run-other-client

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.

1. The first component is present only if the remote-host argument is specified. It is constructed as:

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

2. The second component is always present and specifies the command that starts a Lisp image. The default is to use the value returned by sys:command-line-arguments for the current Lisp image. This value is reasonable if the client image is to run in the same machine and not calling from an IDE image.

   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>
   

3. The third component is the argument list to the lisp-command component.

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

• An integer specifies how many lines should be saved. Output lines from the client Lisp are collected by a background thread in the control Lisp image. The lines are displayed when client-exit is called if verbose was specified with the value :output. This is the default on Unix with a value of 500.
• A string specifies a file where the background thread saves all the lines of output from the client Lisp. The most recent 20 lines are also saved in the heap.
• A value of 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.
• A value of a list of one integer suppresses the background thread. The collected output is saved up to the integer line limit. Lines are collected from the client Lisp when client-ready-p is called. This option is not recommended unless the output of the client Lisp is known to be very small.

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.