The quux-hunchentoot Reference Manual

This is the quux-hunchentoot Reference Manual, version 1.0.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:29:38 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 quux-hunchentoot

Thread pooling for hunchentoot

Author

Francois-Rene Rideau

License

MIT

Version

1.0.2

Dependencies
  • hunchentoot (system)., at least version "1.2.17"
  • alexandria (system).
  • bordeaux-threads (system).
  • lil (system).
  • lparallel (system).
  • trivia (system).
Source

quux-hunchentoot.asd.

Child Components

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/quux-hunchentoot.asd

Source

quux-hunchentoot.asd.

Parent Component

quux-hunchentoot (system).

ASDF Systems

quux-hunchentoot.


3.1.2 quux-hunchentoot/pkgdcl.lisp

Source

quux-hunchentoot.asd.

Parent Component

quux-hunchentoot (system).

Packages

quux-hunchentoot.


3.1.3 quux-hunchentoot/thread-pooling.lisp

Dependency

pkgdcl.lisp (file).

Source

quux-hunchentoot.asd.

Parent Component

quux-hunchentoot (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 quux-hunchentoot

Source

pkgdcl.lisp.

Use List
  • alexandria.
  • common-lisp.
  • hunchentoot.
  • lil/transform/classy.
  • lparallel.
  • trivia.level2.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: channel-recv (channel &key blockp)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.

Function: channel-send (channel message)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.


5.1.2 Standalone methods

Method: decrement-taskmaster-thread-count ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.

Method: execute-acceptor ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.

Method: execute-acceptor :around ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.

Method: handle-incoming-connection ((taskmaster thread-pooling-taskmaster) connection)
Package

hunchentoot.

Source

thread-pooling.lisp.

Method: increment-taskmaster-thread-count ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.

Method: initialize-instance :after ((taskmaster thread-pooling-taskmaster) &rest init-args)

Ensure the if MAX-ACCEPT-COUNT is supplied, that it is greater than MAX-THREAD-COUNT.

Source

thread-pooling.lisp.

Method: shutdown ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.

Reader Method: taskmaster-max-accept-count ((thread-pooling-taskmaster thread-pooling-taskmaster))

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

Package

hunchentoot.

Source

thread-pooling.lisp.

Target Slot

max-accept-count.

Reader Method: taskmaster-max-thread-count ((thread-pooling-taskmaster thread-pooling-taskmaster))

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.

Package

hunchentoot.

Source

thread-pooling.lisp.

Target Slot

max-thread-count.

Writer Method: (setf taskmaster-thread-count) ((thread-pooling-taskmaster thread-pooling-taskmaster))

The number of taskmaster processing threads currently running.

Package

hunchentoot.

Source

thread-pooling.lisp.

Target Slot

thread-count.

Reader Method: taskmaster-thread-count ((thread-pooling-taskmaster thread-pooling-taskmaster))

The number of taskmaster processing threads currently running.

Package

hunchentoot.

Source

thread-pooling.lisp.

Target Slot

thread-count.

Method: too-many-taskmaster-requests ((taskmaster thread-pooling-taskmaster) connection)
Package

hunchentoot.

Source

thread-pooling.lisp.


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

Direct superclasses

multi-threaded-taskmaster.

Direct methods
Direct Default Initargs
InitargValue
:max-thread-count*default-max-thread-count*
:max-accept-count*default-max-accept-count*
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.

Writers

This slot is read-only.

Slot: dispatcher-process

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

Readers

taskmaster-dispatcher-process.

Writers

(setf taskmaster-dispatcher-process).

Slot: dispatcher-channel
Initargs

:dispatcher-channel

Readers

taskmaster-dispatcher-channel.

Writers

(setf taskmaster-dispatcher-channel).

Slot: context

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

Initform

(quote funcall)

Initargs

:context

Readers

taskmaster-context.

Writers

(setf taskmaster-context).

Slot: bindings

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

Initargs

:bindings

Readers

taskmaster-bindings.

Writers

(setf taskmaster-bindings).

Slot: thread-pool

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

Readers

taskmaster-thread-pool.

Writers

(setf taskmaster-thread-pool).

Slot: pending-connections

A list of pending connection socket

Initform

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

Initargs

:pending-connections

Readers

taskmaster-pending-connections.

Writers

(setf taskmaster-pending-connections).

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.

Writers

This slot is read-only.

Slot: thread-count

The number of taskmaster processing threads currently running.

Type

integer

Initform

0

Readers

taskmaster-thread-count.

Writers

(setf taskmaster-thread-count).

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.

Writers

This slot is read-only.

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.

Writers

(setf taskmaster-accept-count).


5.2 Internals


5.2.1 Macros

Macro: with-taskmaster-accessors (slots taskmaster &body body)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.

Macro: with-thread-pool ((taskmaster) &body body)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.


5.2.2 Ordinary functions

Function: call-with-thread-pool (taskmaster thunk)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.

Function: work-on-connection (taskmaster connection)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.


5.2.3 Generic functions

Generic Function: dispatcher-recv (taskmaster &key &allow-other-keys)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.

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.

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.

Methods
Method: ensure-dispatcher-process ((taskmaster thread-pooling-taskmaster))
Generic Function: run-dispatcher-thread (taskmaster)
Package

quux-hunchentoot.

Source

thread-pooling.lisp.

Methods
Method: run-dispatcher-thread ((taskmaster thread-pooling-taskmaster))
Generic Reader: taskmaster-accept-count (object)
Generic Writer: (setf taskmaster-accept-count) (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-accept-count ((thread-pooling-taskmaster thread-pooling-taskmaster))
Writer Method: (setf taskmaster-accept-count) ((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.

Target Slot

accept-count.

Generic Reader: taskmaster-bindings (object)
Generic Writer: (setf taskmaster-bindings) (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-bindings ((thread-pooling-taskmaster thread-pooling-taskmaster))
Writer Method: (setf taskmaster-bindings) ((thread-pooling-taskmaster thread-pooling-taskmaster))

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

Source

thread-pooling.lisp.

Target Slot

bindings.

Generic Reader: taskmaster-context (object)
Generic Writer: (setf taskmaster-context) (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-context ((thread-pooling-taskmaster thread-pooling-taskmaster))
Writer Method: (setf taskmaster-context) ((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.

Target Slot

context.

Generic Reader: taskmaster-dispatcher-channel (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-dispatcher-channel ((thread-pooling-taskmaster thread-pooling-taskmaster))

automatically generated reader method

Source

thread-pooling.lisp.

Target Slot

dispatcher-channel.

Generic Writer: (setf taskmaster-dispatcher-channel) (object)
Package

quux-hunchentoot.

Methods
Writer Method: (setf taskmaster-dispatcher-channel) ((thread-pooling-taskmaster thread-pooling-taskmaster))

automatically generated writer method

Source

thread-pooling.lisp.

Target Slot

dispatcher-channel.

Generic Reader: taskmaster-dispatcher-process (object)
Generic Writer: (setf taskmaster-dispatcher-process) (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-dispatcher-process ((thread-pooling-taskmaster thread-pooling-taskmaster))
Writer Method: (setf taskmaster-dispatcher-process) ((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.

Target Slot

dispatcher-process.

Generic Reader: taskmaster-master-lock (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-master-lock ((thread-pooling-taskmaster thread-pooling-taskmaster))

Thread-unsafe operations without a clear owner use this lock

Source

thread-pooling.lisp.

Target Slot

master-lock.

Generic Reader: taskmaster-pending-connections (object)
Generic Writer: (setf taskmaster-pending-connections) (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-pending-connections ((thread-pooling-taskmaster thread-pooling-taskmaster))
Writer Method: (setf taskmaster-pending-connections) ((thread-pooling-taskmaster thread-pooling-taskmaster))

A list of pending connection socket

Source

thread-pooling.lisp.

Target Slot

pending-connections.

Generic Reader: taskmaster-thread-pool (object)
Generic Writer: (setf taskmaster-thread-pool) (object)
Package

quux-hunchentoot.

Methods
Reader Method: taskmaster-thread-pool ((thread-pooling-taskmaster thread-pooling-taskmaster))
Writer Method: (setf taskmaster-thread-pool) ((thread-pooling-taskmaster thread-pooling-taskmaster))

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

Source

thread-pooling.lisp.

Target Slot

thread-pool.


5.2.4 Standalone methods

Method: decrement-taskmaster-accept-count ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.

Method: increment-taskmaster-accept-count ((taskmaster thread-pooling-taskmaster))
Package

hunchentoot.

Source

thread-pooling.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   E   F   G   H   I   M   R   S   T   W  
Index Entry  Section

(
(setf taskmaster-accept-count): Private generic functions
(setf taskmaster-accept-count): Private generic functions
(setf taskmaster-bindings): Private generic functions
(setf taskmaster-bindings): Private generic functions
(setf taskmaster-context): Private generic functions
(setf taskmaster-context): Private generic functions
(setf taskmaster-dispatcher-channel): Private generic functions
(setf taskmaster-dispatcher-channel): Private generic functions
(setf taskmaster-dispatcher-process): Private generic functions
(setf taskmaster-dispatcher-process): Private generic functions
(setf taskmaster-pending-connections): Private generic functions
(setf taskmaster-pending-connections): Private generic functions
(setf taskmaster-thread-count): Public standalone methods
(setf taskmaster-thread-pool): Private generic functions
(setf taskmaster-thread-pool): Private generic functions

C
call-with-thread-pool: Private ordinary functions
channel-recv: Public ordinary functions
channel-send: Public ordinary functions

D
decrement-taskmaster-accept-count: Private standalone methods
decrement-taskmaster-thread-count: Public standalone methods
dispatcher-recv: Private generic functions
dispatcher-recv: Private generic functions
dispatcher-send: Private generic functions
dispatcher-send: Private generic functions

E
ensure-dispatcher-process: Private generic functions
ensure-dispatcher-process: Private generic functions
execute-acceptor: Public standalone methods
execute-acceptor: Public standalone methods

F
Function, call-with-thread-pool: Private ordinary functions
Function, channel-recv: Public ordinary functions
Function, channel-send: Public ordinary functions
Function, work-on-connection: Private ordinary functions

G
Generic Function, (setf taskmaster-accept-count): Private generic functions
Generic Function, (setf taskmaster-bindings): Private generic functions
Generic Function, (setf taskmaster-context): Private generic functions
Generic Function, (setf taskmaster-dispatcher-channel): Private generic functions
Generic Function, (setf taskmaster-dispatcher-process): Private generic functions
Generic Function, (setf taskmaster-pending-connections): Private generic functions
Generic Function, (setf taskmaster-thread-pool): Private generic functions
Generic Function, dispatcher-recv: Private generic functions
Generic Function, dispatcher-send: Private generic functions
Generic Function, ensure-dispatcher-process: Private generic functions
Generic Function, run-dispatcher-thread: Private generic functions
Generic Function, taskmaster-accept-count: Private generic functions
Generic Function, taskmaster-bindings: Private generic functions
Generic Function, taskmaster-context: Private generic functions
Generic Function, taskmaster-dispatcher-channel: Private generic functions
Generic Function, taskmaster-dispatcher-process: Private generic functions
Generic Function, taskmaster-master-lock: Private generic functions
Generic Function, taskmaster-pending-connections: Private generic functions
Generic Function, taskmaster-thread-pool: Private generic functions

H
handle-incoming-connection: Public standalone methods

I
increment-taskmaster-accept-count: Private standalone methods
increment-taskmaster-thread-count: Public standalone methods
initialize-instance: Public standalone methods

M
Macro, with-taskmaster-accessors: Private macros
Macro, with-thread-pool: Private macros
Method, (setf taskmaster-accept-count): Private generic functions
Method, (setf taskmaster-bindings): Private generic functions
Method, (setf taskmaster-context): Private generic functions
Method, (setf taskmaster-dispatcher-channel): Private generic functions
Method, (setf taskmaster-dispatcher-process): Private generic functions
Method, (setf taskmaster-pending-connections): Private generic functions
Method, (setf taskmaster-thread-count): Public standalone methods
Method, (setf taskmaster-thread-pool): Private generic functions
Method, decrement-taskmaster-accept-count: Private standalone methods
Method, decrement-taskmaster-thread-count: Public standalone methods
Method, dispatcher-recv: Private generic functions
Method, dispatcher-send: Private generic functions
Method, ensure-dispatcher-process: Private generic functions
Method, execute-acceptor: Public standalone methods
Method, execute-acceptor: Public standalone methods
Method, handle-incoming-connection: Public standalone methods
Method, increment-taskmaster-accept-count: Private standalone methods
Method, increment-taskmaster-thread-count: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, run-dispatcher-thread: Private generic functions
Method, shutdown: Public standalone methods
Method, taskmaster-accept-count: Private generic functions
Method, taskmaster-bindings: Private generic functions
Method, taskmaster-context: Private generic functions
Method, taskmaster-dispatcher-channel: Private generic functions
Method, taskmaster-dispatcher-process: Private generic functions
Method, taskmaster-master-lock: Private generic functions
Method, taskmaster-max-accept-count: Public standalone methods
Method, taskmaster-max-thread-count: Public standalone methods
Method, taskmaster-pending-connections: Private generic functions
Method, taskmaster-thread-count: Public standalone methods
Method, taskmaster-thread-pool: Private generic functions
Method, too-many-taskmaster-requests: Public standalone methods

R
run-dispatcher-thread: Private generic functions
run-dispatcher-thread: Private generic functions

S
shutdown: Public standalone methods

T
taskmaster-accept-count: Private generic functions
taskmaster-accept-count: Private generic functions
taskmaster-bindings: Private generic functions
taskmaster-bindings: Private generic functions
taskmaster-context: Private generic functions
taskmaster-context: Private generic functions
taskmaster-dispatcher-channel: Private generic functions
taskmaster-dispatcher-channel: Private generic functions
taskmaster-dispatcher-process: Private generic functions
taskmaster-dispatcher-process: Private generic functions
taskmaster-master-lock: Private generic functions
taskmaster-master-lock: Private generic functions
taskmaster-max-accept-count: Public standalone methods
taskmaster-max-thread-count: Public standalone methods
taskmaster-pending-connections: Private generic functions
taskmaster-pending-connections: Private generic functions
taskmaster-thread-count: Public standalone methods
taskmaster-thread-pool: Private generic functions
taskmaster-thread-pool: Private generic functions
too-many-taskmaster-requests: Public standalone methods

W
with-taskmaster-accessors: Private macros
with-thread-pool: Private macros
work-on-connection: Private ordinary functions