Compare commits

..
Author SHA1 Message Date
yhirose 51b186974b Run the test suite with keep-alive parking on in CI, and mark it experimental
CPPHTTPLIB_KEEPALIVE_PARKING makes every Server start with parking on.
The OpenSSL jobs on Ubuntu (epoll) and macOS (kqueue) now also run the
whole suite built with it, which used to be done only locally. The two
tests that check the blocking path turn parking off explicitly. README
and the cookbook call the feature experimental and say that a server
whose event loop cannot be set up serves as it does without it.
2026-11-21 21:23:22 -05:00
yhirose f09081e320 Describe keep-alive parking in the Keep-Alive cookbook page 2026-11-21 21:23:22 -05:00
yhirose b2a81c0019 Add keep-alive parking (Server::set_keep_alive_parking())
A kept-alive connection holds a worker thread while it waits for its
next request, so connections beyond the thread count wait for one to be
closed, and some clients get nothing until another connection ends.

With keep-alive parking, listen() runs an event loop on the
detail::Poller instead of the blocking accept loop. A connection waiting
for its next request is parked there and goes back to a worker through
the TaskQueue when the request arrives. The handlers, content providers
and WebSocket keep their blocking API and still hold a thread while they
run. SSLServer supports it too: a worker runs the TLS handshake once the
client starts it, and the session stays with the parked connection.

It is opt-in and off by default. With it on:
- consecutive requests on a connection may run on different threads;
- when the queue is full, a connection that has not been served (or has
  not finished its TLS handshake) is closed as before, while an
  established one waits in a backlog instead of losing its request;
- a parked connection frees its read buffer, and with OpenSSL 3.0.14,
  3.1.6, 3.2.2, 3.3.1 or later also its TLS record buffers;
- handing a connection over adds roughly 10-20 us to a request;
- a subclass that overrides the private process_and_close_socket() is
  bypassed.

On two CPUs with two workers, 50 keep-alive clients of a 2.7 ms handler
were all served evenly (the slowest response took about 70 ms instead of
5 s, with 10 clients getting nothing), light requests from 50 clients
went from 79k to about 240k per second, and with 10000 idle connections
parked, 10 active clients got 95k requests per second where the old loop
served none. An idle connection costs under 1 KB, or about 15 KB with
TLS.

The old accept loop moved unchanged into accept_loop(). KeepAliveConnection
holds a parked connection, PlainConnection and SSLServer::TlsConnection
add the transport, and SSLServer::start_session() holds the session setup
and handshake that both paths use.
2026-11-21 21:23:22 -05:00
yhirose d8da76a4a5 Pass the keep-alive wait and the served count into the server loop
process_server_socket_core() now takes the function that waits for the
next request and the number of requests served so far, instead of
calling keep_alive() and counting on its own stack. Both callers pass
keep_alive() and a fresh counter, so nothing changes yet; this lets a
caller stop waiting and resume the same connection later without losing
track of keep_alive_max_count.
2026-11-21 21:23:22 -05:00
yhirose 581a615f7c Add a one-shot Poller with poll, epoll and kqueue backends
Groundwork for keep-alive parking, an opt-in event loop that parks idle
keep-alive connections instead of blocking a worker thread on each.

detail::Poller delivers readiness once per arm(), so a descriptor is
either armed (owned by the poller) or owned by whoever got the event.
wake() ends a wait() from any thread, and an armed descriptor must be
disarmed before it is closed.

- PollPoller (poll() / WSAPoll()) works everywhere.
- EpollPoller (Linux) uses EPOLLONESHOT.
- KqueuePoller (macOS, FreeBSD) uses EV_ONESHOT.
- PollerWaker carries wake() for all three: an eventfd on Linux, a socket
  pair elsewhere. detail::create_socket_pair() emulates socketpair() on
  Windows with sockets that child processes do not inherit.

make_poller() picks the best one and falls back to poll(). The contract
tests run on every backend that builds. Nothing uses the poller yet.
2026-11-21 21:23:22 -05:00

Diff Content Not Available