The swank-client Reference Manual

This is the swank-client Reference Manual, version 1.7, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:40:45 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 swank-client

Client side of the Swank protocol.

Author

Robert Brown <>

License

GPL version 2. See the copyright messages in individual files.

Long Description

An implementation of the client side of Slime’s Swank debugging protocol.

Version

1.7

Dependencies
  • bordeaux-threads (system).
  • com.google.base (system).
  • swank (system).
  • usocket (system).
Source

swank-client.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 swank-client/swank-client.asd

Source

swank-client.asd.

Parent Component

swank-client (system).

ASDF Systems

swank-client.


3.1.2 swank-client/package.lisp

Source

swank-client.asd.

Parent Component

swank-client (system).

Packages

swank-client.


3.1.3 swank-client/swank-client.lisp

Dependency

package.lisp (file).

Source

swank-client.asd.

Parent Component

swank-client (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 swank-client

A client interface to Swank servers.

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: with-slime-connection ((variable host-name port &optional connection-closed-hook) &body body)

Wraps BODY in a LET form where VARIABLE is bound to the value returned by (SLIME-CONNECT HOST-NAME PORT CONNECTION-CLOSED-HOOK). Arranges for the Swank connection to be closed when control exits BODY.

Package

swank-client.

Source

swank-client.lisp.


5.1.2 Ordinary functions

Function: slime-close (connection)

Closes CONNECTION to a Swank server.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-connect (host-name port &optional connection-closed-hook)

Connects to the Swank server running on HOST-NAME that is listening on PORT. Returns a SWANK-CONNECTION if the connection attempt is successful. Otherwise, returns NIL. May signal SLIME-NETWORK-ERROR if the user has a Slime secret file and there are network problems sending its contents to the remote Swank server. If provided, function CONNECTION-CLOSED-HOOK is called when the connection is closed.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-eval (sexp connection)

Sends SEXP over CONNECTION to a Swank server for evaluation and waits for the result. When the result is received, it is returned. Signals SLIME-NETWORK-ERROR when there are network problems sending SEXP.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-eval-async (sexp connection &optional continuation)

Sends SEXP over CONNECTION to a Swank server for evaluation, then immediately returns. Some time later, after the evaluation is finished, CONTINUATION is called with the result as argument. Signals SLIME-NETWORK-ERROR when there are network problems sending SEXP.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-migrate-evals (old-connection new-connection)

Evaluates on NEW-CONNECTION all the work pending on a closed OLD-CONNECTION. Signals SLIME-NETWORK-ERROR when there are network problems.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-pending-evals-p (connection)

Returns T if there are outstanding evaluations pending on CONNECTION; otherwise, returns NIL.

Package

swank-client.

Source

swank-client.lisp.


5.1.3 Conditions

Condition: slime-network-error

Network problem while evaluating a form.

Package

swank-client.

Source

swank-client.lisp.

Direct superclasses

error.


5.1.4 Classes

Class: swank-connection

A connection to a Swank server.

Package

swank-client.

Source

swank-client.lisp.

Direct methods
Direct slots
Slot: host-name

Name of the host where the Swank server is running.

Type

string

Initform

(com.google.base:missing-argument)

Initargs

:host-name

Readers

host-name.

Writers

This slot is read-only.

Slot: port

Port number used to make a Swank server connection.

Type

swank-client::port

Initform

(com.google.base:missing-argument)

Initargs

:port

Readers

port.

Writers

This slot is read-only.

Slot: usocket

USOCKET used to communicate with the Swank server.

Type

usocket:stream-usocket

Initform

(com.google.base:missing-argument)

Initargs

:usocket

Readers

usocket.

Writers

This slot is read-only.

Slot: thread-offset

All threads for this connection are presented to Emacs with this value added to their thread ID.

Type

(integer 0 *)

Initform

(incf swank-client::*thread-offset* swank-client::+maximum-thread-count+)

Readers

thread-offset.

Writers

This slot is read-only.

Slot: continuation-counter

Used to associate an ID with each evaluated form.

Type

(integer 0 *)

Initform

0

Readers

continuation-counter.

Writers

(setf continuation-counter).

Slot: rex-continuations

List of (ID, continuation) pairs, one for each evaluation in progress. Used to match each returned value with the continuation it should be passed to.

Type

list

Initform

(quote nil)

Readers

rex-continuations.

Writers

(setf rex-continuations).

Slot: state

State of the connection, either :ALIVE, :CLOSING, or :DEAD.

Type

(member :alive :closing :dead)

Initform

:alive

Readers

state.

Writers

(setf state).

Slot: connection-lock

Lock protecting slots of this connection that are read and written by concurrently running threads.

Initform

(bordeaux-threads:make-lock)

Readers

connection-lock.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Constants

Constant: +abort+

Unique object used to signal that a computation was aborted on the server.

Package

swank-client.

Source

swank-client.lisp.

Constant: +maximum-thread-count+

Maximum number of threads per Swank connection.

Package

swank-client.

Source

swank-client.lisp.


5.2.2 Special variables

Special Variable: *connections-lock*

Lock protecting *OPEN-CONNECTIONS*.

Package

swank-client.

Source

swank-client.lisp.

Special Variable: *io-package*

A package used by the Swank client code when printing s-expressions, so that symbols in the printed output contain their package names.

Package

swank-client.

Source

swank-client.lisp.

Special Variable: *open-connections*

List of all open Swank connections.

Package

swank-client.

Source

swank-client.lisp.

Special Variable: *thread-offset*

Counter used to assign each Swank connection a unique range of thread IDs.

Package

swank-client.

Source

swank-client.lisp.


5.2.3 Macros

Macro: destructure-case (value &body patterns)

Dispatches VALUE to one of PATTERNS. A cross between CASE and DESTRUCTURING-BIND. The pattern syntax is: ((HEAD . ARGS) . BODY). The list of patterns is searched for a HEAD that’s EQ to the car of VALUE. If one is found, BODY is executed with ARGS bound to the corresponding values in the CDR of VALUE.

Package

swank-client.

Source

swank-client.lisp.

Macro: slime-rex ((&rest saved-vars) (sexp connection) &body continuations)

(slime-rex (VAR ...) (SEXP CONNECTION) CLAUSES ...)

Remote EXecute SEXP.

VARs are a list of saved variables visible in the other forms. Each VAR is either a symbol or a list (VAR INIT-VALUE).

SEXP is evaluated and the PRIN1-ed version is sent over CONNECTION to a remote Lisp.

CLAUSES is a list of patterns with same syntax as ‘destructure-case’. The result of the evaluation of SEXP is dispatched on CLAUSES. The result is either a sexp of the form (:ok VALUE) or (:abort CONDITION). CLAUSES is executed asynchronously.

Signals SLIME-NETWORK-ERROR when there are network problems sending SEXP.

Package

swank-client.

Source

swank-client.lisp.


5.2.4 Ordinary functions

Function: add-open-connection (connection)

Adds CONNECTION to the set of open Swank connections.

Package

swank-client.

Source

swank-client.lisp.

Function: find-connection-for-thread-id (thread-id)

Returns the open Swank connection associated with THREAD-ID.

Package

swank-client.

Source

swank-client.lisp.

Function: forward-event-to-worker (form package thread-id id)

Determines whether an :emacs-rex event is intended for a remote worker Lisp and if so forwards it. When forwarding is successful, FORWARD-EVENT-TO-WORKER returns T; otherwise, it returns NIL.

FORWARD-EVENT-TO-WORKER is called by code in Swank Crew’s patch to Slime’s swank.lisp source file. The forwarding it performs is used by Swank Crew to handle debugging of conditions signalled on remote worker Lisps. See swank.lisp-patch in https://github.com/brown/swank-crew.

Package

swank-client.

Source

swank-client.lisp.

Function: remove-open-connection (connection)

Removes CONNECTION from the set of open Swank connections.

Package

swank-client.

Source

swank-client.lisp.

Function: send-to-emacs (event)

Sends EVENT to Emacs.

Package

swank-client.

Source

swank-client.lisp.

Function: server-thread-id (thread-id)

Maps the THREAD-ID in an event that must be forwarded to the thread ID known by the remote Lisp to which it will be sent.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-dispatch-event (event connection)

Handles EVENT for a Swank CONNECTION. Signals SLIME-NETWORK-ERROR if there are communications problems.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-dispatch-events (connection connection-closed-hook)

Reads and dispatches incoming events for a CONNECTION to a Swank server. If provided, function CONNECTION-CLOSED-HOOK is called when CONNECTION is closed.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-net-connect (host-name port)

Establishes a connection to the Swank server listening on PORT of HOST-NAME. Returns a SWANK-CONNECTION when the connection attempt is successful. Otherwise, returns NIL. May signal SLIME-NETWORK-ERROR if the user has a Slime secret file and there are network problems sending its contents to the remote Swank server.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-net-encode-length (n)

Encodes an integer as a 6-character, 24-bit hex string.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-net-read (connection)

Reads a Swank message from a network CONNECTION to a Swank server. Returns the Swank event or NIL, if there was a problem reading data.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-net-send (sexp usocket)

Sends SEXP to a Swank server over USOCKET. The s-expression is read and evaluated by the remote Lisp.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-secret ()

Finds the secret file in the user’s home directory. Returns NIL if the file doesn’t exist; otherwise, returns the first line of the file.

Package

swank-client.

Source

swank-client.lisp.

Function: slime-send (sexp connection)

Sends SEXP to a Swank server using CONNECTION. Signals SLIME-NETWORK-ERROR if there are communications problems.

Package

swank-client.

Source

swank-client.lisp.

Function: socket-keep-alive (socket)

Configures TCP keep alive packets for SOCKET. The socket connection will be considered dead if keep alive packets are lost.

Package

swank-client.

Source

swank-client.lisp.


5.2.5 Generic functions

Generic Reader: connection-lock (object)
Package

swank-client.

Methods
Reader Method: connection-lock ((swank-connection swank-connection))

Lock protecting slots of this connection that are read and written by concurrently running threads.

Source

swank-client.lisp.

Target Slot

connection-lock.

Generic Reader: continuation-counter (object)
Generic Writer: (setf continuation-counter) (object)
Package

swank-client.

Methods
Reader Method: continuation-counter ((swank-connection swank-connection))
Writer Method: (setf continuation-counter) ((swank-connection swank-connection))

Used to associate an ID with each evaluated form.

Source

swank-client.lisp.

Target Slot

continuation-counter.

Generic Reader: host-name (object)
Package

swank-client.

Methods
Reader Method: host-name ((swank-connection swank-connection))

Name of the host where the Swank server is running.

Source

swank-client.lisp.

Target Slot

host-name.

Generic Reader: port (object)
Package

swank-client.

Methods
Reader Method: port ((swank-connection swank-connection))

Port number used to make a Swank server connection.

Source

swank-client.lisp.

Target Slot

port.

Generic Reader: rex-continuations (object)
Generic Writer: (setf rex-continuations) (object)
Package

swank-client.

Methods
Reader Method: rex-continuations ((swank-connection swank-connection))
Writer Method: (setf rex-continuations) ((swank-connection swank-connection))

List of (ID, continuation) pairs, one for each evaluation in progress. Used to match each returned value with the continuation it should be passed to.

Source

swank-client.lisp.

Target Slot

rex-continuations.

Generic Reader: state (object)
Generic Writer: (setf state) (object)
Package

swank-client.

Methods
Reader Method: state ((swank-connection swank-connection))
Writer Method: (setf state) ((swank-connection swank-connection))

State of the connection, either :ALIVE, :CLOSING, or :DEAD.

Source

swank-client.lisp.

Target Slot

state.

Generic Reader: thread-offset (object)
Package

swank-client.

Methods
Reader Method: thread-offset ((swank-connection swank-connection))

All threads for this connection are presented to Emacs with this value added to their thread ID.

Source

swank-client.lisp.

Target Slot

thread-offset.

Generic Reader: usocket (object)
Package

swank-client.

Methods
Reader Method: usocket ((swank-connection swank-connection))

USOCKET used to communicate with the Swank server.

Source

swank-client.lisp.

Target Slot

usocket.


5.2.6 Types

Type: port ()

A non-privileged TCP/IP port number.

Package

swank-client.

Source

swank-client.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   D   F   G   H   M   P   R   S   T   U   W  
Index Entry  Section

(
(setf continuation-counter): Private generic functions
(setf continuation-counter): Private generic functions
(setf rex-continuations): Private generic functions
(setf rex-continuations): Private generic functions
(setf state): Private generic functions
(setf state): Private generic functions

A
add-open-connection: Private ordinary functions

C
connection-lock: Private generic functions
connection-lock: Private generic functions
continuation-counter: Private generic functions
continuation-counter: Private generic functions

D
destructure-case: Private macros

F
find-connection-for-thread-id: Private ordinary functions
forward-event-to-worker: Private ordinary functions
Function, add-open-connection: Private ordinary functions
Function, find-connection-for-thread-id: Private ordinary functions
Function, forward-event-to-worker: Private ordinary functions
Function, remove-open-connection: Private ordinary functions
Function, send-to-emacs: Private ordinary functions
Function, server-thread-id: Private ordinary functions
Function, slime-close: Public ordinary functions
Function, slime-connect: Public ordinary functions
Function, slime-dispatch-event: Private ordinary functions
Function, slime-dispatch-events: Private ordinary functions
Function, slime-eval: Public ordinary functions
Function, slime-eval-async: Public ordinary functions
Function, slime-migrate-evals: Public ordinary functions
Function, slime-net-connect: Private ordinary functions
Function, slime-net-encode-length: Private ordinary functions
Function, slime-net-read: Private ordinary functions
Function, slime-net-send: Private ordinary functions
Function, slime-pending-evals-p: Public ordinary functions
Function, slime-secret: Private ordinary functions
Function, slime-send: Private ordinary functions
Function, socket-keep-alive: Private ordinary functions

G
Generic Function, (setf continuation-counter): Private generic functions
Generic Function, (setf rex-continuations): Private generic functions
Generic Function, (setf state): Private generic functions
Generic Function, connection-lock: Private generic functions
Generic Function, continuation-counter: Private generic functions
Generic Function, host-name: Private generic functions
Generic Function, port: Private generic functions
Generic Function, rex-continuations: Private generic functions
Generic Function, state: Private generic functions
Generic Function, thread-offset: Private generic functions
Generic Function, usocket: Private generic functions

H
host-name: Private generic functions
host-name: Private generic functions

M
Macro, destructure-case: Private macros
Macro, slime-rex: Private macros
Macro, with-slime-connection: Public macros
Method, (setf continuation-counter): Private generic functions
Method, (setf rex-continuations): Private generic functions
Method, (setf state): Private generic functions
Method, connection-lock: Private generic functions
Method, continuation-counter: Private generic functions
Method, host-name: Private generic functions
Method, port: Private generic functions
Method, rex-continuations: Private generic functions
Method, state: Private generic functions
Method, thread-offset: Private generic functions
Method, usocket: Private generic functions

P
port: Private generic functions
port: Private generic functions

R
remove-open-connection: Private ordinary functions
rex-continuations: Private generic functions
rex-continuations: Private generic functions

S
send-to-emacs: Private ordinary functions
server-thread-id: Private ordinary functions
slime-close: Public ordinary functions
slime-connect: Public ordinary functions
slime-dispatch-event: Private ordinary functions
slime-dispatch-events: Private ordinary functions
slime-eval: Public ordinary functions
slime-eval-async: Public ordinary functions
slime-migrate-evals: Public ordinary functions
slime-net-connect: Private ordinary functions
slime-net-encode-length: Private ordinary functions
slime-net-read: Private ordinary functions
slime-net-send: Private ordinary functions
slime-pending-evals-p: Public ordinary functions
slime-rex: Private macros
slime-secret: Private ordinary functions
slime-send: Private ordinary functions
socket-keep-alive: Private ordinary functions
state: Private generic functions
state: Private generic functions

T
thread-offset: Private generic functions
thread-offset: Private generic functions

U
usocket: Private generic functions
usocket: Private generic functions

W
with-slime-connection: Public macros