jlinker-listen

Arguments: &key process-function end-function init-args max-servers total-timeout stop

This function starts a process that continuously restarts the Lisp jLinker server so that one is (almost) always available for a Java connection.

The Java connection attempts must be separated in time, i.e. a new connection attempt should be made only after a previous one is completely initialized. See the note about competing connections in the description of jlinker-init.

The returned value depends on the arguments. When a new listener is started, then the returned value is the name of the listening process in Lisp. When the stop argument is passed, the returned value is the stop argument. A returned value of nil indicates that no listeners were active, so the call was ignored. A returned value of :stopping indicates that a previous :stop request is not yet completed; in some cases, it may be necessary to manually kill the remaining jlinker processes. Normally, the returned value is the stop argument.

When the stop argument is the keyword :abort, any attempt to stop the listeners is terminated. This option is very likely to leave processes that must be killed manually.

The process-function argument is a function of one argument. It is called when jlinker-init returns after a new server creation. The argument is the value returned by jlinker-init. If this function returns nil, the jlinker-listen process exits and no more servers will be created. If this argument is not specified, then jlinker-listen will exit if jlinker-init fails for any reason.

Compatibility Note

In previous versions of jlinker, jlinker-listen would exit when jlinker-init failed whether the process-function argument was specified or not. The process-function was called, but its result was ignored if jlinker-init returned a failure message.

In the current version it is the responsibility of the process-function to decide whether to stop or continue when jlinker-init returns a failure message.

The stop argument is t to stop advertising after the next connection is made. A value of :stop stops advertising immediately but leaves active connections running. A value of :all stops advertising immediately and forces all the active connections to be killed.

The end-function is called with two arguments when the listener process exits for any reason. The first argument is a reason keyword and the second is a list of currently active connections.

The init-args argument is a list of keyword-value pairs passed in a call to (jlinker-init :lisp-advertises ...).

The max-servers argument is the maximum number of simultaneous active server connections. When this number is reached, the advertised socket is disabled until one or more servers terminate.

The total-timeout argument may be a number of seconds for how long the advertised connection is made available.

See jlinker.htm for more information on the jLinker facility.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.