create-client-remote-debugging-connection

create-ide-remote-debugging-connection Functions

Summary

Create a client or ide remote debugging connection (advanced).

Package

dbg

Signatures

create-client-remote-debugging-connection name &key socket stream ssl log-stream => client-side-connection

create-ide-remote-debugging-connection name &key socket stream ssl log-stream => ide-side-connection

Arguments

`name`⇩	A string.
`socket`⇩	A socket or `nil`.
`stream`⇩	An base-char stream stream opened for `:io` or `nil`.
`ssl`⇩	A SSL specification.
`log-stream`⇩	An output stream or `nil`.

Values

`client-side-connection`⇩
	A client-remote-debugging.
`ide-side-connection`⇩	An ide-remote-debugging.

Description

The function create-client-remote-debugging-connection creates a client side remote debugging connection. The function create-ide-remote-debugging-connection creates an IDE side remote debugging connection.

Normally you would use the higher level interface functions start-client-remote-debugging-server or configure-remote-debugging-spec to open a client side connection, and start-ide-remote-debugging-server or ide-connect-remote-debugging to open an IDE side connection. The higher level functions call these functions to create the connection.

name specifies a name for the connection, but otherwise does not affect its behavior. On the IDE side it is used in the title of Remote Listener and Remote Debugger tools. On both sides it is used in the name of the process that handles communication across the connection.

Either socket or stream (but not both) must be non-nil.

If socket is non-nil, it must be a socket handle, like the one that start-up-server passes to its function argument or the socket that accept-tcp-connections-creating-async-io-states, when called with :create-state nil, passes to its connection-function. A socket-stream is created with this socket and used as the stream in the connection. socket defaults to nil.

If stream is non-nil, it must be an base-char stream opened for :io and it is used directly in the connection. Typically it will be a socket-stream, but that is not a requirement. stream defaults to nil.

If ssl is non-nil, then attach-ssl is called on the stream, passing ssl as the :ssl-ctx argument. Note that this will work only if the stream is a socket-stream. ssl defaults to nil.

log-stream, if non-nil, must be an output stream. The connection writes messages to it in situations when communication fails. log-stream defaults to nil.

For the connection to work, the other side of the socket or stream must be the opposite kind of connection, that is for a client side connection the other side needs to be an IDE connection and vice versa.

The "ownership" of socket or stream is transferred to the connection by these functions. That means that no further I/O operations are allowed on socket or stream by other code, and they must not be closed. They will be closed when the connection is closed.

The value of client-side-connection that is returned by create-client-remote-debugging-connection can be used as the connection argument to with-remote-debugging-connection, set-remote-debugging-connection or set-default-remote-debugging-connection, or as the :connection keyword to start-remote-listener or remote-inspect. It is not remembered by LispWorks anywhere.

The value of ide-side-connection that is returned by create-ide-remote-debugging-connection is remembered by LispWorks, and is returned by ide-list-remote-debugging-connections or ide-find-remote-debugging-connection when appropriate. As a result, it may be used by any of the IDE side functions. It can also be passed explicitly to any of these functions. It is forgotten when it is closed.

Both client-side-connection and ide-side-connection can be manipulated by these functions:

close-remote-debugging-connection closes it.
remote-debugging-connection-add-close-cleanup adds a cleanup callback that is called when the connection is called.
remote-debugging-connection-peer-address finds the peer address of the connection.
remote-debugging-connection-name returns its name.
ensure-remote-debugging-connection checks if it is still open.