The swank-client Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The swank-client Reference Manual

This is the swank-client Reference Manual, version 1.6, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 07:18:01 2022 GMT+0.

Table of Contents


1 Introduction

Swank Client

Swank Client is a Common Lisp implementation of the client side of the Swank debugging protocol used by Slime, a GNU Emacs mode that implements an IDE for Lisp programming. Emacs uses the Swank protocol to communicate with a Lisp system when a user runs the IDE, but the protocol is useful independently of Emacs because it allows a client to evaluate expressions on a remote Lisp that's running a Swank server.

Swank Client is used by Swank Crew to implement a Slime IDE for developing distributed algorithms in Lisp.

The Swank Client API

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.

slime-close connection

Closes CONNECTION to a Swank server.

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.

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.

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.

slime-pending-evals-p connection

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

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.

For more information, see the documentation strings in swank-client.lisp and the example code in swank-client-test.lisp.

Swank Client example

Starting a Swank server

The code below starts two Swank servers, one listening on port 4005 and the other listening on port 10000.

(load-quicklisp)
(asdf:load-system 'com.google.base)
(asdf:load-system 'swank)

(defvar *emacs-port* 4005)
(defvar *swank-client-port* 10000)

(defun swank-thread ()
  "Returns a thread that's acting as a Swank server."
  (dolist (thread (sb-thread:list-all-threads))
    (when (com.google.base:prefixp "Swank" (sb-thread:thread-name thread))
      (return thread))))

(defun wait-for-swank-thread ()
  "Wait for the Swank server thread to exit."
  (let ((swank-thread (swank-thread)))
    (when swank-thread
      (sb-thread:join-thread swank-thread))))

(defun main ()
  (setf swank:*configure-emacs-indentation* nil
        swank::*enable-event-history* nil
        swank:*log-events* t)
  (swank:create-server :port *emacs-port* :dont-close t)
  (swank:create-server :port *swank-client-port* :dont-close t)
  (wait-for-swank-thread))

(main)

Using Swank Client to evaluate an expression on the server

Once the Swank servers are running, you can connect to the server on port 4005 from Emacs using the command M-x slime-connect. This connection is a normal Slime IDE session. From the Slime IDE you can evaluate the following code, which creates a Swank Client connection to the server running on port 10000 and remotely evaluates the expression (cons 1 2).

(load-quicklisp)
(asdf:load-system 'swank-client)

(swank-client:with-slime-connection (connection "localhost" 10000)
  (swank-client:slime-eval '(cons 1 2) connection))

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 swank-client

Client side of the Swank protocol.

Author

Robert Brown <robert.brown@gmail.com>

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.6

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.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

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.


Previous: , Up: Packages   [Contents][Index]

4.1 swank-client

A client interface to Swank servers.

Source

package.lisp.

Use List
  • com.google.base.
  • common-lisp.
Public Interface
Internals

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

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.


Next: , Previous: , Up: Public Interface   [Contents][Index]

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.


Previous: , Up: Public Interface   [Contents][Index]

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

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

Initargs

:port

Readers

port.

Writers

This slot is read-only.

Slot: usocket

USOCKET used to communicate with the Swank server.

Type

usocket:stream-usocket

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


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Next: , Previous: , Up: Internals   [Contents][Index]

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 PRINCed 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.


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Previous: , Up: Internals   [Contents][Index]

5.2.6 Types

Type: port ()

A non-privileged TCP/IP port number.

Package

swank-client.

Source

swank-client.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

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

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