make-rpc-server

Arguments: port-class &key name open local-host local-port limit max timeout home re-connect begin connect-action connect-function connect-args debug verbose mode export message-timeout message-length certificate key other-certificates tester passcode confirm &allow-other-keys

This function creates a server object appropriate for the specified port-class. The port-class argument may be nil. In that case the default port-class is rpc-socket-server.

When the port-class argument is a subtype of rpc-socket-server, then an instance of a stream socket server is created. When the port-class argument is further a subclass of with-rpc-server-enabler (such as rpc-socket-server-with-enabler), additional keyword arguments tester and passcode are supported. They are described below with the other keyword arguments.

When the port-class argument is a subtype of rpc-datagram-server, then an instance of a datagram connection server is created. Note that when creating a datagram connection server, no value should be specified for the name. The name of datagram servers and ports is always generated from the host and port information. Since each RPC call looks like a new connection to a server, the limit argument should be normally nil or a large number.

This new server object must be activated with a call to rpc-open-listener or rpc-open-server. If the open argument is :listener then rpc-open-listener is called implicitly. If the open argument is :port then rpc-open-server is called implicitly.

Multiple values are returned:

1. the server-instance (nil if a server cannot be created)
2. the port-instance (non-nil only when the value of the open argument is :port)
3. the listener-process (non-nil only when the value of the open argument is :listener)
4. error-code

Additional error information may be returned as fifth and subsequent values.

The keyword arguments are:

• name: when port-class is a subclass of rpc-socket-server (or nil), name may be a nil (or omitted), a string, a symbol (whose print name is used), or a function of no arguments that returns a string. The name argument is used to produce a string naming the server. If nil, a name is generated.

  The server name must be unique in every active rpc-port connection in a set of connected Lisp images. The default name is likely to be unique but is not guaranteed to be so. If distinct connections have identical names, an error is signaled when the conflict is detected, normally when a connection is opened.

  When port-class is a subclass of rpc-socket-server, no value should be specified for name. The name of datagram servers and ports is always generated from the host and port information.

• limit: the total number of distinct connections allowed over the life of the server. nil means no limit. When port-class is a subclass of rpc-datagram-server, limit should be nil or a large number since each datagram call counts as a separate connection.
• max: the number of simultaneous active connections allowed.
• re-connect: when non-nil allows client to disconnect and reconnect. When nil, the client may connect exactly once. Non-nil values are :on-demand, :demand, :first-use, and :explicit. The default is :demand. When port-class is a subclass of rpc-datagram-server, this argument is ignored and the setting is always :demand.
• home: may be a string, a symbol or a function. The value is used as a starting point when generating a unique name for a new connection.

  The home name must be unique in every active rpc-port connection in a set of connected Lisp images. The default name is likely to be unique but is not guaranteed to be so. When many communicating Lisp images are created in a short time interval, it is good practice to supply a unique home name in each Lisp image. The internal algorithm will guarantee uniqueness in each Lisp image, and the unique home prefixes will guarantee uniqueness in the entire set.

  If distinct connections have identical names, an error is signaled when the conflict is detected, normally when a connection is opened.

  When port-class is a subclass of rpc-datagram-server, this argument is ignored because the home name of datagram ports is always generated.

• if-error: may be :close or :shutdown, default is :close. If a socket or protocol error is detected, the connection is closed temporarily (until a re-connect) or shut down permanently.
• connect-action, connect-function and connect-args: these are used at the time of connection (see rpc-open-server).
• begin: when t causes sender and receiver processes to be started as soon as a connection is made. If the open argument is non-nil, then begin is set to t unless explicitly specified as nil.

  When port-class is a subclass of rpc-datagram-server, this argument is ignored.

• local-host: nil or a string naming the host where the server is advertising.
• local-port: nil or a port number of the port where the server is advertising.
• verbose and debug: these arguments are passed to the connected port.
• mode: specifies the default handling of recursive remote calls. When port-class is a subclass of rpc-socket-server, the choices for mode are:
  • :nested - a call back to the calling host is handled in the same dynamic environment where the initial call was made. Subsequent recursive calls build a chain of nested dynamic environments on each host.
  • :parallel - each call from a remote host is executed in a new Lisp process.
  • :blocking - recursive calls are prohibited.

  When port-class is a subclass of rpc-datagram-server, the mode is :blocking and the mode argument is ignored.

• message-timeout: the value is inherited by any ports created for new connections to the server. The message-timeout value is a default timeout value for any RPC call made on a port. Ignored when port-class argument is a subtype of rpc-socket-server.
• message-length: specifies the longest incoming message allowed (the units are octets). Note that a datagram rpc call must be entirely contained in one message. The default value is 4096. This argument is meaningful only when the value of the port-class argument is a subtype of rpc-datagram-server; in other cases, it is ignored.
• export: a list of the form ((symbol string) ...) each pair in the list is passed to export-remote-symbol when a connection port is created.
• certificate: when port-class argument is a subclass of rpc-socket-server, this argument is used to specify a secure socket (SSL) connection. If the argument is nil, an ordinary socket connection is used. If the argument is non-nil, make-ssl-server-stream is called immediately after accepting a socket connection. The certificate argument and the key and other-certificates arguments are passed to make-ssl-server-stream to specify the parameters of the secure connection.

  When port-class is a subclass of rpc-datagram-server, this argument, as well as the key and other-certificates arguments are ignored.

• key: when the certificate argument is used to specify a secure connection, this argument is passed to make-ssl-server-stream. Otherwise this argument is ignored.
• other-certificates: when the certificate argument is used to specify a secure connection, this argument is passed to make-ssl-server-stream. Otherwise this argument is ignored.
• tester (this argument is only used when port-class is a subclass of with-rpc-server-enabler, for example, when it is an instance of rpc-socket-server-with-enabler): the value of this argument should be a symbol naming a function of two arguments that returns nil or non-nil. The default is eql.
• passcode (this argument is only used when port-class is a subclass of with-rpc-server-enabler, for example, when it is an instance of rpc-socket-server-with-enabler): the value of this argument should be an atom or a list of atoms.

  When the value is a single atom, the first action of a client must be to call rpc-send-request with the value of the name  :enable-client. The argument must match the passcode value with the value of tester as the test function. Multiple clients may connect using the same passcode (subject to the limit and max constraints).

  When the value is a list, each client must also send an :enable-client request. The argument must be one of the items in the list to enable the client connection. When a client connects, the matching passcode is removed from the list. In this way, the server accepts connections only from a fixed set of distinct clients.

• confirm: when this argument is non-nil, the Lisp RPC protocol includes additional confirmation messages that track the progress of a remote call in more detail (see rpc-query for more details). The default value is nil.

  A non-nil value may be applicable when using a very slow network connection. In such cases more detailed progress information could be useful.

  This argument was not available in releases prior to 6.2, where the function define-rpc-server worked as if this argument was specified non-nil.

See also rpc.htm for general information on the Remote Procedure Call utility in Allegro CL.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.