The swank-client Reference Manual

Table of Contents

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

The swank-client Reference Manual

This is the swank-client Reference Manual, version 1.5, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:23:39 2018 GMT+0.


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

1 Introduction


Swank Client
============

Swank Client is a Common Lisp implementation of the client side of the
Slime/Swank debugging protocol.  Emacs uses the Swank protocol to communicate
with a Lisp system when a user runs the Slime IDE.  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.


The Swank Client API
====================

swank-connection        An object representing a Swank connection.
slime-connect           Connects to a remote Common Lisp using the Swank protocol.
slime-close             Closes a Swank connection.
slime-eval              Evaluates an expression on a remote Lisp.
slime-eval-async        Evaluates an expression on a remote Lisp asynchronously.
slime-migrate-evals     Migrates work pending on one Swank connection to another.
slime-network-error     A condition that represents a network error.
slime-pending-evals-p   Does a Swank connection have unfinished work pending?
with-slime-connection   Macro that operates like with-open-file.

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


Example code for starting a Swank server
========================================

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

(defun start-swank-server-for-emacs (port)
  "Starts a Swank server thread, listening on PORT of the host's loopback
interface, to handle Emacs/Slime connection requests."
  (swank:create-server :port port :dont-close t))

(defun start-swank-server-for-swank-client (port)
  "Starts a Swank server thread, listening on PORT of the host's network
interface, to handle Swank Client connection requests."
  (let ((swank::*loopback-interface* (sb-unix:unix-gethostname)))
    (swank:create-server :port port :dont-close t)))

(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)
  (start-swank-server-for-emacs *emacs-port*)
  (start-swank-server-for-swank-client *swank-client-port*)
  (wait-for-swank-thread))


The code above starts two Swank servers.  You can connect to the server on port
4005 from Emacs using the command M-x slime-connect.  You can programmatically
connect to the second Swank server by loading the Swank Client code into your
Lisp and evaluating:

  (swank-client:slime-connect "my-host.domain.com" 10000)


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

2 Systems

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


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

2.1 swank-client

Author

Robert Brown

License

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

Description

Client side of the Swank protocol.

Long Description

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

Version

1.5

Dependencies
Source

swank-client.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 swank-client.asd

Location

swank-client.asd

Systems

swank-client (system)


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

3.1.2 swank-client/package.lisp

Parent

swank-client (system)

Location

package.lisp

Packages

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

3.1.3 swank-client/swank-client.lisp

Dependency

package.lisp (file)

Parent

swank-client (system)

Location

swank-client.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 swank-client

A client interface to Swank servers.

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

4.2 swank-printing

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

Source

package.lisp (file)


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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: slime-close CONNECTION

Closes CONNECTION to a Swank server.

Package

swank-client

Source

swank-client.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Conditions

Condition: slime-network-error ()

Network problem while evaluating a form.

Package

swank-client

Source

swank-client.lisp (file)

Direct superclasses

error (condition)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: swank-connection ()

A connection to a Swank server.

Package

swank-client

Source

swank-client.lisp (file)

Direct superclasses

standard-object (class)

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 (generic function)

Slot: port

Port number used to make a Swank server connection.

Type

swank-client::port

Initargs

:port

Readers

port (generic function)

Slot: usocket

USOCKET used to communicate with the Swank server.

Type

usocket:stream-usocket

Initargs

:usocket

Readers

usocket (generic function)

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 (generic function)

Slot: continuation-counter

Used to associate an ID with each evaluated form.

Type

(integer 0 *)

Initform

0

Readers

continuation-counter (generic function)

Writers

(setf continuation-counter) (generic function)

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 (generic function)

Writers

(setf rex-continuations) (generic function)

Slot: state

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

Type

(member :alive :closing :dead)

Initform

:alive

Readers

state (generic function)

Writers

