From 0737bb612c3e72f40b2c418b5bcff3209f4bdbd3 Mon Sep 17 00:00:00 2001 From: schneems Date: Tue, 1 May 2018 11:19:50 -0500 Subject: [PATCH] Update class docs for Reactor --- lib/puma/reactor.rb | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/lib/puma/reactor.rb b/lib/puma/reactor.rb index 3a282b03..659b346a 100644 --- a/lib/puma/reactor.rb +++ b/lib/puma/reactor.rb @@ -6,21 +6,24 @@ module Puma # # The Reactor object is responsible for ensuring that a request has been # completely received before it starts to be processed. This may be known as read buffering. - # If this is not done and no other read buffering is performed (such as by an application) server - # such as nginx then the application would be subject to a slow client attack. + # If read buffering is not done, and no other read buffering is performed (such as by an application server + # such as nginx) then the application would be subject to a slow client attack. # - # For a graphical representation see [architecture.md](https://github.com/puma/puma/blob/master/docs/architecture.md#connection-pipeline). + # For a graphical representation of how the reactor works see [architecture.md](https://github.com/puma/puma/blob/master/docs/architecture.md#connection-pipeline). # - # A request comes into a `Puma::Server`, it is then passed to the reactor. + # ## Reactor Flow + # + # A request comes into a `Puma::Server` instance, it is then passed to a `Puma::Reactor` instance. # The reactor stores the request in an array and calls `IO.select` on the array in a loop. + # # When the request is written to by the client then the `IO.select` will "wake up" and # return the references to any objects that caused it to "wake". The reactor - # then loops through each of these request objects, sees if they're complete. If they - # are complete (have a full header and body) then it passes the request to a thread pool - # where a "worker thread" can run the the application's Ruby code against the request. + # then loops through each of these request objects, and sees if they're complete. If they + # have a full header and body then the reactor passes the request to a thread pool. + # Once in a thread pool, a "worker thread" can run the the application's Ruby code against the request. # - # If the request is not complete then it stays in the array and the next time any - # data is written to it the loop is woken up and it is checked for completeness again. + # If the request is not complete, then it stays in the array, and the next time any + # data is written to that socket reference, then the loop is woken up and it is checked for completeness again. # # A detailed example is given in the docs for `run_internal` which is where the bulk # of this logic lives.