← ↑ → ↺ λ

3 More detailed API documentation

← ↑ → ↺ λ

3.1 Server API reference

[in package HTTP2/SERVER with nicknames HTTP2/SERVER/SHARED, HTTP2/SERVER/POLL, HTTP2/SERVER/THREADED]

• [variable] *VANILLA-SERVER-DISPATCHER* NIL

  Default value of the server dispatcher. One of DETACHED-TLS-THREADED-DISPATCHER ot POLL-DISPATCHER

• [class] TLS-SINGLE-CLIENT-DISPATCHER TLS-DISPATCHER-MIXIN SINGLE-CLIENT-DISPATCHER

• [class] DETACHED-TLS-SINGLE-CLIENT-DISPATCHER TLS-SINGLE-CLIENT-DISPATCHER

• [class] DETACHED-TLS-THREADED-DISPATCHER TLS-THREADED-DISPATCHER

• [class] TLS-THREADED-DISPATCHER THREADED-DISPATCHER TLS-DISPATCHER-MIXIN

• [class] POLL-DISPATCHER POLL-DISPATCHER-MIXIN TLS-DISPATCHER-MIXIN

  Uses poll to listen to a set of clients and handle arriving packets in a single thread.

  Maximum number of clients is fixed (by default fdset-size, by default 10). Additional clients wait Use :FDSET-SIZE to set a different value.

• [class] DETACHED-POLL-DISPATCHER POLL-DISPATCHER

  Detached version of the POLL-DISPATCHER.

← ↑ → ↺ λ

3.2 Polling server

[in package HTTP2/SERVER with nicknames HTTP2/SERVER/SHARED, HTTP2/SERVER/POLL, HTTP2/SERVER/THREADED]

← ↑ → ↺ λ

3.2.1 Interface to the application

• [class] POLL-DISPATCHER-MIXIN

  Uses poll to listen to a set of clients and handle arriving packets in a single thread.

  Maximum number of clients is fixed (by default fdset-size, by default 10). Additional clients wait until one of existing client leaves.

  Timeouts can be specified for polling.

• [accessor] GET-FDSET-SIZE POLL-DISPATCHER-MIXIN (:FDSET-SIZE)

  Number of slots for clients to be polled.

• [accessor] GET-POLL-TIMEOUT POLL-DISPATCHER-MIXIN (:POLL-TIMEOUT)

  See *POLL-TIMEOUT*.

• [accessor] GET-NO-CLIENT-POLL-TIMEOUT POLL-DISPATCHER-MIXIN (:NO-CLIENT-POLL-TIMEOUT)

  See *NO-CLIENT-POLL-TIMEOUT*.

• [variable] *NO-CLIENT-POLL-TIMEOUT* :∞

  Default timeout in seconds to use when there is no client (to limit time to a client to connect).

  This is supposed to be used primarily in the automated tests, where you do not want indefinite waits in case of a problem.

  On timeout signals POLL-TIMEOUT error.

  Default means an indefinite wait.

• [variable] *POLL-TIMEOUT* :∞

  Default timeout in seconds to use for poll when there are connected clients, but no client communication.

  On timeout signals POLL-TIMEOUT error.

  Default means an indefinite wait.

• [condition] POLL-TIMEOUT ERROR

  Poll was called with a timeout and returned before any file descriptor became ready.

• [function] COMPUTE-POLL-TIMEOUT-VALUE HUMAN-FORM

  Compute poll timeout from "nice" value (seconds or :∞) to value accepted by poll (miliseconds or -1)

← ↑ ↺

3.2.2 Client actions loop (implementation)

Each client has a STATE that encapsulates what actions are effectively possible. SELECT-NEXT-ACTION selects appropriate action. When no new action is available, next client is handled and eventually POLL called when all clients were served.

When POLL returns, new action is available for some client (read from a socket or write to it).

The actions are in general indicated by arrows in the diagram:

• [function] PROCESS-CLIENT-FD FD-PTR CLIENT

  Process events available on FD-PTR (a pointer to struct pollfd) with CLIENT.

  The new possible action corresponding to ① or ⑥ on the diagram above is added to the client state and DO-AVAILABLE-ACTIONS is called to react to that.

• [function] DO-AVAILABLE-ACTIONS CLIENT

  Run available actions as selected by SELECT-NEXT-ACTION till there is none.

• [function] SELECT-NEXT-ACTION CLIENT

  One of possible next actions consistent with then the state of the client, or nil if no action is available.

  This is factored out so that it can be traced. There is a TLS-SERVER/MEASURE::ACTIONS clip on this function.

• [function] PROCESS-DATA-ON-SOCKET CLIENT

  Read data from client socket ① and pass them to the tls buffer ② to decrypt.

• [function] ENCRYPT-DATA CLIENT

  Encrypt data in client's ENCRYPT-BUF.

  Do nothing if there is no data to encrypt or SSL not yet initialized (and return zero).

  Otherwise, use a temporary vector to write data

• [function] MOVE-ENCRYPTED-BYTES CLIENT

  Move data encrypted by OpenSSL to the socket write queue Ⓔ.

  This should be called in a way friendly to Nagle algorithm. My understaning is this is either when we pipeline a lot of data, or when we send out somethinf that expects a response.

• [function] WRITE-DATA-TO-SOCKET CLIENT

  Write buffered encrypted data Ⓔ to the client socket ⑥. Update the write buffer to keep what did not fit.