The weft Reference Manual

Table of Contents

The weft Reference Manual

This is the weft Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 18:16:12 2021 GMT+0.

1 Introduction

* Weft, a simple server framework
  Weft is a simple network server framework, which handles the details
  of listening for connections and handing client connections off to
  workers. Work management is done independently of the networking
  stuff, and work managers can be created to use whatever strategy is
  appropriate for a server.

  Unlike [[http://www.thangorodrim.de/software/lisp-network-server/index.html][lisp-network-server]], Weft does not aim to be an
  inetd-alike. This simplifies some of the code and allows services to
  use different work management strategies. At the moment,
  lisp-network-service's caveats about re-defining handlers still hold.

* Class Server
  The =server= class is the top-level object for the library, and
  holds all the pieces necessary to run the server. When created, a
  client must supply or set the =:address=, =:port=, and =:handler=
  slots.

  Optionally, clients may set the =:manager= slot, which is the task
  manager for the server. Clients may also set the =:max-connections=
  slot, which will cause the server to refuse new connections when
  that many concurrent connections are open. The same limit can be
  applied to the threaded task manager with the =:limit= option. If a
  manager is supplied with =:manager=, the manager's limit will take
  precededence.
** Accessors
*** server-task-manager
    Returns or sets the task manager for the server.

*** server-socket
    Returns or sets the =usocket:stream-server-usocket= the server is
    listening on. This will be NIL if the server isn't currently
    running, or an open socket if it's been started.

*** server-address
    Returns or sets the address the server will listen on (the server
    must be restarted in order for any change to take affect). Can be
    any value acceptable to =usocket:socket-listen=.

*** server-port
    Returns or sets the port the server will listen on (a restart is
    required for changes to take effect). Can be any value acceptable
    to =usocket:socket-listen=.

*** server-connection-handler
    Returns or sets the connection-handler function for the
    server. This function will be called by a wrapper that ensures the
    client socket is closed when the handler exits. The handler will
    be called with a =usocket:stream-usocket= object and any =:args=
    arguments set when the server object was created.

** Operations
*** run
    The =run= function is used to start the server. =run='s exact
    behavior will depend on the task manager used: with the default
    threaded task manager, =run= returns immediately, but with a
    single-threaded manager it would almost certainly block.

*** stop
    =stop= shuts the server down, including any open client
    connections. With some task managers client connection shutdown may
    be cooperative, so this function may be blocked for some
    time. =stop= returns once the server has been completely shut down.

*** stop-accepting
    =stop-accepting= is like =stop=, but only shuts down the listening
    socket. Client connections are allowed to continue until they are
    closed by the clients. =stop-accepting= returns as soon as the
    listening socket has been shut down.

* Default Manager
  Weft provides a thread-per-connection implementation of the task
  manager (=threaded-task-manager=), which is used by default. Tasks
  being run on this manager obey the following protocol:
** *shutdown*
   The special variable =*shutdown*= will be set to =t= when the
   task should be shut down. The task must make it's own arrangements
   to check =*shutdown*= periodically and shut down when
   appropriate.

** thread-shutdown
   If a task wants to signal that it should be shut down, it may set
   =*shutdown*= to =t= and let it's own handlers take care of it, or
   signal a condition of type =thread-shutdown=. The condition avoids
   any delay in checking =*shutdown*=, and will be handled by the task
   manager immediately.

* Task Manager Protocol
  Weft can make use of any object that implements the task manager to
  handle client connections. The task manager protocol consists of the
  following functions:

** add-task
*** Syntax
    : (add-task manager thunk)
*** Description
   =add-task= takes a thunk to be run as a task and adds it to the
   given manager, returning a unique id for the task. =add-task= need
   not start a task immediately, but it should at least be queued for
   later execution.

   If a manager has a limit on the maximum number of concurrent tasks
   that can be running, =add-task= should signal an error of type
   =manager-full-error=.

** remove-task
*** Syntax
    : (remove-task manager id)
*** Description
    =remove-task= takes a unique id as returned by =add-task=, and
    removes the corresponding task from the manager, if
    present. =remove-task= returns =t= if the task was found and
    removed, =nil= otherwise.

** stop-task
*** Syntax
    : (stop-task manager id)
*** Description
    =stop-task= takes a unique task id and shuts that task down, if
    present. =stop-task= returns once the task has been stopped, which
    may be some time later if task shutdown is cooperative.

** all-tasks
*** Syntax
    : (all-tasks manager)
*** Description
    Returns a list of ids for all tasks currently managed by the
    manager.

2 Systems

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

2.1 weft

Author

Matthew Stickney <mtstickney@gmail.com>

License

MIT

Description

A TCP server framework, like Hunchentoot for TCP.

Dependencies

• usocket
• bordeaux-threads
• log4cl
• trivial-timeout

Source

weft.asd (file)

Components

• package.lisp (file)
• weft.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 weft.asd

Location

weft.asd

Systems

weft (system)

3.1.2 weft/package.lisp

Parent

weft (system)

Location

package.lisp

Packages

weft

3.1.3 weft/weft.lisp

Dependency

package.lisp (file)

Parent

weft (system)

Location

weft.lisp

Exported Definitions

• *shutdown* (symbol macro)
• add-task (generic function)
• add-task (method)
• all-tasks (generic function)
• all-tasks (method)
• find-task (generic function)
• find-task (method)
• manager-full-error (condition)
• remove-task (generic function)
• remove-task (method)
• run (generic function)
• run (method)
• server (class)
• server-address (method)
• (setf server-address) (method)
• server-connection-handler (method)
• (setf server-connection-handler) (method)
• server-port (method)
• (setf server-port) (method)
• server-socket (method)
• (setf server-socket) (method)
• server-task-manager (method)
• (setf server-task-manager) (method)
• slots-available-p (generic function)
• slots-available-p (method)
• stop (generic function)
• stop (method)
• stop-accepting (generic function)
• stop-accepting (method)
• stop-task (generic function)
• stop-task (method)
• task-manager (class)
• thread-shutdown (condition)
• threaded-task-manager (class)

Internal Definitions

• %ref-lock (function)
• (setf %ref-lock) (function)
• %ref-val (function)
• (setf %ref-val) (function)
• *id-counter* (special variable)
• acceptor-func (function)
• connection-handler-func (function)
• copy-ref (function)
• gen-id (function)
• make-ref (function)
• manager (method)
• (setf manager) (method)
• max-connections (method)
• prompt-for (function)
• ref (structure)
• ref-p (function)
• ref-val (function)
• (setf ref-val) (function)
• server-acceptor-task (method)
• (setf server-acceptor-task) (method)
• server-handler-args (method)
• (setf server-handler-args) (method)
• shutdown-vars (method)
• (setf shutdown-vars) (method)
• size-of (function)
• task-count (method)
• (setf task-count) (method)
• task-exists-error (condition)
• task-id (method)
• (setf task-id) (method)
• task-limit (method)
• (setf task-limit) (method)
• task-lock (method)
• task-shutdown-p (generic function)
• task-shutdown-p (method)
• (setf task-shutdown-p) (method)
• (setf task-shutdown-p) (generic function)
• tasks (method)
• (setf tasks) (method)

4 Packages

Packages are listed by definition order.

4.1 weft

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *shutdown* (symbol macro)
• add-task (generic function)
• add-task (method)
• all-tasks (generic function)
• all-tasks (method)
• find-task (generic function)
• find-task (method)
• manager-full-error (condition)
• remove-task (generic function)
• remove-task (method)
• run (generic function)
• run (method)
• server (class)
• server-address (generic function)
• server-address (method)
• (setf server-address) (method)
• (setf server-address) (generic function)
• server-connection-handler (generic function)
• server-connection-handler (method)
• (setf server-connection-handler) (method)
• (setf server-connection-handler) (generic function)
• server-port (generic function)
• server-port (method)
• (setf server-port) (method)
• (setf server-port) (generic function)
• server-socket (generic function)
• server-socket (method)
• (setf server-socket) (method)
• (setf server-socket) (generic function)
• server-task-manager (generic function)
• server-task-manager (method)
• (setf server-task-manager) (method)
• (setf server-task-manager) (generic function)
• slots-available-p (generic function)
• slots-available-p (method)
• stop (generic function)
• stop (method)
• stop-accepting (generic function)
• stop-accepting (method)
• stop-task (generic function)
• stop-task (method)
• task-manager (class)
• thread-shutdown (condition)
• threaded-task-manager (class)

Internal Definitions

• %ref-lock (function)
• (setf %ref-lock) (function)
• %ref-val (function)
• (setf %ref-val) (function)
• *id-counter* (special variable)
• acceptor-func (function)
• connection-handler-func (function)
• copy-ref (function)
• gen-id (function)
• make-ref (function)
• manager (generic function)
• manager (method)
• (setf manager) (method)
• (setf manager) (generic function)
• max-connections (generic function)
• max-connections (method)
• prompt-for (function)
• ref (structure)
• ref-p (function)
• ref-val (function)
• (setf ref-val) (function)
• server-acceptor-task (generic function)
• server-acceptor-task (method)
• (setf server-acceptor-task) (method)
• (setf server-acceptor-task) (generic function)
• server-handler-args (generic function)
• server-handler-args (method)
• (setf server-handler-args) (method)
• (setf server-handler-args) (generic function)
• shutdown-vars (generic function)
• shutdown-vars (method)
• (setf shutdown-vars) (method)
• (setf shutdown-vars) (generic function)
• size-of (function)
• task-count (generic function)
• task-count (method)
• (setf task-count) (method)
• (setf task-count) (generic function)
• task-exists-error (condition)
• task-id (generic function)
• task-id (method)
• (setf task-id) (method)
• (setf task-id) (generic function)
• task-limit (generic function)
• task-limit (method)
• (setf task-limit) (method)
• (setf task-limit) (generic function)
• task-lock (generic function)
• task-lock (method)
• task-shutdown-p (generic function)
• task-shutdown-p (method)
• (setf task-shutdown-p) (method)
• (setf task-shutdown-p) (generic function)
• tasks (generic function)
• tasks (method)
• (setf tasks) (method)
• (setf tasks) (generic function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Symbol macros

Symbol Macro: *shutdown*

Package

weft

Source

weft.lisp (file)

Expansion

(weft::ref-val weft::*shutdown-slot*)

5.1.2 Generic functions

Generic Function: add-task MANAGER THUNK

Add a task to execute THUNK to MANAGER. Returns a
unique ID for the task. If the manager cannot accept a new task, signals an error of type MANAGER-FULL-ERROR.

Package

weft

Source

weft.lisp (file)

Methods

Method: add-task (MANAGER threaded-task-manager) THUNK

Generic Function: all-tasks MANAGER

Return a list of the ids of all tasks in MANAGER.

Package

weft

Source

weft.lisp (file)

Methods

Method: all-tasks (MANAGER threaded-task-manager)

Generic Function: find-task MANAGER TASK-ID

Return the entry for TASK-ID from MANAGER.

Package

weft

Source

weft.lisp (file)

Methods

Method: find-task (MANAGER threaded-task-manager) (TASK symbol)

Generic Function: remove-task MANAGER TASK

Remove TASK from the task-manager MANAGER.

Package

weft

Source

weft.lisp (file)

Methods

Method: remove-task (MANAGER threaded-task-manager) (TASK symbol)

Generic Function: run SERVER &key BACKLOG ELEMENT-TYPE

Package

weft

Source

weft.lisp (file)

Methods

Method: run (SERVER server) &key BACKLOG ELEMENT-TYPE

Generic Function: server-address OBJECT

Generic Function: (setf server-address) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-address (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-address) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: server-connection-handler OBJECT

Generic Function: (setf server-connection-handler) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-connection-handler (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-connection-handler) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: server-port OBJECT

Generic Function: (setf server-port) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-port (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-port) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: server-socket OBJECT

Generic Function: (setf server-socket) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-socket (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-socket) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: server-task-manager OBJECT

Generic Function: (setf server-task-manager) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-task-manager (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-task-manager) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: slots-available-p MANAGER

Return T if there is capacity to add a new task to MANAGER, NIL otherwise.

Package

weft

Source

weft.lisp (file)

Methods

Method: slots-available-p (MANAGER threaded-task-manager)

Generic Function: stop SERVER

Package

weft

Source

weft.lisp (file)

Methods

Method: stop (SERVER server)

Generic Function: stop-accepting SERVER

Package

weft

Source

weft.lisp (file)

Methods

Method: stop-accepting (SERVER server)

Generic Function: stop-task MANAGER TASK

Perform shutdown of the TASK in MANAGER.

Package

weft

Source

weft.lisp (file)

Methods

Method: stop-task (MANAGER threaded-task-manager) (TASK symbol)

5.1.3 Conditions

Condition: manager-full-error ()

Package

weft

Source

weft.lisp (file)

Direct superclasses

error (condition)

Direct methods

• manager (method)
• manager (method)

Direct slots

Slot: manager

Initargs

:manager

Readers

manager (generic function)

Writers

(setf manager) (generic function)

Condition: thread-shutdown ()

Package

weft

Source

weft.lisp (file)

Direct superclasses

condition (condition)

5.1.4 Classes

Class: server ()

Package

weft

Source

weft.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• stop-accepting (method)
• stop (method)
• run (method)
• initialize-instance (method)
• server-handler-args (method)
• server-handler-args (method)
• server-connection-handler (method)
• server-connection-handler (method)
• server-acceptor-task (method)
• server-acceptor-task (method)
• max-connections (method)
• server-port (method)
• server-port (method)
• server-address (method)
• server-address (method)
• server-socket (method)
• server-socket (method)
• server-task-manager (method)
• server-task-manager (method)

Direct slots

Slot: task-manager

Initargs

:manager

Readers

server-task-manager (generic function)

Writers

(setf server-task-manager) (generic function)

Slot: socket

Readers

server-socket (generic function)

Writers

(setf server-socket) (generic function)

Slot: address

Initargs

:address

Readers

server-address (generic function)

Writers

(setf server-address) (generic function)

Slot: port

Initargs

:port

Readers

server-port (generic function)

Writers

(setf server-port) (generic function)

Slot: max-connections

Initargs

:max-connections

Readers

max-connections (generic function)

Slot: acceptor-task

Readers

server-acceptor-task (generic function)

Writers

(setf server-acceptor-task) (generic function)

Slot: connection-handler

Initargs

:handler

Readers

server-connection-handler (generic function)

Writers

(setf server-connection-handler) (generic function)

Slot: handler-args

Initargs

:args

Readers

server-handler-args (generic function)

Writers

(setf server-handler-args) (generic function)

Direct Default Initargs

Initarg	Value
:args	(quote nil)

Class: task-manager ()

Package

weft

Source

weft.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

threaded-task-manager (class)

Direct methods

• task-count (method)
• task-count (method)
• task-limit (method)
• task-limit (method)

Direct slots

Slot: limit

Initargs

:limit

Readers

task-limit (generic function)

Writers

(setf task-limit) (generic function)

Slot: count

Initform

0

Readers

task-count (generic function)

Writers

(setf task-count) (generic function)

Direct Default Initargs

Initarg	Value
:limit	nil

Class: threaded-task-manager ()

Class implementing a thread-per-connection task manager.

Package

weft

Source

weft.lisp (file)

Direct superclasses

task-manager (class)

Direct methods

• slots-available-p (method)
• all-tasks (method)
• remove-task (method)
• stop-task (method)
• add-task (method)
• task-shutdown-p (method)
• task-shutdown-p (method)
• find-task (method)
• shutdown-vars (method)
• shutdown-vars (method)
• task-lock (method)
• tasks (method)
• tasks (method)

Direct slots

Slot: tasks

Initform

(quote nil)

Readers

tasks (generic function)

Writers

(setf tasks) (generic function)

Slot: task-lock

Initform

(bordeaux-threads:make-recursive-lock)

Readers

task-lock (generic function)

Slot: shutdown-vars

Initform

(make-hash-table :test (function equal))

Readers

shutdown-vars (generic function)

Writers

(setf shutdown-vars) (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *id-counter*

Package

weft

Source

weft.lisp (file)

5.2.2 Functions

Function: %ref-lock INSTANCE

Function: (setf %ref-lock) VALUE INSTANCE

Package

weft

Source

weft.lisp (file)

Function: %ref-val INSTANCE

Function: (setf %ref-val) VALUE INSTANCE

Package

weft

Source

weft.lisp (file)

Function: acceptor-func SERVER

Package

weft

Source

weft.lisp (file)

Function: connection-handler-func SERVER SOCK HANDLER

Return a wrapper func for HANDLER that will ensure SOCK is closed at exit.

Package

weft

Source

weft.lisp (file)

Function: copy-ref INSTANCE

Package

weft

Source

weft.lisp (file)

Function: gen-id ()

Package

weft

Source

weft.lisp (file)

Function: make-ref &key (VAL VAL) (LOCK LOCK)

Package

weft

Source

weft.lisp (file)

Function: prompt-for TYPE FORMAT-STRING &rest FORMAT-ARGS

Prompt for a value of type TYPE, using FORMAT-STRING and FORMAT-ARGS to produce the prompt. Signals an error if the value read is not of type TYPE.

Package

weft

Source

weft.lisp (file)

Function: ref-p OBJECT

Package

weft

Source

weft.lisp (file)

Function: ref-val REF

Function: (setf ref-val) VAL REF

Package

weft

Source

weft.lisp (file)

Function: size-of OBJ

Package

weft

Source

weft.lisp (file)

5.2.3 Generic functions

Generic Function: manager CONDITION

Generic Function: (setf manager) NEW-VALUE CONDITION

Package

weft

Methods

Method: manager (CONDITION manager-full-error)

Method: (setf manager) NEW-VALUE (CONDITION manager-full-error)

Source

weft.lisp (file)

Generic Function: max-connections OBJECT

Package

weft

Methods

Method: max-connections (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Generic Function: server-acceptor-task OBJECT

Generic Function: (setf server-acceptor-task) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-acceptor-task (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-acceptor-task) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: server-handler-args OBJECT

Generic Function: (setf server-handler-args) NEW-VALUE OBJECT

Package

weft

Methods

Method: server-handler-args (SERVER server)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf server-handler-args) NEW-VALUE (SERVER server)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: shutdown-vars OBJECT

Generic Function: (setf shutdown-vars) NEW-VALUE OBJECT

Package

weft

Methods

Method: shutdown-vars (THREADED-TASK-MANAGER threaded-task-manager)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf shutdown-vars) NEW-VALUE (THREADED-TASK-MANAGER threaded-task-manager)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: task-count OBJECT

Generic Function: (setf task-count) NEW-VALUE OBJECT

Package

weft

Methods

Method: task-count (TASK-MANAGER task-manager)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf task-count) NEW-VALUE (TASK-MANAGER task-manager)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: task-id CONDITION

Generic Function: (setf task-id) NEW-VALUE CONDITION

Package

weft

Methods

Method: task-id (CONDITION task-exists-error)

Method: (setf task-id) NEW-VALUE (CONDITION task-exists-error)

Source

weft.lisp (file)

Generic Function: task-limit OBJECT

Generic Function: (setf task-limit) NEW-VALUE OBJECT

Package

weft

Methods

Method: task-limit (TASK-MANAGER task-manager)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf task-limit) NEW-VALUE (TASK-MANAGER task-manager)

automatically generated writer method

Source

weft.lisp (file)

Generic Function: task-lock OBJECT

Package

weft

Methods

Method: task-lock (THREADED-TASK-MANAGER threaded-task-manager)

automatically generated reader method

Source

weft.lisp (file)

Generic Function: task-shutdown-p MANAGER TASK-ID

Return a boolean indicating whether the task identified by TASK-ID in MANAGER should shut down.

Package

weft

Source

weft.lisp (file)

Writer

(setf task-shutdown-p) (generic function)

Methods

Method: task-shutdown-p (MANAGER threaded-task-manager) (TASK-ID symbol)

Generic Function: (setf task-shutdown-p) NEW-VAL MANAGER TASK-ID

Set the shutdown variable for the task identified by TASK-ID in MANAGER to NEW-VAL.

Package

weft

Source

weft.lisp (file)

Reader

task-shutdown-p (generic function)

Methods

Method: (setf task-shutdown-p) NEW-VAL (MANAGER threaded-task-manager) (TASK-ID symbol)

Generic Function: tasks OBJECT

Generic Function: (setf tasks) NEW-VALUE OBJECT

Package

weft

Methods

Method: tasks (THREADED-TASK-MANAGER threaded-task-manager)

automatically generated reader method

Source

weft.lisp (file)

Method: (setf tasks) NEW-VALUE (THREADED-TASK-MANAGER threaded-task-manager)

automatically generated writer method

Source

weft.lisp (file)

5.2.4 Conditions

Condition: task-exists-error ()

Error thrown when a task with a particular ID already exists.

Package

weft

Source

weft.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• task-id (method)
• task-id (method)

Direct slots

Slot: id

Initargs

:id

Readers

task-id (generic function)

Writers

(setf task-id) (generic function)

5.2.5 Structures

Structure: ref ()

Package

weft

Source

weft.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: val

Readers

%ref-val (function)

Writers

(setf %ref-val) (function)

Slot: lock

Initform

(bordeaux-threads:make-lock)

Readers

%ref-lock (function)

Writers

(setf %ref-lock) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types