1Weft, a simple server framework

Weft is a simple network server framework, which handles the detailsof listening for connections and handing client connections off toworkers. Work management is done independently of the networkingstuff, and work managers can be created to use whatever strategy isappropriate for a server.

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

2Class Server

The server class is the top-level object for the library, andholds all the pieces necessary to run the server. When created, aclient must supply or set the :address, :port, and :handlerslots.

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.

2.1Accessors

2.1.1server-task-manager

Returns or sets the task manager for the server.

2.1.2server-socket

Returns or sets the usocket:stream-server-usocket the server islistening on. This will be NIL if the server isn't currentlyrunning, or an open socket if it's been started.

2.1.3server-address

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

2.1.4server-port

Returns or sets the port the server will listen on (a restart isrequired for changes to take effect). Can be any value acceptableto usocket:socket-listen.

2.1.5server-connection-handler

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

2.2Operations

2.2.1run

The run function is used to start the server. run's exactbehavior will depend on the task manager used: with the defaultthreaded task manager, run returns immediately, but with asingle-threaded manager it would almost certainly block.

2.2.2stop

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

2.2.3stop-accepting

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

3Default Manager

Weft provides a thread-per-connection implementation of the taskmanager (threaded-task-manager), which is used by default. Tasksbeing run on this manager obey the following protocol:

3.1shutdown

The special variable *shutdown* will be set to t when thetask should be shut down. The task must make it's own arrangementsto check *shutdown* periodically and shut down whenappropriate.

3.2thread-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, orsignal a condition of type thread-shutdown. The condition avoidsany delay in checking *shutdown*, and will be handled by the taskmanager immediately.

4Task Manager Protocol

Weft can make use of any object that implements the task manager tohandle client connections. The task manager protocol consists of thefollowing functions:

4.1add-task

4.1.1Syntax

(add-task manager thunk)

4.1.2Description

add-task takes a thunk to be run as a task and adds it to thegiven manager, returning a unique id for the task. add-task neednot start a task immediately, but it should at least be queued forlater 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.

4.2remove-task

4.2.1Syntax

(remove-task manager id)

4.2.2Description

remove-task takes a unique id as returned by add-task, andremoves the corresponding task from the manager, ifpresent. remove-task returns t if the task was found andremoved, nil otherwise.

4.3stop-task

4.3.1Syntax

(stop-task manager id)

4.3.2Description

stop-task takes a unique task id and shuts that task down, ifpresent. stop-task returns once the task has been stopped, whichmay be some time later if task shutdown is cooperative.

4.4all-tasks

4.4.1Syntax

(all-tasks manager)

4.4.2Description

Returns a list of ids for all tasks currently managed by themanager.