def-remote-function

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