After the server and client have connected, they each have a wire allowing function evaluation in the other process. This RPC mechanism has three flavors: for side-effect only, for a single value, and for multiple values.
Only a limited number of data types can be sent across wires as arguments for remote function calls and as return values: integers inclusively less than 32 bits in length, symbols, lists, and remote-objects (see section 9.1.3). The system sends symbols as two strings, the package name and the symbol name, and if the package doesn't exist remotely, the remote process signals an error. The system ignores other slots of symbols. Lists may be any tree of the above valid data types. To send other data types you must represent them in terms of these supported types. For example, you could use prin1-to-string locally, send the string, and use read-from-string remotely.
[Macro]
wire: remote wire call-specs
The remote macro arranges for the process at the other end of wire to invoke each of the functions in the call-specs. To make sure the system sends the remote evaluation requests over the wire, you must call wire-force-output.
Each of call-specs looks like a function call textually, but it has some odd constraints and semantics. The function position of the form must be the symbolic name of a function. remote evaluates each of the argument subforms for each of the call-specs locally in the current context, sending these values as the arguments for the functions.
Consider the following example:
(defun write-remote-string (str) (declare (simple-string str)) (wire:remote wire (write-string str)))The value of str in the local process is passed over the wire with a request to invoke write-string on the value. The system does not expect to remotely evaluate str for a value in the remote process.
[Function]
wire: wire-force-output wire
wire-force-output flushes all internal buffers associated with wire, sending the remote requests. This is necessary after a call to remote.
[Macro]
wire: remote-value wire call-spec
The remote-value macro is similar to the remote macro. remote-value only takes one call-spec, and it returns the value returned by the function call in the remote process. The value must be a valid type the system can send over a wire, and there is no need to call wire-force-output in conjunction with this interface.
If client unwinds past the call to remote-value, the server continues running, but the system ignores the value the server sends back.
If the server unwinds past the remotely requested call, instead of returning normally, remote-value returns two values, nil and t. Otherwise this returns the result of the remote evaluation and nil.
[Macro]
wire: remote-value-bind wire (variable) remote-form
local-forms
remote-value-bind is similar to multiple-value-bind except the values bound come from remote-form's evaluation in the remote process. The local-forms execute in an implicit progn.
If the client unwinds past the call to remote-value-bind, the server continues running, but the system ignores the values the server sends back.
If the server unwinds past the remotely requested call, instead of returning normally, the local-forms never execute, and remote-value-bind returns nil.