The quux-hunchentoot Reference Manual

Table of Contents

The quux-hunchentoot Reference Manual

This is the quux-hunchentoot Reference Manual, version 1.0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:33:31 2021 GMT+0.

1 Introduction

quux-hunchentoot
================


TODO
----

Have an acceptor that listens on existing connections
so that scheduled work is done per-request as opposed to per-connection.

2 Systems

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

2.1 quux-hunchentoot

Author

Francois-Rene Rideau

License

MIT

Description

Thread pooling for hunchentoot

Version

1.0.2

Dependencies

• hunchentoot (at least version 1.2.17)
• alexandria
• bordeaux-threads
• lil
• lparallel
• trivia

Source

quux-hunchentoot.asd (file)

Components

• pkgdcl.lisp (file)
• thread-pooling.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 quux-hunchentoot.asd

Location

quux-hunchentoot.asd

Systems

quux-hunchentoot (system)

3.1.2 quux-hunchentoot/pkgdcl.lisp

Parent

quux-hunchentoot (system)

Location

pkgdcl.lisp

Packages

quux-hunchentoot

3.1.3 quux-hunchentoot/thread-pooling.lisp

Dependency

pkgdcl.lisp (file)

Parent

quux-hunchentoot (system)

Location

thread-pooling.lisp

Exported Definitions

• channel-recv (function)
• channel-send (function)
• thread-pooling-taskmaster (class)

Internal Definitions

• call-with-thread-pool (function)
• dispatcher-recv (generic function)
• dispatcher-recv (method)
• dispatcher-send (generic function)
• dispatcher-send (method)
• ensure-dispatcher-process (generic function)
• ensure-dispatcher-process (method)
• run-dispatcher-thread (generic function)
• run-dispatcher-thread (method)
• taskmaster-accept-count (method)
• (setf taskmaster-accept-count) (method)
• taskmaster-bindings (method)
• (setf taskmaster-bindings) (method)
• taskmaster-context (method)
• (setf taskmaster-context) (method)
• taskmaster-dispatcher-channel (method)
• (setf taskmaster-dispatcher-channel) (method)
• taskmaster-dispatcher-process (method)
• (setf taskmaster-dispatcher-process) (method)
• taskmaster-master-lock (method)
• taskmaster-pending-connections (method)
• (setf taskmaster-pending-connections) (method)
• taskmaster-thread-pool (method)
• (setf taskmaster-thread-pool) (method)
• with-taskmaster-accessors (macro)
• with-thread-pool (macro)
• work-on-connection (function)

4 Packages

Packages are listed by definition order.

4.1 quux-hunchentoot

Source

pkgdcl.lisp (file)

Use List

• lil/transform/classy
• trivia.level2
• lparallel
• alexandria
• hunchentoot
• common-lisp

Exported Definitions

• channel-recv (function)
• channel-send (function)
• thread-pooling-taskmaster (class)

Internal Definitions

