Pyjo.Server.Prefork - Pre-forking non-blocking I/O HTTP and WebSocket server

from Pyjo.Server.Prefork import Prefork

prefork = Prefork(listen=['http://*:8080'])


@prefork.unsubscribe('request').on('request')
def request(prefork, tx):
    # Request
    method = tx.req.method
    path = tx.req.url.path

    # Response
    tx.res.code = 200
    tx.res.headers.content_type = 'text/plain'
    tx.res.body = f'{method} request for {path}!'.encode()

    # Resume transaction
    tx.resume()


prefork.run()

# Or import the module, as in Google Python Style Guide

import Pyjo.Server.Prefork

prefork = Pyjo.Server.Prefork.new(listen=['http://*:8080'])


@prefork.unsubscribe('request').on('request')
def request(prefork, tx):
    # Request
    method = tx.req.method
    path = tx.req.url.path

    # Response
    tx.res.code = 200
    tx.res.headers.content_type = 'text/plain'
    tx.res.body = f'{method} request for {path}!'.encode()

    # Resume transaction
    tx.resume()


prefork.run()

Pyjo.Server.Prefork is a full featured, UNIX optimized, pre-forking non-blocking I/O HTTP and WebSocket server, built around the very well tested and reliable Pyjo.Server.Daemon, with IPv6, TLS, SNI, UNIX domain socket, Comet (long polling), keep-alive and multiple event loop support. Note that the server uses signals for process management, so you should avoid modifying signal handlers in your applications.

The workers are forks of the manager, made with os.fork(), so the server runs where os.fork() exists, not on Windows, where Pyjo.Server.Prethread has the workers in threads. Name resolution in a thread, SOCKS5 and TLS support can be disabled with the PYJO_NO_NNR, PYJO_NO_SOCKS and PYJO_NO_TLS environment variables.

Manager signals

The Pyjo.Server.Prefork manager process can be controlled at runtime with the following signals.

INT, TERM

Shut down server gracefully. The manager and the workers close the listen sockets, so that a new connection is refused, and the workers finish the accepted ones, after shutdown_delay, while the workers serve as before, which the manager tells them with USR1. A second INT, as of Ctrl-C pressed twice, shuts it down immediately, also during the delay, a second TERM does nothing.

QUIT

Shut down server immediately.

HUP

Restart the workers gracefully, or emit the event reload when it has subscribers.

TTIN

Increase worker pool by one.

TTOU

Decrease worker pool by one.

Worker signals

Pyjo.Server.Prefork worker processes can be controlled at runtime with the following signals.

TERM

Stop worker gracefully, with its copies of the listen sockets closed.

USR1

Stop worker gracefully after shutdown_delay, while it serves as before.

QUIT

Stop worker immediately.

The workers ignore INT, which Ctrl-C sends to all the processes of the server, and HUP, as the manager stops them.

Events

Pyjo.Server.Prefork inherits all events from Pyjo.Server.Daemon and can emit the following new ones.

finish

prefork.on('finish', lambda prefork, graceful: ...)

Emitted when the server shuts down.

prefork.on('finish', lambda prefork, graceful: print('Graceful server shutdown' if graceful else 'Server shutdown'))

heartbeat

prefork.on('heartbeat', lambda prefork, pid: ...)

Emitted when a heartbeat message has been received from a worker.

prefork.on('heartbeat', lambda prefork, pid: print(f'Worker {pid} has a heartbeat'))

reap

prefork.on('reap', lambda prefork, pid: ...)

Emitted when a child process exited.

prefork.on('reap', lambda prefork, pid: print(f'Worker {pid} stopped'))

reload

prefork.on('reload', lambda prefork: ...)

Emitted when the manager gets the signal HUP, in the place of the restart of the workers.

prefork.on('reload', lambda prefork: print('Reloading the configuration'))

spawn

prefork.on('spawn', lambda prefork, pid: ...)

Emitted when a worker process is spawned.

prefork.on('spawn', lambda prefork, pid: print(f'Worker {pid} started'))

wait

prefork.on('wait', lambda prefork: ...)

Emitted when the manager starts waiting for new heartbeat messages.

prefork.on('wait', lambda prefork: print(f'Waiting for heartbeat messages from {prefork.workers} workers'))

See also

Pyjoyment, https://mojolicious.org.

Ported from Mojo::Server::Prefork of Mojolicious 9.49.

Classes

class Pyjo.Server.Prefork.Pyjo_Server_Prefork(*, accepts: int = 10000, cleanup: bool = True, graceful_timeout: float = 25, heartbeat_interval: float = 5, heartbeat_timeout: float = 50, pid_file: str | PathLike[str] | None = None, spare: int = 2, workers: int = 4, **kwargs: Any)[source]

Pyjo.Server.Prefork inherits all methods from Pyjo.Server.Daemon and implements the following new ones.

accepts
accepts = prefork.accepts
prefork.accepts = 100

Maximum number of connections a worker is allowed to accept, before stopping gracefully and then getting replaced with a newly started worker, passed along to Pyjo.IOLoop.Pyjo_IOLoop.max_accepts, defaults to 10000. Setting the value to 0 will allow workers to accept new connections indefinitely. Note that up to half of this value can be subtracted randomly to improve load balancing, and to make sure that not all workers restart at the same time.

check_pid() → int | None[source]
pid = prefork.check_pid()

Get process id for running server from pid_file or delete it if server is not running.

if not prefork.check_pid():
    print('Server is not running')
cleanup
boolean = prefork.cleanup
prefork.cleanup = False

Delete pid_file automatically once it is not needed anymore, defaults to a true value.

ensure_pid_file(pid: int) → None[source]
prefork.ensure_pid_file(pid)

Ensure pid_file exists.

graceful_timeout
timeout = prefork.graceful_timeout
prefork.graceful_timeout = 15

Maximum amount of time in seconds stopping a worker gracefully may take before being forced, defaults to 25, less than the 30 seconds that Kubernetes gives a container to stop. Note that this value should usually be a little larger than the maximum amount of time you expect any one request to take.

property healthy: int[source]
healthy = prefork.healthy

Number of currently active worker processes with a heartbeat.

heartbeat_interval
interval = prefork.heartbeat_interval
prefork.heartbeat_interval = 3

Heartbeat interval in seconds, defaults to 5.

heartbeat_timeout
timeout = prefork.heartbeat_timeout
prefork.heartbeat_timeout = 2

Maximum amount of time in seconds before a worker without a heartbeat will be stopped gracefully, defaults to 50. Note that this value should usually be a little larger than the maximum amount of time you expect any one operation to block the event loop.

pid_file: str | PathLike[str]
file = prefork.pid_file
prefork.pid_file = '/tmp/prefork.pid'

Full path of process id file, defaults to prefork.pid in a temporary directory.

run() → None[source]
prefork.run()

Run server and wait for the manager signals.

spare
spare = prefork.spare
prefork.spare = 4

Temporarily spawn up to this number of additional workers if there is a need, defaults to 2. This allows for new workers to be started while old ones are still shutting down gracefully, drastically reducing the performance cost of worker restarts.

workers
workers = prefork.workers
prefork.workers = 10

Number of worker processes, defaults to 4. A good rule of thumb is two worker processes per CPU core for applications that perform mostly non-blocking operations, blocking operations often require more and benefit from decreasing concurrency with Pyjo.Server.Daemon.Pyjo_Server_Daemon.max_clients (often as low as 1).