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 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.
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
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.
Returns or sets the task manager for the server.
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.
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
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
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.
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 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 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.
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:
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.
If a task wants to signal that it should be shut down, it may set
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 manager thunk)
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
(remove-task manager id)
remove-task takes a unique id as returned by
add-task, and removes the corresponding task from the manager, if present.
t if the task was found and removed,
(stop-task manager id)
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.
Returns a list of ids for all tasks currently managed by the manager.
- Matthew Stickney <firstname.lastname@example.org>