ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

# client-end-all

Generic Function, net.rpc package

Arguments: &optional kill wait

This function terminates all known client images and closes the control server. This function returns `nil` if all sub-processes have ended. It returns an integer process id if some sub-processes are still running.

The optional kill and wait arguments are passed in the call to client-exit for each known client. The default for both is `t`, which means an attempt is made to have the client exit using an rpc call, and if that fails an attempt is made to kill the client using the OS kill functionality.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-exit

Function, net.rpc package

Arguments: client &key wait kill

This function causes a client image to exit. It returns one of the keywords `:terminating`, `:terminated`, `:closing`, or `:closed`.

#### The client argument

The client argument must be a client-lisp instance. The wait argument may be `nil`, a positive integer, the keyword `:wait`, or any other non-`nil` value.

If the client instance is already marked as terminated, the function returns `nil` immediately.

#### The wait keyword argument

If the wait argument is `nil`, the value returned is `:closing`. If the wait argument is a positive integer, it is the number of seconds to wait. If the wait argument is `:wait`, the wait interval is indefinite. If the wait argument is any other non-`nil` value, the wait interval is 30 seconds.

If at the end of the wait interval the connection to the client still appears to be open, the value returned is `:timeout`; otherwise the value is `:closed`.

#### The kill keyword argument

The default behavior of client-exit (when kill is `nil`) is to call the client Lisp and request that it terminate (if the keep flag, returned by client-lisp-keep, is `nil`). When the kill argument is non-`nil` some more aggressive steps may be taken, such as calling the Operating System kill command. The table below lists the possible strategies.

Value of kill argument | Keep Flag Nil | Keep Flag T
End with call | OS Kill | End with call | OS Kill
`nil` | yes | no | no | no
`:force` | yes | no | yes | no
`:kill` | no | yes | no | no
`:killall` | no | yes | no | yes
`:all` | yes | yes | yes | yes
other non-`nil` | yes | yes | no | no

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-funcall

Function, net.rpc package

Arguments: client-op &rest args

This function calls a function in the client image and returns the values.

The client argument must be a client-lisp instance.

The op argument may be a symbol, a string, or a remote object instance. A symbol denotes the corresponding symbol in the client image. A string is decoded with read-from-string in the client image; the result should be a symbol. A remote object instance must denote a funcallable object in the client image.

The remaining arguments are the arguments passed to the function in the client image.

This function should be called only after client-ready-p returns `t`. If called when the client is not ready, an error will be signaled.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-data

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the accessor to the data slot of a client-lisp instance. It returns the data slot of the client-lisp instance. The slot is initialized with the data argument to run-other-client. Can be used with setf.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-errors

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the accessor to the errors slot of a client-lisp instance. It returns the list of error objects returned from the client image.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-keep

Generic Function, net.rpc package

Arguments: client-lisp-instance

This accessor returns (or modifies) the `client-lisp-keep` slot of an instance of client-lisp. When this slot is non-`nil`, the function client-end-all does not call client-exit for the client image, and does not attempt to kill the client process if client-exit is not sufficient.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-key

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the reader for the key slot of a client-lisp instance. It returns the key slot of the client-lisp instance. The slot is initialized when a client-lisp instance is created.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-name

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the reader for the name slot of a client-lisp instance. It returns the name slot of the client-lisp instance. The slot is initialized with the name argument to run-other-client.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-port

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the reader for the port slot of a client-lisp instance. It returns the rpc port instance used to communicate with the client Lisp.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-rc

Generic Function, net.rpc package

Arguments: client-lisp-instance

This accessor returns (or modifies) the `client-lisp-rc` slot of an instance of client-lisp. This slot is initially `nil`. It is set to the return code from the client Lisp image when the image is terminated.

In some OS environments and situations the value may be unreliable or never set even when the client Lisp process has terminated.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-start

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the accessor to the start slot of a client-lisp instance. It returns the start slot of the client-lisp instance. The slot is initialized with the start argument to run-other-client.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-lisp-verbose

Generic Function, net.rpc package

Arguments: client-lisp-instance

This is the accessor to the verbose slot of a client-lisp instance. It returns the verbose slot of the client-lisp instance. The slot is initialized with the verbose argument to run-other-client.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# client-ready-p

Function, net.rpc package

Arguments: client &optional wait

This function queries a client instance and returns `t` when the client image is ready to receive or send information from or to the control process. It returns `t` if the client image is ready and responding to calls. It returns `nil` and a second value if the client is not ready. The second value is one of the keywords `:closed`, `:waiting`, or `:timeout`.

The client argument must be a client-lisp> instance.

The wait argument can be `nil`, a number, the keyword `:error`, or another non-`nil` value. The default it `t`. If the wait argument is `nil`, the function returns immediately. If the wait argument is a number, it is the number of seconds to wait (until the client is ready). If the wait argument is `:error`, then an error of type `rpc-cluster-error` with error-code `:rpc-other-client-not-ready` is signaled if the client is not ready. If the wait argument is some other non-`nil` value, the wait interval is 60 seconds. The default is `t`, for a 60 second interval.

If the client image is ready, the returned value is `t`. If the client image is not ready, the two returned values are `nil` and a keyword:

- `:waiting`: waiting for a signal from the client image
- `:timeout`: waiting interval expired *`:closed`: client image is no longer running, or connection was lost and cannot be re-established

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# def-remote-function

Macro, net.rpc package

Arguments: name arglist &key port result mode destination close final

This macro defines a Lisp function that will perform a remote call when it is called. If the port argument is omitted, the call is made through the default connection. If the port argument is specified, it is evaluated at each call to yield an rpc-port instance. If the port instance is a server port, it must be connected. If the port instance is a client port, it will be connected if necessary. The other keyword arguments are expressions that modify the remote call.

If the name argument is a symbol, the same symbol is assumed to exist in the called image. If the name argument is a list, the first element is the local name of the function. The remainder of the list is like a call to rref and defines the function to be called in the remote image. The most reliable and case portable way to reference a remote function is with the name argument:

       (local-name "ppp::nnnnn")

where ppp is the package name and nnnnn is the symbol name of the remote function.

The arglist is similar to a defun lambda list but &aux variables are not allowed, default and supplied-p variable are not allowed on optional or keyword parameters. If a lambda list item is a symbol (not a keyword) or `nil`, that argument position is converted by default rules. If a lambda list item is a keyword, that keyword is treated as the :type argument in a call to rref when converting that argument position. If a lambda list item is a list, that list is treated as the tail of a call to rref `(rref arg :type . list)`.

The position after &rest has additional semantics. If the item after &rest is a symbol (not a keyword) or `nil`, then each item in the argument list of the call is encoded as a separate argument to the remote call. If the item after &rest is a keyword, then each item in the argument list of the call is encoded separately according to the keyword. If the item after &rest is a list beginning with :rest, then a single item is encoded and passed to the remote call. Any other list after &rest is applied individually to any items in the actual call argument list.

The positions after &key have additional semantics. A symbol (not a keyword) denotes a keyword parameter passed by default rules. A list consists of a keyword variable followed by conversion advice.

    (def-remote-function foo (:ref-only :ref-only) :result :ref-only)

This call defines a function foo that is called foo in the remote image too. It expects two arguments that must be both passed as references and it always returns a reference. Thus (foo 1 2) would signal an error before the call was even made since fixnums cannot be passed by reference.

    (def-remote-function bar (nil &key key1 (key2 :ref)))

This call defines a function bar that is called bar in the remote image too. The remote function will get the first argument by default rules, the keyword argument :key1 will be passed by default rules, the keyword argument :key2 will be passed as a reference if possible.

    (def-remote-function baz (&rest (:rest nil)))

