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.

With a patch released in February of 2014, the behavior of jlinker-listen is much more robust when connections fail and are re-established from the same Java client. When one Java application connects and disconnects repeatedly from Lisp, the recommended practice is to make the connect() and disconnect() calls from the same Java thread. Connecting and disconnecting from separate threads can increase the probability of a failed connection that must be attempted again. Lisp continues to listen and accept connections after a failed connection attempt, but each failed connection will cause a noticable delay in the availability of the Lisp server.

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