• call-with-thread-pool (function)
• dispatcher-recv (generic function)
• dispatcher-recv (method)
• dispatcher-send (generic function)
• dispatcher-send (method)
• ensure-dispatcher-process (generic function)
• ensure-dispatcher-process (method)
• run-dispatcher-thread (generic function)
• run-dispatcher-thread (method)
• taskmaster-accept-count (generic function)
• taskmaster-accept-count (method)
• (setf taskmaster-accept-count) (method)
• (setf taskmaster-accept-count) (generic function)
• taskmaster-bindings (generic function)
• taskmaster-bindings (method)
• (setf taskmaster-bindings) (method)
• (setf taskmaster-bindings) (generic function)
• taskmaster-context (generic function)
• taskmaster-context (method)
• (setf taskmaster-context) (method)
• (setf taskmaster-context) (generic function)
• taskmaster-dispatcher-channel (generic function)
• taskmaster-dispatcher-channel (method)
• (setf taskmaster-dispatcher-channel) (method)
• (setf taskmaster-dispatcher-channel) (generic function)
• taskmaster-dispatcher-process (generic function)
• taskmaster-dispatcher-process (method)
• (setf taskmaster-dispatcher-process) (method)
• (setf taskmaster-dispatcher-process) (generic function)
• taskmaster-master-lock (generic function)
• taskmaster-master-lock (method)
• taskmaster-pending-connections (generic function)
• taskmaster-pending-connections (method)
• (setf taskmaster-pending-connections) (method)
• (setf taskmaster-pending-connections) (generic function)
• taskmaster-thread-pool (generic function)
• taskmaster-thread-pool (method)
• (setf taskmaster-thread-pool) (method)
• (setf taskmaster-thread-pool) (generic function)
• with-taskmaster-accessors (macro)
• with-thread-pool (macro)
• work-on-connection (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: channel-recv CHANNEL &key BLOCKP

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Function: channel-send CHANNEL MESSAGE

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

5.1.2 Classes

Class: thread-pooling-taskmaster ()

A taskmaster that maintains a pool of worker threads
and a queue of accepted connections to be processed.

If MAX-THREAD-COUNT is null, a new thread will always be created
when all existing workers are busy.

If MAX-THREAD-COUNT is supplied, the number of worker threads is
limited to that. Furthermore, if MAX-ACCEPT-COUNT is not supplied, an
HTTP 503 will be sent if the thread limit is exceeded. Otherwise, if MAX-ACCEPT-COUNT is supplied, it must be greater than MAX-THREAD-COUNT;
in this case, requests are accepted up to MAX-ACCEPT-COUNT, and only
then is HTTP 503 sent.

It is important to note that MAX-ACCEPT-COUNT and the HTTP 503 behavior described above is racing with the acceptor listen backlog. If we are receiving requests faster than threads can be spawned and 503 sent, the requests will be silently rejected by the kernel.

In a load-balanced environment with multiple Hunchentoot servers, it’s reasonable to provide MAX-THREAD-COUNT but leave MAX-ACCEPT-COUNT null. This will immediately result in HTTP 503 when one server is out of resources, so the load balancer can try to find another server.

In an environment with a single Hunchentoot server, it’s reasonable
to provide both MAX-THREAD-COUNT and a somewhat larger value for MAX-ACCEPT-COUNT. This will cause a server that’s almost out of
resources to wait a bit; if the server is completely out of resources,
then the reply will be HTTP 503.

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Direct superclasses

multi-threaded-taskmaster (class)

Direct methods

• run-dispatcher-thread (method)
• too-many-taskmaster-requests (method)
• handle-incoming-connection (method)
• execute-acceptor (method)
• execute-acceptor (method)
• dispatcher-recv (method)
• dispatcher-send (method)
• shutdown (method)
• increment-taskmaster-thread-count (method)
• decrement-taskmaster-thread-count (method)
• increment-taskmaster-accept-count (method)
• decrement-taskmaster-accept-count (method)
• ensure-dispatcher-process (method)
• initialize-instance (method)
• taskmaster-accept-count (method)
• taskmaster-accept-count (method)
• taskmaster-max-accept-count (method)
• taskmaster-thread-count (method)
• taskmaster-thread-count (method)
• taskmaster-max-thread-count (method)
• taskmaster-pending-connections (method)
• taskmaster-pending-connections (method)
• taskmaster-thread-pool (method)
• taskmaster-thread-pool (method)
• taskmaster-bindings (method)
• taskmaster-bindings (method)
• taskmaster-context (method)
• taskmaster-context (method)
• taskmaster-dispatcher-channel (method)
• taskmaster-dispatcher-channel (method)
• taskmaster-dispatcher-process (method)
• taskmaster-dispatcher-process (method)
• taskmaster-master-lock (method)

Direct slots

Slot: master-lock

Thread-unsafe operations without a clear owner use this lock

Initform

(bordeaux-threads:make-lock "taskmaster-master")

Readers

taskmaster-master-lock (generic function)

Slot: dispatcher-process

A process that dispatches connections to worker processes for handling, or withholds them when resources are missing.

Readers

taskmaster-dispatcher-process (generic function)

Writers

(setf taskmaster-dispatcher-process) (generic function)

Slot: dispatcher-channel

Initargs

:dispatcher-channel

Readers

taskmaster-dispatcher-channel (generic function)

Writers

(setf taskmaster-dispatcher-channel) (generic function)

Slot: context

A context function, taking a thunk as argument, and calling it within proper context, for workers in the thread pool.

Initargs

:context

Initform

(quote funcall)

Readers

taskmaster-context (generic function)

Writers

(setf taskmaster-context) (generic function)

Slot: bindings

bindings (as an alist) to wrap around workers in the thread pool.

Initargs

:bindings

Readers

taskmaster-bindings (generic function)

Writers

(setf taskmaster-bindings) (generic function)

Slot: thread-pool

A kernel to which to bind lparallel:*kernel* to handle the thread pool.

Readers

taskmaster-thread-pool (generic function)

Writers

(setf taskmaster-thread-pool) (generic function)

Slot: pending-connections

A list of pending connection socket

Initargs

:pending-connections

Initform

(lil/transform/classy:empty-fifo-queue)

Readers

taskmaster-pending-connections (generic function)

Writers

(setf taskmaster-pending-connections) (generic function)

Slot: max-thread-count

The maximum number of request threads this taskmaster will simultaneously run before refusing or queueing new connections requests. If the value is null, then there is no limit.

Type

(or integer null)

Initargs

:max-thread-count

Readers

taskmaster-max-thread-count (generic function)

Slot: thread-count

The number of taskmaster processing threads currently running.

Type

integer

Initform

0

Readers

taskmaster-thread-count (generic function)

Writers

(setf taskmaster-thread-count) (generic function)

Slot: max-accept-count

The maximum number of connections this taskmaster will accept
before refusing new connections. If supplied and an integer,
this must be greater than MAX-THREAD-COUNT.
The number of queued requests is the difference between MAX-ACCEPT-COUNT
and MAX-THREAD-COUNT. If NIL, then behave as if it were MAX-THREAD-COUNT.
If T, then keep accepting new connections until resources are exhausted (not recommended).

Type

(or integer boolean)

Initargs

:max-accept-count

Readers

taskmaster-max-accept-count (generic function)

Slot: accept-count

The number of connection currently accepted by the taskmaster. These connections are not ensured to be processed, they may be waiting for an empty processing slot or rejected because the load is too heavy.

Type

integer

Initform

0

Readers

taskmaster-accept-count (generic function)

Writers

(setf taskmaster-accept-count) (generic function)

Direct Default Initargs

Initarg	Value
:max-thread-count	hunchentoot::*default-max-thread-count*
:max-accept-count	hunchentoot::*default-max-accept-count*

5.2 Internal definitions

5.2.1 Macros

Macro: with-taskmaster-accessors SLOTS TASKMASTER &body BODY

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Macro: with-thread-pool (TASKMASTER) &body BODY

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

5.2.2 Functions

Function: call-with-thread-pool TASKMASTER THUNK

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Function: work-on-connection TASKMASTER CONNECTION

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

5.2.3 Generic functions

Generic Function: dispatcher-recv TASKMASTER &key &allow-other-keys

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Methods

Method: dispatcher-recv (TASKMASTER thread-pooling-taskmaster) &key &allow-other-keys

Generic Function: dispatcher-send TASKMASTER MESSAGE &key &allow-other-keys

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Methods

Method: dispatcher-send (TASKMASTER thread-pooling-taskmaster) MESSAGE &key &allow-other-keys

Generic Function: ensure-dispatcher-process TASKMASTER

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Methods

Method: ensure-dispatcher-process (TASKMASTER thread-pooling-taskmaster)

Generic Function: run-dispatcher-thread TASKMASTER

Package

quux-hunchentoot

Source

thread-pooling.lisp (file)

Methods

Method: run-dispatcher-thread (TASKMASTER thread-pooling-taskmaster)

Generic Function: taskmaster-accept-count OBJECT

Generic Function: (setf taskmaster-accept-count) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-accept-count (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Method: (setf taskmaster-accept-count) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

The number of connection currently accepted by the taskmaster. These connections are not ensured to be processed, they may be waiting for an empty processing slot or rejected because the load is too heavy.

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-bindings OBJECT

Generic Function: (setf taskmaster-bindings) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-bindings (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Method: (setf taskmaster-bindings) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

bindings (as an alist) to wrap around workers in the thread pool.

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-context OBJECT

Generic Function: (setf taskmaster-context) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-context (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Method: (setf taskmaster-context) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

A context function, taking a thunk as argument, and calling it within proper context, for workers in the thread pool.

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-dispatcher-channel OBJECT

Generic Function: (setf taskmaster-dispatcher-channel) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-dispatcher-channel (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

automatically generated reader method

Source

thread-pooling.lisp (file)

Method: (setf taskmaster-dispatcher-channel) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

automatically generated writer method

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-dispatcher-process OBJECT

Generic Function: (setf taskmaster-dispatcher-process) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-dispatcher-process (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Method: (setf taskmaster-dispatcher-process) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

A process that dispatches connections to worker processes for handling, or withholds them when resources are missing.

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-master-lock OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-master-lock (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Thread-unsafe operations without a clear owner use this lock

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-pending-connections OBJECT

Generic Function: (setf taskmaster-pending-connections) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-pending-connections (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Method: (setf taskmaster-pending-connections) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

A list of pending connection socket

Source

thread-pooling.lisp (file)

Generic Function: taskmaster-thread-pool OBJECT

Generic Function: (setf taskmaster-thread-pool) NEW-VALUE OBJECT

Package

quux-hunchentoot

Methods

Method: taskmaster-thread-pool (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

Method: (setf taskmaster-thread-pool) NEW-VALUE (THREAD-POOLING-TASKMASTER thread-pooling-taskmaster)

A kernel to which to bind lparallel:*kernel* to handle the thread pool.

Source

thread-pooling.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types