start-remote-listener

start-remote-listener Function

Summary

Client side: Start a Remote Listener on the IDE side.

Package

dbg

Signature

start-remote-listener &key new-process-p message connection close-on-exit => started-p

Arguments

`new-process-p`⇩	A boolean, default `t`.
`message`⇩	A string or `nil`.
`connection`⇩	A client-remote-debugging or `nil`.
`close-on-exit`⇩	A boolean.

Values

started-p

A boolean.

Description

The function start-remote-listener starts a Remote Listener tool on the IDE side, such that reading and evaluation is done on the client side where the start-remote-listener was called.

start-remote-listener first tells the IDE to start the Listener, and then runs a read-eval-print loop that communicates with the IDE's Listener over the connection.

If new-process-p is non-nil (the default), then a new Lisp process is created to start the Listener and run the read-eval-print loop. This process runs until the read-eval-print loop exits. If new-process-p is nil, then the read-eval-print loop runs in the current process and start-remote-listener does not return until the read-eval-print loop exits.

message, when is not nil, is printed into the Listener tool before the first prompt appears.

connection (default nil) controls which connection to use. If connection is non-nil and is connected then it is used. Otherwise start-remote-listener uses the same mechanism as the debugger to find the connection, which by default means re-using an existing connection if one exists, or opening a new one (under the control of the remote debugging spec). In typical usage, this be set up by either configure-remote-debugging-spec or start-client-remote-debugging-server. See 3.7.1 Simple usage and 3.7.5 Advanced usage - multiple connections for details.

close-on-exit is used only when connection is non-nil. When close-on-exit is non-nil, the connection is closed when the read-eval-print loop exits. Otherwise (the default), the connection remains open for later re-use.

If the Listener tool on the IDE side is closed, then the read-eval-print loop exits. Normally this is the only way that the loop exits, but you could also exit it by throwing to a surrounding catch (when new-process-p is nil) or by terminating the process (by current-process-kill).

start-remote-listener returns nil if connection is not a valid connection (either nil or already closed) and it cannot find the connection to use. Otherwise, if new-process-p is non-nil (the default) it returns t immediately, and if new-process-p is nil it returns nil only when the Listener is closed.

Notes

Using message is an easy way for the client to write some text to the IDE even when you do not need a Listener.