From 0e63c6892dda25d9bea76f393f53ad406bfa7ff2 Mon Sep 17 00:00:00 2001 From: Dino Maric Date: Thu, 29 Apr 2021 15:00:09 +0200 Subject: [PATCH] Link to classes in the architecture docs. (#2614) Just started reading the architecture docs, for me as a first time reader it would be useful to have direct link to stated class in the markdown. This commit passes through `architecture.md` only, if this is something that makes sense to you I can pass through all the `docs/` --- docs/architecture.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index ac63d7e7da..22dd8ad728 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,11 +6,12 @@ Puma is a threaded Ruby HTTP application server, processing requests across a TCP or UNIX socket. -Puma processes (there can be one or many) accept connections from the socket via a thread (in the `Reactor` class). The connection, once fully buffered and read, moves in to the `todo` list, where it will be picked up by a free/waiting thread in the threadpool (the `ThreadPool` class). + +Puma processes (there can be one or many) accept connections from the socket via a thread (in the [`Reactor`](../lib/puma/reactor.rb) class). The connection, once fully buffered and read, moves in to the `todo` list, where it will be picked up by a free/waiting thread in the threadpool (the [`ThreadPool`](../lib/puma/thread_pool.rb) class). Puma works in two main modes: cluster and single. In single mode, only one Puma process is booted. In cluster mode, a `master` process is booted, which prepares (and may boot) the application, and then uses the `fork()` system call to create 1 or more `child` processes. These `child` processes all listen to the same socket. The `master` process does not listen to the socket or process requests - its purpose is mostly to manage and listen for UNIX signals and possibly kill or boot `child` processes. -We sometimes call `child` processes (or Puma processes in `single` mode) _workers_, and we sometimes call the threads created by Puma's `ThreadPool` _worker threads_. +We sometimes call `child` processes (or Puma processes in `single` mode) _workers_, and we sometimes call the threads created by Puma's [`ThreadPool`](../lib/puma/thread_pool.rb) _worker threads_. ## How Requests Work @@ -18,8 +19,8 @@ We sometimes call `child` processes (or Puma processes in `single` mode) _worker * Upon startup, Puma listens on a TCP or UNIX socket. * The backlog of this socket is configured (with a default of 1024). This determines the size of the queue for unaccepted connections. Generally, this setting is unimportant and will never be hit in production use. If the backlog is full, the connection will be refused by the operating system. - * This socket backlog is distinct from the `backlog` of work as reported by `Puma.stats` or the control server. The backlog as reported by Puma is the number of connections in the process' `todo` set waiting for a thread from the `ThreadPool`. -* By default, a single, separate thread (created by the `Reactor` class) is used to read and buffer requests from the socket. + * This socket backlog is distinct from the `backlog` of work as reported by `Puma.stats` or the control server. The backlog as reported by Puma is the number of connections in the process' `todo` set waiting for a thread from the [`ThreadPool`](../lib/puma/thread_pool.rb). +* By default, a single, separate thread (created by the [`Reactor`](../lib/puma/reactor.rb) class) is used to read and buffer requests from the socket. * When at least one worker thread is available for work, the reactor thread listens to the socket and accepts a request, if one is waiting. * The reactor thread waits for the entire HTTP request to be received. * The time spent waiting for the HTTP request body to be received is exposed to the Rack app as `env['puma.request_body_wait']` (milliseconds).