This call defines a function baz that is called baz in the remote image too. In the local image, baz may be called with any number of arguments. The remote version of baz will get a single argument which is the list of arguments to local baz passed as a single object by default rules. If the list is one that may be passed by value, remote baz will get a copied list, otherwise remote baz will get a remote reference.

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

# def-remote-method

Function, net.rpc package

Arguments: name [mod] lambda-list &key port result mode destination close final

This macro is like def-remote-function but defines a method instead. The lambda list may be a method lambda list with specializers. In addition, a keyword in the lambda list is treated like a :type keyword to rref. A list always denotes a specialized argument, but any items beyond the second element are treated as keyword arguments to rref. The keyword arguments are the same as those for def-remote-function.

    (def-remote-method
        bar :before ((x local-class) (y t :ref-only) :copy-only))

This call defines a :before method with three arguments. The first is specialized on local-class and is passed by default rules. The second argument is unspecialized and is passed by reference only. The third argument is unspecialized and is passed only by value.

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

# define-remote-class

Function, net.rpc package

Arguments: class-name string

This function calls import-remote-class with the current default port. It returns the class name. We recommend users use import-remote-class instead of this function.

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

# define-rpc-client

Function, net.rpc package

Arguments: *port-class &key home remote-host remote-port poll-interval poll-count if-error re-connect begin open verbose debug mode export message-tiemout server message-length ssl

This function has been renamed make-rpc-client, as that name more closely follows standard Common Lisp naming conventions for an operator that creates an object. This name is preserved for backward compatibility. Users are encouraged to use the new name. See make-rpc-client for a description. This symbol will be deleted in a future release.

# define-rpc-server

Function, net.rpc package

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 &allow-other-keys

This function has been renamed make-rpc-server, as that name more closely follows standard Common Lisp naming conventions for an operator that creates an object. This name is preserved for backward compatibility. Users are encouraged to use the new name. See make-rpc-server for a description. This symbol will be deleted in a future release.

# eval-string

Function, net.rpc package

Arguments: string &optional (eof-error-p t) eof-value &key (start 0) end preserve-whitespace (read-error-p t) read-error-value (eval-error-p t) eval-error-value

This function reads the contents of the string string and then evaluates the resulting object. It returns the result(s) of the evaluation. This function is useful when making complex remote calls.

The arguments eof-error-p, eof-value, start, end, and preserve-whitespace are passed to read-from-string and control the values returned from read-from-string.

If read-from-string returns a value, it is passed to eval. If read-from-string signals an error, then the behavior is controlled by the read-error-p argument. If the value is non-`nil` (the default), then the same error is signaled from eval-string. If the value is `nil`, then the value of the read-error-value argument is passed to eval.

If the call to eval returns values, those values are returned from eval-string. If the call to eval signals an error, then the behavior is controlled by the eval-error-p argument. If the value is non-`nil` (the default), then the same error is signaled from eval-string. If the value is `nil`, then the value of the eval-error-value argument is returned as the single value of eval-string.

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

# export-remote-symbol

Function, net.rpc package

Arguments: home-location symbol export-string &optional propagate

This function defines a mapping from symbols that name a class to a string. It returns export-string. home-location must be an instance of rpc-port or of rpc-port-server (its presence allows the generic function to behave differently on the two classes).

A local reference to a class is identified in an outgoing remote reference by a string. The default string is the "~A" representation of the class name. If an export-string is defined for the class, then the export-string is sent instead.

To avoid ambiguities or conflicts caused by package and case differences between remote images, an application can use export-remote-symbol in the sender to define unique class identifier strings and import-remote-class in the receiver to interpret these unique strings.

### Method for: (rpc-port-server t t)

This method updates the table stored in the rpc-port-server instance. The table is copied to any new rpc-port instances created from the server. If the propagate argument is non-nil, then all active ports created from this server are updated as well.

### Method: (rpc-port t t)

This method updates the table in the specified rpc-port instance. The propagate argument is ignored.

### Example

Suppose the string "bar" is not sufficient or appropriate to identify the correct class when arriving from Image A to Image B. For example, there may be symbols `pkg1::bar` and `pkg2::bar` in image A, and an unrelated symbol `pkg3::bar` in image B. Image A can define a unique string that identifies the desired class `bar` uniquely to image B, for example "bar-from-a".

Then image A would say:

    (export-remote-symbol port-to-b 'bar "bar-from-a")
    (rcall 'foo (make-instance 'bar))

Image B would say:

    (import-remote-class port-to-a 'far-bar "bar-from-a")

and the function foo gets the correct class instance.

See also the example in the description of import-remote-class.

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

# grab-gate

Generic Function, net.rpc package

Arguments:

No longer supported.

In the initial release of the Allegro CL RPC module (see rpc.html), this function was one of several operators (along with with-access-gate, with-access-gate*, and ungrab-gate) provided as an interface to multiprocessing gate objects (see Gates (both models) in multiprocessing.html). However, we have determined that those operators were not useful for that purpose. The symbols naming them have been unexported and the interface is no longer supported.

# import-remote-class

Generic Function, net.rpc package

Arguments: home-location class-name import-name &optional propagate

This function defines a mapping from the string to the local class named by class-name. It returns the class name. This class must be a sub-class of rpc-remote-ref or an error is signaled. home-location must be an instance of rpc-port or of rpc-port-server (its presence allows the generic function to behave differently on the two classes).

When a remote reference to a class arrives at a port, the class is identified by a string. This string is compared (with string-equal) to the import-name strings defined by this function. If a match occurs, an instance of the corresponding class-name is created instead of a direct instance of rpc-remote-ref.

To avoid ambiguities or conflicts caused by package and case differences between remote images, an application can use export-remote-symbol in the sender to define unique class identifier strings and import-remote-class in the receiver to interpret these unique strings.

### Method: (rpc-port-server t t)

This method updates the table stored in the rpc-port-server instance. The table is copied to any new rpc-port instances created from the server. If the propagate argument is non-nil, then all active ports created from this server are updated as well.

### Method: (rpc-port t t)

This method updates the table in the specified rpc-port instance. The propagate argument is ignored.

### Programming Note and Warning:

Subclasses of rpc-remote-ref must not be instantiated by application programs. Any instance of rpc-remote-ref created by a direct call to make-instance will cause serious errors in the application.

Instances of rpc-remote-ref (and any subclasses) are only created when a remote reference arrives at an rpc-port, or when an application needs to create an explicit wrapper with a call to rref or rpc-ref.

### Example

Image A calls image B with:

    (rcall 'foo (make-instance 'bar))

In image B, the function foo gets an instance of rpc-remote-ref as its one argument x. `(rr-type x)` returns the string "bar". Image B can only obtain additional information about the object x by calling back to A.

