configure-remote-debugging-spec

configure-remote-debugging-spec Function

Summary

Client side: Configure how LispWorks opens a connection for remote debugging on the client side.

Package

dbg

Signature

configure-remote-debugging-spec host &key port log-stream failure-function timeout open-callback name setup-default enable ssl ipv6 => host

Arguments

`host`⇩	A string specifying the IDE side hostname, or `nil`.
`port`⇩	An integer.
`log-stream`⇩	An output stream or `nil`.
`failure-function`⇩	`nil` or a function of two arguments: host and port.
`timeout`⇩	A non-negative real or `nil`.
`open-callback`⇩	`nil` or a function that takes one argument (a newly opened connection).
`name`⇩	Any object.
`setup-default`⇩	`:delayed`, `nil` or `t`.
`enable`⇩	`nil` or `t`.
`ssl`⇩	A SSL client context specification.
`ipv6`⇩	`:any` (the default), `t`, or `nil`.

Values

host

A string or nil.

Description

The function configure-remote-debugging-spec tells LispWorks how to open a connection for remote debugging on the client side if there is no existing connection to use (see set-remote-debugging-connection for details). configure-remote-debugging-spec changes the global settings, unless it is called inside the dynamic extent of with-remote-debugging-spec, in which case its effects last until the exit from this extent (except for setup-default and enable, see below).

If port, log-stream, failure-function, timeout, open-callback, name, ssl or ipv6 are supplied then they configure the corresponding settings, otherwise the settings are not changed.

host and port configure the hostname and TCP port to connect to (see the hostspec and service arguments to open-tcp-stream). host can also be nil, which specifies that LispWorks must not try to open a debugging connection. The initial configured value of port is the value of *default-ide-remote-debugging-server-port*, which is 21101 initially.

timeout configure the timeout in seconds, or nil for indefinite. If a connection to the IDE side cannot be made within the specified timeout then remote debugging is not used.

log-stream configures logging for communication problems, including failure to open the connection (unless the configured value of failure-function is non-nil) and errors when communicating across the connection. Failure to open the stream can happen if the host is not ready, the communication is blocked or the network/host are overloaded. Later failures should not happen as long as the underlying operating system is not broken. When the configured value of log-stream is non-nil, LispWorks writes error messages to it. Otherwise (the default) LispWorks does not log errors when communicating across the connection.

When the configured value of failure-function is non-nil, it will be called with the values of host and port in case of failure to open the connection, instead of writing to log-stream. The initial value of failure-function is nil.

The configured value of name is used as the name of the connection. It affects how the connection object is printed and also the name of the Lisp process that handles communication for the connection. It initially defaults to "Remote debugging".

When the configured value of open-callback is non-nil, it is called after the new connection has been opened, with the new connection as its argument. The initial configured value of open-callback is nil.

setup-default and enable determine whether the new connection becomes the default, and when it should be used. Note that they always have a global effect, even when configure-remote-debugging-spec is called in the dynamic extent of with-remote-debugging-spec.

When setup-default is :delayed (the default if the configured open-callback is nil) or t, the new connection will become the default connection, by a call to set-default-remote-debugging-connection. If enable is non-nil (the default), then the enabling switch is turned on as if by calling set-remote-debugging-connection with argument t. As a result, assuming no other calls to set-remote-debugging-connection or set-default-remote-debugging-connection are made, the new connection will be used in the future whenever a connection is needed. See set-remote-debugging-connection for more details. If setup-default is :delayed, then the connection will be opened the first time it is needed. If setup-default is t, then configure-remote-debugging-spec opens the connection immediately. Thus with the default arguments, the connection will be opened the first time it is needed, and will then be used whenever a connection is needed.

When setup-default is nil (the default if the configured open-callback is non-nil), the connection is not made a default. If it is created when entering the debugger or for a Remote Listener, then it will be closed automatically when exiting the debugger or closing the Listener. See remote-inspect for how it deals with connections.

If ssl is non-nil, then the connection will be made using SSL. This is done by passing ssl as the ssl-ctx argument to open-tcp-stream when the connection is opened. To be able to configure the SSL connection options, including setting the certificates, you can supply a comm:ssl-abstract-context. Note that ssl will be used repeatedly.

ipv6 is used when opening the TCP connection, and interpreted the same way as in open-tcp-stream.

Notes

For the connection to open successfully, the machine which is addressed by host must be listening for TCP connections on port. Normally that should happen as result of calling start-ide-remote-debugging-server, but you can reasonably easily write your own version of it if required.

It is possible to override the default value of port by configuring the service name lw-remote-debug-ide. On a machine where this service is registered, if port is not given then the registered value is used instead of *default-ide-remote-debugging-server-port*.

Using configure-remote-debugging-spec requires the ability to use open-tcp-stream, which at OS level means using the C library function connect.

Sometimes it is easier to make the connection in the other direction. For example, the Android SDK allows you to redirect sockets from a host to the android device, by using adb forward, so when the Android device is the client side, it is easier to connect the other way, in which case you should use start-client-remote-debugging-server on the client side (instead of using configure-remote-debugging-spec), and call ide-connect-remote-debugging on the IDE side.

Opening a connection once and then re-using it is probably more efficient in most cases and also has the advantage that remote object handles remain valid. However, if opening a connection is relatively rare, using one-off connections removes the (quite small) overhead of keeping a connection open.

When you do not re-use the connection, the configured values are used each time you open a connection.

If you wish to open a connection yourself, then note that you cannot implement the delayed automatic opening that configure-remote-debugging-spec implements when setup-default is :delayed (the default) or nil. You can, however, implement the equivalent of :setup-default t (that is opening the connection before it is needed) by making the underlying stream yourself using open-tcp-stream or some other mechanism, using create-client-remote-debugging-connection to create the client connection and then using set-default-remote-debugging-connection, set-remote-debugging-connection and with-remote-debugging-connection as appropriate.