| Allegro CL version 8.2 Moderate update since 8.2 release. 8.1 version | ||||||||||
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.
<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.
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>
<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 <genopts> 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 <genargs> component is always present and consists of the tokens
"-key" <key> "-port" <port> "-pass" <pass> ["-host" <host>]
<key> is a generated integer key that identifies the client image in the control process.
<port> is the port number where the control process is listening.
<host> is the hostname where the control process is listening.
<pass> 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.
:output. This is the default on Unix with a value
of 500.
nil suppresses any client output
handling. This is the default on Windows where the output does not
accumulate in the stream. On Unix, this value may cause the client
process to block when the system buffer for the pipe is filled.
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.htm for information on running several Lisp images.
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.
| Allegro CL version 8.2 Moderate update since 8.2 release. 8.1 version | ||||||||||