rpc-close

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

The following description for the rpc-port method applies to the patched version of Allegro CL RPC facility made available after the release of Allegro CL 6.2. You must have downloaded the relevant patch (you can do so with update-allegro). If you have downloaded the patch, this function rpc-version will be defined and the form (rpc-version) will return (3 2 2) (version 3.2.2) or later. A method was defined in the unpatched version, but it did not work correctly.

The method on rpc-port works as follows.

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 is 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.

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 is non-nil, cancel any unsent messages.

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.

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.

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 noop.

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.

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

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.