But image B could also do as follows:

    (defclass far-bar (rpc-remote-ref) ())
    (import-remote-class port-to-a 'far-bar "bar")

At this point, the function foo gets an instance of `far-bar` as an argument. This is a local class that may be used to dispatch appropriate methods in image B.

For example, in image A, the class `bar` may have a slot accessed with accessor count. One way to call this accessor from image B is to use

    (rcall 'count x)

But since import-remote-class caused a local class to be instantiated, we can define in image B

    (defmethod count ((x far-bar)) (rcall 'count x))

and access the slot with `(count x)`.

See export-remote-symbol for what to do if the class name represented simply as the symbol name might cause ambiguity.

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

# make-rpc-client

Function, net.rpc package

Arguments: port-class &key home remote-host remote-port poll-interval poll-count if-error re-connect begin open verbose debug mode export message-tiemout server message-length ssl passcode confirm

This function creates an rpc-port instance appropriate for the specified port-class ready to connect to an advertising host. The value returned is the rpc-port instance if the operation succeeds, or `nil` and a second value that describes the cause of the failure if the operation fails.

When the port-class argument is a subtype of rpc-socket-port, then an instance of a stream socket client is created. Note that in this case, no value should be specified for the server keyword argument, which is used for datagram socket clients only. When port-class is also a subclass of with-rpc-port-enabler (such as rpc-socket-port-with-enabler), a passcode keyword argument is also accepted. It is described with the other keyword arguments below.

When the port-class argument is a subtype of rpc-datagram-port, then an instance of a datagram socket client is created. Note that in this case, no value should be specified for the home keyword argument, since the home name of a datagram connection is constructed from the local and remote hosts and ports. The server keyword argument can be a rpc-datagram-server instance or the name of one. The server instance is used for incoming messages and the client instance is used for outgoing messages.

The actual connection happens when rpc-open-client is called. If the open argument is non-`nil`, an implicit call to rpc-open-client is made.

The port-class argument may be `nil` to denote the default port class, rpc-socket-port.

The keyword arguments are generally similar to those of make-rpc-server. They are:

- home: same as for make-rpc-server.

- remote-host: a string naming the host where the server is listening. The default is "localhost".

- remote-port: a required number, the port number of the port at which the server is listening.

- poll-interval: the number of seconds to wait between attempts to connect.

- poll-count: `nil` or a number. When `nil`, try only once; when a number, try that many times.

- if-error: same as for make-rpc-server.

- re-connect: `nil` (allow only one explicit connection); `:on-first-use` or `:first-use` (allow only one implicit connection); `:on-demand`, `:demand` (re-connect when necessary) or `:connect` (attempt to re-connect and if the re-connect fails, tries a new connect).

- begin: same as for make-rpc-server.

- open: when non-`nil`, call rpc-open-client.

- verbose: same as for make-rpc-server.

- debug: same as for make-rpc-server.

- mode: same as for make-rpc-server.

- export: a list of pairs passed to export-remote-symbol when a connection is established.

- message-timeout: when the port-class argument is a subtype of rpc-datagram-port, same as for make-rpc-server. This argument is ignored when the port-class argument is a subtype of rpc-socket-port.

- message-length: when the port-class argument is a subtype of rpc-datagram-port, same as for make-rpc-server. This argument is ignored when the port-class argument is a subtype of rpc-socket-port.

- server: this argument is used only when port-class is a subclass of rpc-datagram-port. The value may be `nil`, the name of an rpc-datagram-server instance or an rpc-datagram-server instance. If `nil`, the host and port arguments must be sufficient to create an rpc-datagram-server instance.

- ssl: this argument is used only when port-class is a subclass of rpc-socket-port. When non-`nil`, call make-ssl-client-stream immediately after connecting to a server

- passcode (this argument is only used when port-class is a subclass of with-rpc-port-enabler, for example, when it is an instance of rpc-socket-port-with-enabler): the passcode argument sent in an implicit `:enable-client` request that is sent after a connection is established.

- 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 this function worked as if this argument was specified non-`nil`.

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

# make-rpc-server

Function, net.rpc package

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-client-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.html for general information on the Remote Procedure Call utility in Allegro CL.

# other-client-error

Function, net.rpc package

Arguments: &rest edata

This function notifies the control process that some error has occurred in the client image. The edata argument is data that describes the error.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# other-client-exit

Function, net.rpc package

Arguments: &rest edata

This function notifies the control process and then exits. The edata argument is data that describes the exit reason. Since the client image is exiting, only data transmitted by value makes sense.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# rapply

Function, net.rpc package

Arguments: function-ref &rest arg-refs

This function, along with the others listed at the end of this page, is used to make remote calls within the dynamic scope of a with-remote-port form. It returns the value(s) of the remote call.

The first argument is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function. Remote references are described in Data representation in rpc.html. The remote reference is resolved to a function in the remote environment, and the function is called with the arguments passed in the call. The value of the expression is the value or values returned by the remote call. These may be local values or remote references.

This function performs its call like apply, returning the value to the caller.

See also rcall, rcall-ignore, rcall-one-way, rapply, rapply-ignore, and rapply-one-way.

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

# rapply-ignore

Function, net.rpc package

Arguments: function-ref &rest arg-refs

This function, along with the others listed at the end of this page, is used to make remote calls within the dynamic scope of a with-remote-port form. This function returns no values.

The first argument is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function. Remote references are described in Data representation in rpc.html. The remote reference is resolved to a function in the remote environment, and the function is called with the arguments passed in the call. The value of the expression is the value or values returned by the remote call. These may be local values or remote references.

This function performs its call like apply, but specifies that the returned value will be ignored, and therefore does not need to be returned to the caller. If the return value is large or network latency is significant, this may be a very effective optimization.

See also rcall, rcall-ignore, rcall-one-way, rapply, and rapply-one-way.

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

# rapply-one-way

Function, net.rpc package

Arguments: function-ref &rest arg-refs

This function, along with the others listed at the end of this page, is used to make remote calls within the dynamic scope of a with-remote-port form. This function returns no values.

The first argument is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function. Remote references are described in Data representation in rpc.html. The remote reference is resolved to a function in the remote environment, and the function is called with the arguments passed in the call. The value of the expression is the value or values returned by the remote call. These may be local values or remote references.

This function performs its call like apply, but returns immediately without waiting for any return value. (Contrast with rapply-ignore which ignores its return value but does not return immediately.) If the value to be returned is large or network latency is significant, this may be a very effective optimization.

Note that the execution timing of one-way calls may be indeterminate since each is performed in a separate Lisp thread (in the default case). It is quite possible for a second call from A to be executed before a first call from A.

See also rcall, rcall-ignore, rcall-one-way, rapply, and rapply-ignore.

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

# rcall

Function, net.rpc package

Arguments: function-ref &rest arg-refs

This function, along with the others listed at the end of this page, is used to make remote calls within the dynamic scope of a with-remote-port form. This function returns the value(s) of the remote call.

The first argument is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function (see Operator Conversion in rpc.html). Remote references are described in Data representation in rpc.html. The remote reference is resolved to a function in the remote environment, and the function is called with the arguments passed in the call. The value of the expression is the value or values returned by the remote call. These may be local values or remote references.

This function performs its call returning the value to the caller.

See also rcall, rcall-ignore, rcall-one-way, rapply, rapply-ignore, and rapply-one-way.

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

# rcall-ignore

Function, net.rpc package

Arguments: function-ref &rest arg-refs

This function, along with the others listed at the end of this page, is used to make remote calls within the dynamic scope of a with-remote-port form. This function returns no values.

The first argument is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function. Remote references are described in Data representation in rpc.html. The remote reference is resolved to a function in the remote environment, and the function is called with the arguments passed in the call. The value of the expression is the value or values returned by the remote call. These may be local values or remote references.

This function performs its call but specifies that the returned value will be ignored, and therefore does not need to be returned to the caller. If the return value is large or network latency is significant, this may be a very effective optimization.

See also rcall, rcall-ignore, rcall-one-way, rapply, rapply-ignore, and rapply-one-way.

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

# rcall-one-way

Function, net.rpc package

Arguments: function-ref &rest arg-refs

This function, along with the others listed at the end of this page, is used to make remote calls within the dynamic scope of a with-remote-port form. This function returns no values.

The first argument is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function. Remote references are described in Data representation in rpc.html. The remote reference is resolved to a function in the remote environment, and the function is called with the arguments passed in the call. The value of the expression is the value or values returned by the remote call. These may be local values or remote references.

This function performs its call but returns immediately without waiting for any return value. (Contrast with rcall-ignore which ignores its return value but does not return immediately.) If the value to be returned is large or network latency is significant, this may be a very effective optimization.

Note that the execution timing of one-way calls may be indeterminate since each is performed in a separate Lisp thread (in the default case). It is quite possible for a second call from A to be executed before a first call from A.

See also rcall, rcall-ignore, rapply, rapply-ignore, and rapply-one-way.

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

# rclose

Function, net.rpc package

Arguments: &key flush abort all atop final

This function operates on the default RPC port bound to *rpc-port*. It is a shorthand for rpc-close when *rpc-port* is the port to work on.

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

# register-client-lisp

Generic Function, net.rpc package

Arguments: client

This method is called in the control image when a client image connects for the first time. The default primary method simply returns `t`. A user-defined method returns `t` to accept a registration or `nil` to refuse it.

Applications can define a method specialized on the client-lisp class to manage the client registration. If the returned value is `t`, the client is accepted and the content of client-lisp-start is returned to the client. If the returned value is `nil`, the client is not registered, and a throw is returned to the client.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# ropen

Function, net.rpc package

Arguments:

This function is a shorthand for a call to rpc-open-client when the port to work on is the value of *rpc-port* (typically by with-remote-port). Any keyword arguments are used to update the port instance slots.

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

# rpc-begin

Generic Function, net.rpc package

Arguments: (port rpc-port) &key (timeout 15) &allow-other-keys

This method starts the Lisp processes necessary to sustain an RPC connection. It is called automatically from rpc-open-server or rpc-open-client when port is a subclass of rpc-socket-port and when the begin keyword argument is omitted or non-`nil`. This function must be called explicitly if for some reason the application chooses to open an RPC port but does not start the processes. One reason to call rpc-begin separately could be to do additional tests on the connection streams before the RPC processes are enabled.

Returns `t` (or other non-`nil`) if the operation completed successfully. Returns `nil` and a second value describing the failure.

This method is not called when port is a subclass of rpc-datagram-port because sender and receiver process are not created in this case.

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

# rpc-close

Generic Function, net.rpc package

Arguments: (port ) &key flush abort all stop final wait

There are several methods specialized on the port argument. The behavior of the function and meaning of the arguments varies with the type of the port argument.

The wait argument specifies whether to wait for the operation or operations to complete; it can also specify how long to wait. A value of `nil` causes one or more operations to be initiated but control returns almost immediately to the caller. If the value is a positive number, it is the number of seconds to wait.
Any other non-`nil` value specifies an indefinite wait.

### For (port rpc-socket-server)

Arguments (port rpc-socket-server) &key flush abort all stop final wait

If the all argument is non-`nil`, then rpc-close is called on each port opened by this server. The flush, abort and final arguments are passed down to each port call.

If the stop argument is the keyword `:final`, then stop advertising and discard the server entirely. To cause a clean shutdown, the all and wait arguments should be non-`nil`; if all is `nil`, then any open ports are shut down unilaterally and any activity is aborted; if wait is `nil`, then it is also possible to cause open ports to be shut down unilaterally.

If the stop argument is any other non-`nil` value, then simply stop advertising. If a listener process is running, then stop the listener process as well. A call to rpc-open-server or rpc-open-listener will resume advertising.

If the wait argument is non-`nil`, then the outermost call to rpc-close, and any implicit calls to rpc-close, will return only after each operation is completed. When the abort argument is non-`nil`, the remote process may still be closing down the connection.

A port is finally closed, when a call to rpc-open-p returns one of the keywords `:idle` or `:closed`.

### For (port rpc-port)

Arguments (port rpc-port) &key flush abort all stop final wait

Close an rpc-port. If abort is non-`nil`, shut down the port without attempting any further communication.

If flush argument determines what to do with pending messages and active worker threads. The value of flush can be `:kill`, `:runout`, `nil` or any other non-`nil` value.

If the value of flush is `:kill`, then any active threads are killed and any pending messages are discarded. If the value is `:runout`, then active threads are allowed to run to completion, but the close operation does not wait for the threads to finish (even if wait is non-`nil`), and the threads do not attempt to send the result to the remote caller.

If the value is `nil`, then the port is closed only after all pending messages are handled and all active threads terminate.

If the value is any other non-`nil` value, pending messages are discarded, but active threads are left running. Note that when the call in an active thread ends, it will signal an error since the result cannot be sent back through a closed port -- this error is ignored unless one of the debug options is enabled.

If abort and flush are `nil`, close the port by sending a disconnect message after all pending messages are sent. When the disconnect message is acknowledged, close the port.

If the re-connect option of the port is non-`nil`, the port may be re-connected later, but if the option is `nil` or if final is non-`nil`, the port is closed with no more connections allowed.

If stop is non-`nil`, call rpc-close on the server from which the port was derived.

If all is non-`nil`, call rpc-close for all ports derived from the same server as this one.

As with the method on rpc-socket-server, if the wait argument is true, the call to rpc-close should not return until the close operation is completed. Note that with a slow connection even when rpc-close returns, the remote host may still be in the process of closing down. If the wait argument is `nil`, the call returns while the closing takes place. The port is finally closed when a call to rpc-open-p returns one of the keywords `:idle` or `:closed`.

### For (port rpc-datagram-server)

Arguments (port rpc-datagram-server) &key flush abort all stop final wait

When called with the stop argument non-nil, this method stops the listener. Otherwise, this method has no effect.

### For (port rpc-datagram-port)

Arguments (port rpc-datagram-port) &key flush abort all stop final wait

Since a datagram port is closed after each RPC message, this method is effectively a no-op.

### For (port (eql :all))

Arguments (port (eql :all)) &key flush abort all stop final wait

Call rpc-close for all known servers. The keyword arguments are passed down in each call. The wait argument, when non-nil, specifies that the call to rpc-close should not return until the close operation is completed. Note that with a slow connection even when rpc-close returns, the remote host may still be in the process of closing down. If the wait argument is nil, the call returns while the closing takes place. The port is finally closed when a call to rpc-open-p returns one of the keywords `:idle` or `:closed`.

### For (port (eql :reset))

Arguments (port (eql :reset)) &key flush abort all stop final wait

This closes all RPC activity in a Lisp image. It is equivalent to

    (rpc-close :all :flush t :abort t :all t :stop t :final t :wait t).

### Programming Note

How to close an ACLRPC connection gracefully:

1. One side makes a remote call to the other to notify the other side that the connection is closing, and then calls

       (rpc-close port :wait t)

2. When the other side receives the notification, it calls

       (rpc-close port :wait t)

The notification must be adapted to the needs and style of the application. Some possibilites are setting a special variable, opening a Lisp gate, modifying some data structure.

To close the server and all connections gracefully:

    (rpc-close server :stop :final :all t :wait t)

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

# rpc-do-invoke

Generic Function, net.rpc package

Arguments: port op args

This function is called each time a remote call, sent with rcall or rpc-invoke, is executed at the receiving end.

The default method simply calls apply to apply the op argument to the argument list args (note that args is a single argument, not an &rest).

We provide a method that implements the behavior of the with-rpc-port-enabler mixin class. An application can define methods on subclasses of rpc-port to control access to called functions in other ways.

### Around Method: (with-rpc-port-enabler t t)

This method signals an error unless the port has been enabled with an `:enable-client` request with an appropriate passcode.

This is an `:around` method to ensure that the method body is called before any primary methods, regardless of the class precedence list. The application may define a primary method to add other filtering algorithms.

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

# rpc-do-request

Generic Function, net.rpc package

Arguments: port (name t) arg &rest keys &allow-other-keys

This function is called each time a remote request, sent with rpc-send-request, is executed at the receiving end.

The default method simply returns 0.

We provide two methods that implement the behavior of the with-rpc-port-enabler mixin class. An application can define methods on subclasses of rpc-port to control access to the port in other ways.

### Around Method: (with-rpc-port-enabler t t)

This method signals an error unless the port has been enabled with an `:enable-client` request with an appropriate passcode.

This is an `:around` method to ensure that the method body is called before any primary methods, regardless of the class precedence list. The application may define a primary method to add other filtering algorithms.

### Around Method: (with-rpc-port-enabler (eql :enable-client) t)

This method tests the arg argument against the passcode defined in the port.

If the server was defined with a :passcode value that is an atom, then the :tester function is called with arg and passcode. If the function returns a non-nil value, the port is enabled for subsequent requests and remote calls.

If the port was defined with a :passcode value that is a list, then arg is matched with the member function against the list with tester as the test function. If arg is found in the list, the port is enabled, and the matching passcode is removed from the server list.

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

# rpc-enable-client

Generic Function, net.rpc package

Arguments: port passcode

The default method of this generic function does nothing. It returns the first argument.

### Method: (port with-rpc-port-enabler)

This method is called to enable a connection explicitly. This is necessary when the default enable sequence is suppressed in the call to rpc-open-client.

If a passcode is specified, send an `:enable-client` request with the specified passcode.

If passcode is nil, don't send anything. This case makes sense if the application sent an `:enable-client` request explicitly.

Finally, enable the local port for request and invoke callbacks from the server.

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

# rpc-enable-port

Generic Function, net.rpc package

Arguments: port &optional error-p error-val

This function checks a connection and re-establishes it if necessary and possible. If error-p is non-`nil`, an error is signaled if the port cannot be opened. If error-p is `nil`, error-val is returned if the port cannot be opened. If the port is opened, the return value is the open port.

The method when port is a datagram port is a no-op.

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

# rpc-get

Generic Function, net.rpc package

Arguments: (self rpc-port) (m rpc-message) &key (error-p t)

This method is used with the message handle returned by rpc-invoke to extract the result of the remote call. If the state of the message is :rms-done, one or more values are returned, one for each value returned by the remote call.

If the state of the message is :rms-throw, then the effect depends on the thrown result and the error-p argument. If error-p is `nil`, three values are always returned: the tag argument of the throw, the value of the throw, and an unwind-protect flag. When the unwind-protect flag is non-`nil`, the first two values are `nil`; the remote call was terminated by a throw past the return to this caller.

If error-p is non-`nil`, and the tag is non-`nil`, then the throw is continued in the calling environment. Otherwise an error is signaled.

If the state of the message is :rms-error an error is signaled, unless the error-p argument is `nil`. If the error-p argument is `nil`, the value returned is usually a list where the first element is a keyword denoting the error and the second element is a string describing the remote error in more detail.

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

# rpc-invoke

Generic Function, net.rpc package

Arguments: (port rpc-port) op arglist &key *mode (result :copy-maybe) destination (wait t) (error-p t) timeout

This generic function provides a more controlled way of making a remote call than rcall. If wait is non-`nil`, the returned value is the value or values returned from the remote call, when these finally arrive. If wait is `nil`, a value is returned immediately. The value is a message instance that serves as a handle for the call. This handle may be used with the methods rpc-query, rpc-wait, and rpc-get to monitor the progress of the call.

The op is a function reference that may be a string, a symbol, or a remote reference to a string, symbol or function (see Operator Conversion in rpc.html).

Except for datagram ports, the mode argument may be :nest, :parallel, or :block to override the default call mode in the port definition. The destination argument may be :new to specify that the remote call should be handled in a new process regardless of the mode settings.

For datagram ports, the timeout argument overrides the default value in the message-timeout slot of the port. A timeout is signaled as an error.

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

# rpc-local-host

Generic Function, net.rpc package

Arguments: self

If the argument is a server instance, and the server is listening, then the value is local host name. If the server is not listening, the value is `nil`.

If the argument is a client instance, and the client is connected, then the value is the local host name. If the client is not connected, the value is `nil`.

# rpc-local-port

Generic Function, net.rpc package

Arguments: p

If the argument is a server instance, and the server is listening, then the value is the port number where the server is listening. If the server is not listening, the value is `nil`.

# rpc-open-client

Generic Function, net.rpc package

Arguments: (port rpc-socket-port) &key confirm

This function actually makes a connection based on the parameters stored in the port instance specified by the port. Any keyword arguments are used to update the port instance slots. See ropen, which operates on the default RPC port bound to the variable *rpc-port*. Return values are described in the body of the description.

When the port is a subclass of with-rpc-port-enabler (such as rpc-socket-port-with-enabler), and a passcode was defined in the call to make-rpc-client (or in this argument list), we send an `:enable-client` request as soon as the connection to the server is established. Note that the value of the re-connect keyword argument to make-rpc-client can affect the behavior of this function.

If the passcode is `nil`, then the application must call rpc-enable-client explicitly.

The confirm keyword argument: 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.

Arguments (port rpc-datagram-port)

This method is a no-op for datagram connections.

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

# rpc-open-listener

Generic Function, net.rpc package

Arguments: (when server is a rpc-socket-server) (server rpc-socket-server) &key confirm 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

Arguments: (when server is a rpc-datagram-server) (server rpc-socket-server) &key confirm

This function starts a Lisp process that accepts connections from a passive socket. The newly created process (a port instance) is returned but `nil` is returned if the process could not be started. This is the typical method of maintaining an RPC connection both in the stream socket and datagram protocols.

The keyword arguments are the same as make-rpc-server, and are used to update the settings in the server instance. See make-rpc-server for information on the keyword arguments. Only confirm is discussed here.

When a connection is accepted, a server port is created and the connect-function is called if it is specified (see rpc-open-server for more information on the connect-function). The limit count is decremented if limit is non-`nil`. When limit reaches zero, new connections are no longer accepted. The decremented limit persists over closing and re-opening a listener. To reset the limit count, add the limit keyword argument in the call to rpc-open-listener.

The confirm keyword argument: 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.

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

# rpc-open-p

Function, net.rpc package

Arguments: &optional port-or-server verify verbose

This function reports on the state of one or more rpc ports and/or servers. The verbose argument causes output to be printed to the console. The verify argument, when non-`nil`, causes a connection to be verified with a round-trip message. When the first argument is `nil`, this function reports on the state of the default port. The return value depends on argument values.

When the first argument is a datagram port instance, this method will normally return `:idle`.

When the first argument is an rpc-port instance, this function returns two values:

- the state of the port - one of the keywords :idle :connected or `:closed` or some other keywords denoting short-lived connect and disconnect states. If the connection was verified, this value is `:verified`.

- a list of the form (home state role local-port remote-host remote-port).

When the first argument is a server instance, the value is a list of the form `(server-home-name :listening local-port p1 p2 ... )` where p1... are lists describing any ports derived from this server.

When the first argument is `:all`, the value is a list of the form `(s1 s2 ... [clients])` where s1... are reports for all known server instances. The client's entry is there if there are any client ports present. It is a list of the form `(:client-ports nil p1 p2 ... )`.

When the first argument is a string or symbol, the value returned is the rpc-port-server instance, or the rpc-port instance with that home name. All port instances are identified by their unique local home name.

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

# rpc-open-server

Generic Function, net.rpc package

Arguments: (server rpc-socket-server) &key confirm

Arguments: (server rpc-datagram-server) &key confirm

This function accepts one connection from a remote client. In a typical situation, a server would loop on a call to this function. The function rpc-open-listener implements such a loop. This function is useful if an application needs behavior that is not provided by rpc-open-listener.

When server is a subclass of rpc-socket-server, this method waits for a connection and returns the resulting port object.

When server is a subclass of rpc-datagram-server, the effect of this method is to wait for one datagram message to arrive. The message could be a new RPC call, the result of some previous RPC call, or an RPC request. Unless this method is called repeatedly in some loop, the Lisp host will be very unreceptive to remote calls and requests.

The keyword arguments are the same as make-rpc-server, and are used to update the settings in the server instance.

A passive socket is opened if necessary, and closed if appropriate. If begin is t, start receiver and sender processes for the port. The begin argument always defaults to t, unless it is explicitly passed as `nil` in each call.

If connect-action is `:return`, the port object is simply returned as the value of the call.

If connect-action is `:call`, then two values are returned:

- The port instance

- The result of calling the function supplied as connect-function. The connect-function is called with the port instance as the first argument and the value of connect-args as the remaining arguments.

If connect-action is `:process`, then two values are returned:

- The port instance

- An Allegro CL process object - a new process is started and the connect-function is called in the new process with the same arguments as in the `:call` case.

The confirm keyword argument: 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 this function worked as if this argument was specified non-`nil`.

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

# rpc-process-pool

Function, net.rpc package

Arguments: &key limit drop active query flush forget show

This function is used to query and to manage the process pool maintained by the Allegro CL RPC Module. Each new in-bound remote call (a call that is not a callback from an out-bound call) is evaluated in a new Lisp process. In the os-threads model of Lisp multi-processing (see multiprocessing.html), there is some overhead associated with the creation of a new Lisp process. The process pool reduces this overhead by re-using processes.

The keyword arguments are:

- limit: This argument is used to set the limit on the number of idle processes kept in the pool. The initial value is 15. Valid values are integers from 1 to 100. Note that the processes kept in the pool are reserved for remote calls. If there is an OS limit on the number of running processes, then the processes in the pool are included in that limit.
- drop: This argument is used to set the limit on how long idle processes are kept in the pool. The initial value is 15; the units are minutes. Valid values are integers from 0 to 1000000. If this parameter is 0, then processes are discarded as soon as they are done, and the process pool will almost always be empty.
- active: This argument is used to set the limit on the number of processes that will be run simultaneously to handle remote calls. The initial value is 10. Valid values are integers from 1 to 100, but note that the actual number of running processes may be bounded by an OS resource limit.
- query: when a value from the list given below is given for this argument, the value of the function call is the value of a parameter of the process pool. Otherwise the value returned is `nil`. See below for possible values for query and the resulting value of the function call.
- show: When non-`nil`, display the status, parameters and statistics of the process pool on *standard-output*.
- flush: When non-`nil`, discard all the idle processes in the pool.
- forget: When non-`nil`, discard any pending remote calls waiting for a process.
- new: When `:none`, disable the process pool facility. When non-`nil` (but not `:none`), start a new pool. In both cases, all previous statistics are discarded.If the flush and/or forget arguments are non-`nil`, their effect takes place first. If the flush argument is `nil` or omitted, then any idle processes are discarded with a warning. If the forget argument is `nil` or omitted, then any waiting work items are discarded with a warning.

### Possible values for the query argument

If the value of the query argument is one of the listed keywords, rpc-process-pool returns information about the process pool and the status of processes, as described. If the value of the query argument is `nil` or omitted, rpc-process-pool returns `nil`.

Value of query | Value returned by rpc-process-pool
`nil`. This is the default. | `nil`
`:waiting` | Return the number of remote calls waiting for a process at this moment.
`:pool` | Return the number of idle processes in the pool at this moment.
`:running` | Return the number of processes running a remote call at this moment.
`:limit` | Return the limit on the number of idle processes kept in the pool.
`:drop` | Return the limit on how long idle processes are kept in the pool.
`:active` | Return the limit on the number of processes that will be run simultaneously to handle remote calls.
`:max-active` | Return the maximum number of active processes.
`:max-waiting` | Return the maximum number of calls waiting for a process.
`:re-used` | Return the number of times a process was re-used.
`:new` | Return the number of times a process was created.
`:saved` | Return the number of times a process was saved for re-use.
`:killed` | Return the number of times a process was discarded after use.
`:dropped` | Return the number of times a process was discarded from the idle pool

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

# rpc-query

Function, net.rpc package

Arguments: (self rpc-port) (m rpc-message) &rest modifiers

This method is used with the message handle returned by rpc-invoke to query the state of a remote call. The value is a keyword that describes the state of the message. The possible keywords are:

### While a call is in progress:

- `:rms-begin-invoke`: a call has been initiated.
- `:rms-arguments`: the arguments to the call are being transmitted.
- `:rms-invoke-sent`: the entire call has been transmitted.
- `:rms-invoke-confirmed`: the call has been acknowledged by the remote host. This state appears only if the confirm argument of the port is non-`nil`.
- `:rms-receiving-results`: the results are arriving.
- `:rms-result-received`: all the results have arrived. This state appears only if the confirm argument of the port is non-`nil`.

### While a call is completed:

- `:rms-done`: the results have been confirmed and the call has completed successfully.
- `:rms-error-received`: the call is completed, but the remote host is transmitting error information. This state appears only if the confirm argument of the port is non-`nil`.
- `:rms-error`: the call is completed, but the remote host signaled an error.
- `:rms-throw`: the call was cut short by a throw in the remote host.

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

# rpc-ref

Generic Function, net.rpc package

Arguments: (port rpc-port) data &key type symbol-mode package-mode symbol-name symbol-package

This generic function creates an explicit reference object. If no keyword arguments are specified, then a default conversion is performed. The type keyword is defined in the table in Data Type Qualifiers in rpc.html. It is used to control the data conversion explicitly. The other keyword arguments, also described in Data Type Qualifiers in rpc.html, are used only when a symbol reference is created.

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

# rpc-remote-host

Generic Function, net.rpc package

Arguments: self

If the argument is a server instance, the value is `nil`.

If the argument is a client instance, and the client is connected, then the value is the remote host of the connection. If the client is not connected, the value is `nil`.

# rpc-remote-port

Generic Function, net.rpc package

Arguments: self

If the argument is a server instance, the value is `nil`.

If the argument is a client instance, and the client is connected, then the value is the remote port number of the connection. If the client is not connected, the value is `nil`.

# rpc-send-request

Generic Function, net.rpc package

Arguments: (self rpc-port) name arg &key destination wait mode result error-p

A somewhat lighter protocol than rpc-invoke. The name may be any argument suitable for eql method dispatch. The arg may be any data that is passed by value. The returned result is any single object returnable by value. To have an effect, the remote host must have defined one or more rpc-do-request methods specialized on appropriate arguments. The keyword arguments are as in rpc-invoke.

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

# rpc-version

Function, net.rpc package

Arguments: &optional type main-only

This function returns a value that represents the version of Allegro CL RPC in the current Allegro CL image. The type argument is a keyword that determines the type and format of the returned value. If the main-only argument is non-`nil`, the value returned describes only the main version number of the module. It should be possible for two Allegro CL images with different versions to communicate as long as the main version number in both is the same.

The following table show what is returned for various values of type and main-only. Both arguments default to `nil`.

Value of type | Value returned when main-only is nil | Value returned when main-only is non-nil
`:string` | "3.2.2" | "3"
`:pretty` | "ACL RPC Version 3.2.2" | "ACL RPC Version 3"
`:num` | 30202 | 3
[omitted or nil or any other value] | (3 2 2) | 3

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

# rpc-wait

Generic Function, net.rpc package

Arguments: (self rpc-port) (m rpc-message) &rest modifiers

This method is used with the message handle returned by rpc-invoke to wait for the completion of the call. Upon completion, the state of the message object is returned and will be one of

- `:rms-done` - for normal completion
- `:rms-error` - for an error
- `:rms-throw` - for a remote throw

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

# rpp-passcode

Generic Function, net.rpc package

Arguments: port

### Method for (port with-rpc-port-enabler)

This reader method returns the passcode value stored in the port instance. The method is provided for custom rpc-do-request and rpc-do-invoke method implementations.

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

# rpp-tester

Generic Function, net.rpc package

Arguments: port

### Method for (port with-rpc-port-enabler)

This reader method returns the tester function stored in the port instance. The method is provided for custom rpc-do-request and rpc-do-invoke method implementations.

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

# rps-buffer-name

Function, net.rpc package

Arguments: shared-memory-rpc-port-server-instance

This accessor retrieves the name of the shared memory buffer created for a new shared-memory-rpc-port-server instance. This name must be communicated to the other Lisp image in order to allow it to connect to the server. The name is generated at the time the shared memory area is created and since it must be unique, it cannot be known in advance.

One possibile communication path is to open a socket rpc connection between the two processes for this purpose. Another way could be through a file.

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

# rr-base

Generic Function, net.rpc package

Arguments: remote-ref

A reader method for instances of the rpc-remote-ref class. The rr-base accessor returns a keyword that describes the type of remote reference. Most free remote references will be of the type :pointer. Other types may be created by calling rref or rpc-ref explicitly. See also rr-home and rr-type.

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

# rr-home

Generic Function, net.rpc package

Arguments: remote-ref

A reader method for instances of the rpc-remote-ref class. The rr-home accessor returns a string naming the home image of the reference. See also rr-base and rr-type.

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

# rr-type

Generic Function, net.rpc package

Arguments: remote-ref

A reader method for instances of the rpc-remote-ref class. The rr-type accessor returns a string that describes the remote type of a :pointer reference. The string is the ~A representation of the Lisp type of the object. See also rr-base and rr-home.

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

# rref

Function, net.rpc package

Arguments: data &key type symbol-mode package-mode symbol-name symbol-package

This is a variant of rpc-ref that omits the port argument. The implicit port bound by with-remote-port is the port that is used in the call.

This function creates an explicit reference object. If no keyword arguments are specified, then a default conversion is performed. The type keyword is defined in the table in Data Type Qualifiers in rpc.html. It is used to control the data conversion explicitly. The other keyword arguments, also described in Data Type Qualifiers in rpc.html, are used only when a symbol reference is created.

See also rpc-ref and rpc.html for general information on the Remote Procedure Call utility in Allegro CL.

# rthrow

Function, net.rpc package

Arguments: &optional tag value error-p

When called in the dynamic extent of a remote call, terminate the call and propagate tag and value to the remote caller.

Consequently, tag is a reference in the remote environment. If tag is `nil`, the remote call is simply terminated without a continuing throw in the remote environment. If tag is non-`nil`, remote call is terminated and the throw is continued in the remote environment.

An ordinary throw inside a remote call terminates the call but continues the throw in the local environment. The remote caller can determine that a throw happened. The thrown value will appear to be :unwind-protect.

When called in the dynamic extent of a remote call, this function does not return. If rthrow is called outside a remote call, then the effect depends on the error-p argument. When `nil`, simply return `nil`, otherwise signal an error.

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

# run-other-client

Function, net.rpc package

Arguments: &key start lisp remote-host remote-command prefix suffix flags infile opts args vecp env class verbose name line-limit host data log nanny keep ee image debug

This function starts a new Allegro CL Lisp image in a new operating system process, and possibly on a separate remote host machine. The calling Lisp image and the new one can communicate through rpc calls. This function returns a client-lisp instance which is used as an argument in subsequent calls to manipulate or query the new image (this is the only way to create such an instance). The first time run-other-client is called, a server process is started.

The start argument may be a string or symbol that denotes a function in the client Allegro CL image, or a list beginning with such a string or symbol. The entire list is sent to the client image when it connects to the server and the function is applied to the rest of the list. If and when the start function returns in the client image, the client image continues in an idle loop. On Windows, the console window is active in the Initial Listener process. On Unix, the top-level is never started. The start function may initiate the activity of the client image, or the client image may be activated by subsequent calls to client-funcall in the control image.

The lisp argument specifies a command that will start a Lisp process in the destination host. The argument may be a string or a list of strings; the elements in the list will be separated by spaces in the operating system command. If this argument is omitted or `nil`, the command that started the calling Lisp process is used.

The remote-host argument specifies the host where the new Lisp process will run. The default is to run on the same host as the caller. If a remote-host is specified, the lisp argument must specify a command that is meaningful in the remote host.

The remote-command, prefix, suffix, flags, infile, opts, and args arguments specify the components of the command that will be used to start the client Lisp process. The arguments are used to construct an operating system command string from three main components. Each of the items in each component may be a single string or a list of strings. Each string is passed as a separate argument in the OS command. Thus, if an item consists of several OS tokens, they should be presented as a list of strings; otherwise, they will not be recognized as separate arguments. The components are concatenated into a single command that is invoked with run-shell-command.

1. The first component is present only if the remote-host argument is specified. It is constructed as:

       <remote-command> <prefix> <remote-host> <suffix>

   The default for remote-command is "rsh". If remote-host is `nil`, the remote-command, prefix, and suffix arguments are ignored.

2. The second component is always present and specifies the command that starts a Lisp image. The default is to use the value returned by command-line-arguments for the current Lisp image. This value is reasonable if the client image is to run in the same machine and not calling from an IDE image.

   If the calling image is an IDE image, it is unlikely that the client image should be an IDE image; therefore it is necessary to specify this argument explicitly.

       <lisp-command>

3. The third component is the argument list to the lisp-command component.

       <flags> <-I image> <-d log> <-L infile> ... <genopts> <opts> < -- <genargs> <args>

   If the image argument is not specified, the <-I image> part is omitted.

   If the infile argument is not specified, the <-L infile> part is omitted. If the infile argument is a list, then multiple <-L> parts are inserted.

   The component is always present and consists of the tokens

         "-e" "(net.rpc.internal::other-restart)"

   where the contents of the string is actually encoded to eliminate spaces and other characters that interact poorly with shell commands. If the ee argument is `nil` (the default is `t`), then the `-e` command-line option is used. This option must be used if the other Lisp is an older version of Allegro CL that does not support `-ee`.

   The keep and debug arguments are applied to the aclrpc instances created to manage the remote Lisp images. The debug argument is also passed in the call to run-other-lisp. They are mainly intended for debugging situations.

   The component is always present and consists of the tokens

         "-key" <key> "-port" <port> "-pass" <pass> ["-host" <host>]

   is a generated integer key that identifies the client image in the control process.

   is the port number where the control process is listening.

   is the hostname where the control process is listening.

   is a generated passcode integer that allows access to the control process listener. The control process rpc listener is a sub-class of `rpc-socket-server-with-enabler` and thus requires a passcode for client access.

The host argument is needed only if the client image is to run on a separate host machine and the value of short-site-name is not usable to reach the host where this function is called. The default value is the value returned by short-site-name.

The nanny argument is used only in the first call to run-other-client. The nanny argument, if non-`nil`, starts a process that monitors the client images. If the nanny argument is a positive integer, it is the number of seconds between client checks. The default is 60 seconds. If the nanny argument is a symbol naming a function or a function, this function is called with one argument, the queried client, at each query interval. The nanny process exits when the control server exits. The function is called with the argument `nil` when the nanny process exits. If the nanny argument is a list, the first element is an interval and the second is a function.

The verbose argument, if non-`nil`, causes progress and status messages on the control process console. If the verbose argument is `:output`, then the output of the client processes is collected and printed on the control process standard output when each client is terminated.

The name argument specifies a name that will be shown in verbose messages pertaining to this client image.

The data argument is saved in the client-lisp-data slot which contains data relevant to the application.

The class argument is the name of the class for the client instance. It must be a sub-class of `client-lisp`.

The line-limit argument specifies how the output of client images should be handled. Its value can be an integer, a string, `nil`, or a list of a single integer.

- An integer specifies how many lines should be saved. Output lines from the client Lisp are collected by a background thread in the control Lisp image. The lines are displayed when client-exit is called if verbose was specified with the value `:output`. This is the default on Unix with a value of 500.

- A string specifies a file where the background thread saves all the lines of output from the client Lisp. The most recent 20 lines are also saved in the heap.

- A value of `nil` suppresses any client output handling. This is the default on Windows where the output does not accumulate in the stream. On Unix, this value may cause the client process to block when the system buffer for the pipe is filled.

- A value of a list of one integer suppresses the background thread. The collected output is saved up to the integer line limit. Lines are collected from the client Lisp when client-ready-p is called. This option is not recommended unless the output of the client Lisp is known to be very small.

The file examples/aclrpc/rpc-otherex.cl contains some simple programs that use run-other-client to manage several Lisp images.

When a client Lisp image is started, it will most likely start in the caller's home directory. It may be desirable to change the directory before making any other calls to the client image.

The following examples show two ways to do this:

If the client image contains the top-level module

        (client-funcall c "tpl:do-command" :cd root)

or a more primitive way

       (let* ((x (client-funcall c "excl.osi:chdir" root))
              (y (client-funcall c "cl:pathname" x)))
         (client-funcall c (client-funcall c "cl:set" '*default-pathname-defaults* y)))

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# run-other-lisp

Function, net.rpc package

Arguments: &key log vecp env remote-command prefix remote-host suffix image lisp flags infile opts args debug

When this function is used to start a second Lisp image, most of the other functions in this document are not available since the client-lisp infrastructure is not enabled. This function is used by run-other-client and may be useful in situations where an application needs behavior outside of the scope of this document.

This is a more primitive function (than run-other-client) to start a new Allegro CL Lisp image. There is no implied calling or loading performed by this call. The values returned by run-other-lisp are the same as the value returned by run-shell-command.

If the log argument is non-`nil`, it must be a string that denotes a file. The new Lisp image will start a dribble there.

The vecp argument is only used on Unix. When the vecp argument is non-`nil` (the default), the command is passed to run-shell-command as a vector of strings.

The env argument is an association list of environment variable names and values. The environment variables are added to the OS environment of the new Lisp image

The remote-command argument may be a string or a list of strings. The flattened sequence of strings is used as the command that starts the new Lisp image. The default is "rsh". If the command consists of several tokens it is recommended to pass it as a list of strings instead of a single string of tokens and spaces.

The prefix argument may be a string or a list of strings. The flattened sequence of strings is inserted in the command that starts the new Lisp image.

The remote-host argument is a string that names the host where the new Lisp image must run. If omitted or `nil`, the value "localhost" is used.

The suffix argument may be a string or a list of strings. The flattened sequence of strings is inserted in the command that starts the new Lisp image.

The image argument may be a string that names the Lisp image file for the new Lisp image.

The lisp argument may be a string or a list of strings. The flattened sequence of strings is inserted in the command that starts the new Lisp image.

The flags argument may be a string or a list of strings. The flattened sequence of strings is inserted in the command that starts the new Lisp image.

The infile argument may be a string or a list of strings. Each string names a file that is loaded in the new Lisp image with a -L flag.

The opts argument may be a string or a list of strings. The flattened sequence of strings is inserted in the command that starts the new Lisp image.

The args argument may be a string or a list of strings. The flattened sequence of strings is inserted in the command that starts the new Lisp image.

The debug argument, when non-`nil`, causes the run-shell-command arguments to be printed to *standard-output*.

The arguments to run-other-lisp are used to construct an operating system command string from three main components. The components are concatenated into a single command that is invoked with run-shell-command.

1. The first component is present only if the remote-host argument is specified. It is constructed as:

       <remote-command> <prefix> <remote-host> <suffix>

   Each of the items in the first component may be a single string or a list of strings. Each string is passed as a separate argument in the OS command. Thus, if an item consists of several OS tokens, they should be presented as a list of strings; otherwise, they will not be recognized as separate arguments.

2. The second component is always present and specifies the command that starts a Lisp image. The default is to use the value returned by sys:command-line-arguments for the current Lisp image. This value is reasonable if the client image is to run in the same machine and not calling from an IDE image.

   If the calling image is an IDE image, it is unlikely that the client image should be an IDE image; therefore it is necessary to specify this argument explicitly.

   If the client image is to run on a separate host, then the lisp argument must be specified.

       <lisp-command>

3. The third component is the argument list to the lisp-command component.

       <flags> <-I image> <-d log> <-L infile>... <opts> -- <args>

The flags, opts, and args arguments may be any combination of lists and strings. Any list structure is flattened out and the resulting elements are separated by spaces in the command string, or appear as separate elements in the command vector.

If the image argument is not specified, the <-I image> part is omitted.

If the infile argument is not specified, the <-L infile> part is omitted. If the infile argument is a list, then multiple <-L> parts are inserted.

If the case-modes of the calling and client images are different, then the applications are responsible for passing information in a way that is compatible with the respective case-mode values. If symbols are specified as lowercase package-qualified strings, then case-mode issues are generally avoided.

#### Simple example

To run a second Lisp image on the same host as the caller, almost all the arguments may be omitted:

    (run-other-lisp)

is sufficient to start a second Lisp image that simply waits for some top-level input.

    (run-other-lisp :infile "foo.cl")

will start a second Lisp image that loads "foo.cl" during startup.

    (run-other-lisp :remote-host "spot"
                    :lisp "~/bin/start-lisp"
                    :args '("-flag1" "-flag2"))

will start a Lisp image on host "spot". The script "~/bin/start-lisp" is assumed to contain whatever is needed to start a Lisp on that host. The two argumtens "-flag1" "-flag2" will be added to the command line after the "--" separator.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# ungrab-gate

Generic Function, net.rpc package

Arguments:

No longer supported.

In the initial release of the Allegro CL RPC module (see rpc.html), this function was one of several operators (along with grab-gate, with-access-gate*, and with-access-gate) provided as an interface to multiprocessing gate objects (see Gates (both models) in multiprocessing.html). However, we have determined that those operators were not useful for that purpose. The symbols naming them have been unexported and the interface is no longer supported.

# with-access-gate

Macro, net.rpc package

Arguments:

No longer supported.

In the initial release of the Allegro CL RPC module (see rpc.html), this macro was one of several operators (along with grab-gate, with-access-gate*, and ungrab-gate) provided as an interface to multiprocessing gate objects (see Gates (both models) in multiprocessing.html). However, we have determined that those operators were not useful for that purpose. The symbols naming them have been unexported and the interface is no longer supported.

# with-access-gate*

Macro, net.rpc package

Arguments:

No longer supported.

In the initial release of the Allegro CL RPC module (see rpc.html), this macro was one of several operators (along with grab-gate, with-access-gate, and ungrab-gate) provided as an interface to multiprocessing gate objects (see Gates (both models) in multiprocessing.html). However, we have determined that those operators were not useful for that purpose. The symbols naming them have been unexported and the interface is no longer supported.

# with-other-client-port

Macro, net.rpc package

Arguments: &body body

The RPC functions rcall, etc. may be used in the body of this macro to make calls to the controlling process. The value(s) returned are the value(s) of the body treated as a let body.

See Running several communicating Allegro CL images in rpc.html for information on running several Lisp images.

# with-remote-port

Macro, net.rpc package

Arguments: (port-var &key key close final) &rest body

The purpose of this macro is to establish a dynamic context where a default rpc port is available. port-var is bound to *rpc-port*. The value(s) returned are the value(s) of the body treated as a let body.

Before the body is evaluated, the port is examined, and if open, it is used as-is. If not open, it is opened or re-opened as appropriate. If the port is not open and cannot be opened, an error is signaled.

If the close keyword value is non-`nil`, the port is closed upon exit from the body. If the final keyword value is non-`nil`, the port is closed permanently.

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

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0