(setf state) (generic function)

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 (generic function)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [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 (file)

Constant: +maximum-thread-count+

Maximum number of threads per Swank connection.

Package

swank-client

Source

swank-client.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Special variables

Special Variable: *connections-lock*

Lock protecting *OPEN-CONNECTIONS*.

Package

swank-client

Source

swank-client.lisp (file)

Special Variable: *io-package*
Package

swank-client

Source

swank-client.lisp (file)

Special Variable: *open-connections*

List of all open Swank connections.

Package

swank-client

Source

swank-client.lisp (file)

Special Variable: *thread-offset*

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

Package

swank-client

Source

swank-client.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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 (file)

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 (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Functions

Function: add-open-connection CONNECTION

Adds CONNECTION to the set of open Swank connections.

Package

swank-client

Source

swank-client.lisp (file)

Function: find-connection-for-thread-id THREAD-ID

Returns the open Swank connection associated with THREAD-ID.

Package

swank-client

Source

swank-client.lisp (file)

Function: remove-open-connection CONNECTION

Removes CONNECTION from the set of open Swank connections.

Package

swank-client

Source

swank-client.lisp (file)

Function: send-to-emacs EVENT

Sends EVENT to Emacs.

Package

swank-client

Source

swank-client.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

Function: slime-net-encode-length N

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

Package

swank-client

Source

swank-client.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Generic functions

Generic Function: connection-lock OBJECT
Package

swank-client

Methods
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 (file)

Generic Function: continuation-counter OBJECT
Generic Function: (setf continuation-counter) NEW-VALUE OBJECT
Package

swank-client

Methods
Method: continuation-counter (SWANK-CONNECTION swank-connection)
Method: (setf continuation-counter) NEW-VALUE (SWANK-CONNECTION swank-connection)

Used to associate an ID with each evaluated form.

Source

swank-client.lisp (file)

Generic Function: host-name OBJECT
Package

swank-client

Methods
Method: host-name (SWANK-CONNECTION swank-connection)

Name of the host where the Swank server is running.

Source

swank-client.lisp (file)

Generic Function: port OBJECT
Package

swank-client

Methods
Method: port (SWANK-CONNECTION swank-connection)

Port number used to make a Swank server connection.

Source

swank-client.lisp (file)

Generic Function: rex-continuations OBJECT
Generic Function: (setf rex-continuations) NEW-VALUE OBJECT
Package

swank-client

Methods
Method: rex-continuations (SWANK-CONNECTION swank-connection)
Method: (setf rex-continuations) NEW-VALUE (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 (file)

Generic Function: state OBJECT
Generic Function: (setf state) NEW-VALUE OBJECT
Package

swank-client

Methods
Method: state (SWANK-CONNECTION swank-connection)
Method: (setf state) NEW-VALUE (SWANK-CONNECTION swank-connection)

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

Source

swank-client.lisp (file)

Generic Function: thread-offset OBJECT
Package

swank-client

Methods
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 (file)

Generic Function: usocket OBJECT
Package

swank-client

Methods
Method: usocket (SWANK-CONNECTION swank-connection)

USOCKET used to communicate with the Swank server.

Source

swank-client.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.6 Types

Type: port ()

A non-privileged TCP/IP port number.

Package

swank-client

Source

swank-client.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, swank-client.asd: The swank-client<dot>asd file
File, Lisp, swank-client/package.lisp: The swank-client/package<dot>lisp file
File, Lisp, swank-client/swank-client.lisp: The swank-client/swank-client<dot>lisp file

L
Lisp File, swank-client.asd: The swank-client<dot>asd file
Lisp File, swank-client/package.lisp: The swank-client/package<dot>lisp file
Lisp File, swank-client/swank-client.lisp: The swank-client/swank-client<dot>lisp file

S
swank-client.asd: The swank-client<dot>asd file
swank-client/package.lisp: The swank-client/package<dot>lisp file
swank-client/swank-client.lisp: The swank-client/swank-client<dot>lisp file

Jump to:   F   L   S  

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): Internal generic functions
(setf continuation-counter): Internal generic functions
(setf rex-continuations): Internal generic functions
(setf rex-continuations): Internal generic functions
(setf state): Internal generic functions
(setf state): Internal generic functions

A
add-open-connection: Internal functions

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

D
destructure-case: Internal macros

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

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

H
host-name: Internal generic functions
host-name: Internal generic functions

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

P
port: Internal generic functions
port: Internal generic functions

R
remove-open-connection: Internal functions
rex-continuations: Internal generic functions
rex-continuations: Internal generic functions

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

T
thread-offset: Internal generic functions
thread-offset: Internal generic functions

U
usocket: Internal generic functions
usocket: Internal generic functions

W
with-slime-connection: Exported macros

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

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

A.3 Variables

Jump to:   *   +  
C   H   P   R   S   T   U  
Index Entry  Section

*
*connections-lock*: Internal special variables
*io-package*: Internal special variables
*open-connections*: Internal special variables
*thread-offset*: Internal special variables

+
+abort+: Internal constants
+maximum-thread-count+: Internal constants

C
connection-lock: Exported classes
Constant, +abort+: Internal constants
Constant, +maximum-thread-count+: Internal constants
continuation-counter: Exported classes

H
host-name: Exported classes

P
port: Exported classes

R
rex-continuations: Exported classes

S
Slot, connection-lock: Exported classes
Slot, continuation-counter: Exported classes
Slot, host-name: Exported classes
Slot, port: Exported classes
Slot, rex-continuations: Exported classes
Slot, state: Exported classes
Slot, thread-offset: Exported classes
Slot, usocket: Exported classes
Special Variable, *connections-lock*: Internal special variables
Special Variable, *io-package*: Internal special variables
Special Variable, *open-connections*: Internal special variables
Special Variable, *thread-offset*: Internal special variables
state: Exported classes

T
thread-offset: Exported classes

U
usocket: Exported classes

Jump to:   *   +  
C   H   P   R   S   T   U  

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

A.4 Data types

Jump to:   C   P   S   T  
Index Entry  Section

C
Class, swank-connection: Exported classes
Condition, slime-network-error: Exported conditions

P
Package, swank-client: The swank-client package
Package, swank-printing: The swank-printing package
port: Internal types

S
slime-network-error: Exported conditions
swank-client: The swank-client system
swank-client: The swank-client package
swank-connection: Exported classes
swank-printing: The swank-printing package
System, swank-client: The swank-client system

T
Type, port: Internal types

Jump to:   C   P   S   T