| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version | ||||||||||
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:
nil if a server cannot
be created)
nil only when the
value of the open argument is
:port)
nil only when the
value of the open argument is
:listener)
Additional error information may be returned as fifth and subsequent values.
The keyword arguments are:
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.
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.
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.
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.
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.
nil or a
string naming the host where the server is advertising.
nil or a
port number of the port where the server is advertising.
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.
rpc-socket-server.
rpc-datagram-server; in other
cases, it is ignored.
((symbol
string) ...) each pair in the list is passed to export-remote-symbol when
a connection port is created.
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.
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.
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.
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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version | ||||||||||