ToC DocOverview CGDoc RelNotes FAQ Index PermutedIndex
Allegro CL version 11.0

net.rpc operators

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:

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:

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)

  1. the listener-process (non-nil only when the value of the open argument is :listener)

  2. error-code

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

The keyword arguments are:

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:

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:

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

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:

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:

While a call is completed:

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-onlyis nil Value returned when main-onlyis 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

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.

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) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC DocOverview CGDoc RelNotes FAQ Index PermutedIndex
Allegro CL version 11.0