rpc-close

Arguments: (port <type-of-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.htm for general information on the Remote Procedure Call utility in Allegro CL.

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