Skip to content
Permalink
Browse files

Merge pull request #1818 from Jesus/nio4r-doc

Updates docs, removes refs. to IO.select()
  • Loading branch information...
schneems committed Jun 12, 2019
2 parents 65df7f0 + 7b0c134 commit c242e76f4d14dd7582ce27062c6b0d26ff4abaf5
Showing with 20 additions and 19 deletions.
  1. +4 −3 lib/puma/client.rb
  2. +16 −16 lib/puma/reactor.rb
@@ -27,9 +27,10 @@ class ConnectionError < RuntimeError; end
# For example a web request from a browser or from CURL. This
#
# An instance of `Puma::Client` can be used as if it were an IO object
# for example it is passed into `IO.select` inside of the `Puma::Reactor`.
# This is accomplished by the `to_io` method which gets called on any
# non-IO objects being used with the IO api such as `IO.select.
# by the reactor, that's because the latter is expected to call `#to_io`
# on any non-IO objects it polls. For example nio4r internally calls
# `IO::try_convert` (which may call `#to_io`) when a new socket is
# registered.
#
# Instances of this class are responsible for knowing if
# the header and body are fully buffered via the `try_to_finish` method.
@@ -20,10 +20,11 @@ module Puma
#
# ## 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.
# A connection comes into a `Puma::Server` instance, it is then passed to a `Puma::Reactor` instance,
# which stores it in an array and waits for any of the connections to be ready for reading.
#
# When the request is written to by the client then the `IO.select` will "wake up" and
# The waiting/wake up is performed with nio4r, which will use the apropriate backend (libev, Java NIO or
# just plain IO#select). The call to `NIO::Selector#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, and sees if they're complete. If they
# have a full header and body then the reactor passes the request to a thread pool.
@@ -69,19 +70,18 @@ def initialize(server, app_pool)

private


# Until a request is added via the `add` method this method will internally
# loop, waiting on the `sockets` array objects. The only object in this
# array at first is the `@ready` IO object, which is the read end of a pipe
# connected to `@trigger` object. When `@trigger` is written to, then the loop
# will break on `IO.select` and return an array.
# will break on `NIO::Selector#select` and return an array.
#
# ## When a request is added:
#
# When the `add` method is called, an instance of `Puma::Client` is added to the `@input` array.
# Next the `@ready` pipe is "woken" by writing a string of `"*"` to `@trigger`.
#
# When that happens, the internal loop stops blocking at `IO.select` and returns a reference
# When that happens, the internal loop stops blocking at `NIO::Selector#select` and returns a reference
# to whatever "woke" it up. On the very first loop, the only thing in `sockets` is `@ready`.
# When `@trigger` is written-to, the loop "wakes" and the `ready`
# variable returns an array of arrays that looks like `[[#<IO:fd 10>], [], []]` where the
@@ -97,7 +97,7 @@ def initialize(server, app_pool)
# to the `@ready` IO object. For example: `[#<IO:fd 10>, #<Puma::Client:0x3fdc1103bee8 @ready=false>]`.
#
# Since the `Puma::Client` in this example has data that has not been read yet,
# the `IO.select` is immediately able to "wake" and read from the `Puma::Client`. At this point the
# the `NIO::Selector#select` is immediately able to "wake" and read from the `Puma::Client`. At this point the
# `ready` output looks like this: `[[#<Puma::Client:0x3fdc1103bee8 @ready=false>], [], []]`.
#
# Each element in the first entry is iterated over. The `Puma::Client` object is not
@@ -109,12 +109,12 @@ def initialize(server, app_pool)
#
# If the request body is not present then nothing will happen, and the loop will iterate
# again. When the client sends more data to the socket the `Puma::Client` object will
# wake up the `IO.select` and it can again be checked to see if it's ready to be
# wake up the `NIO::Selector#select` and it can again be checked to see if it's ready to be
# passed to the thread pool.
#
# ## Time Out Case
#
# In addition to being woken via a write to one of the sockets the `IO.select` will
# In addition to being woken via a write to one of the sockets the `NIO::Selector#select` will
# periodically "time out" of the sleep. One of the functions of this is to check for
# any requests that have "timed out". At the end of the loop it's checked to see if
# the first element in the `@timeout` array has exceed its allowed time. If so,
@@ -124,7 +124,7 @@ def initialize(server, app_pool)
#
# This behavior loops until all the objects that have timed out have been removed.
#
# Once all the timeouts have been processed, the next duration of the `IO.select` sleep
# Once all the timeouts have been processed, the next duration of the `NIO::Selector#select` sleep
# will be set to be equal to the amount of time it will take for the next timeout to occur.
# This calculation happens in `calculate_sleep`.
def run_internal
@@ -320,7 +320,7 @@ def run_in_thread
end
end

# The `calculate_sleep` sets the value that the `IO.select` will
# The `calculate_sleep` sets the value that the `NIO::Selector#select` will
# sleep for in the main reactor loop when no sockets are being written to.
#
# The values kept in `@timeouts` are sorted so that the first timeout
@@ -351,18 +351,18 @@ def calculate_sleep
# object.
#
# The main body of the reactor loop is in `run_internal` and it
# will sleep on `IO.select`. When a new connection is added to the
# will sleep on `NIO::Selector#select`. When a new connection is added to the
# reactor it cannot be added directly to the `sockets` array, because
# the `IO.select` will not be watching for it yet.
# the `NIO::Selector#select` will not be watching for it yet.
#
# Instead what needs to happen is that `IO.select` needs to be woken up,
# Instead what needs to happen is that `NIO::Selector#select` needs to be woken up,
# the contents of `@input` added to the `sockets` array, and then
# another call to `IO.select` needs to happen. Since the `Puma::Client`
# another call to `NIO::Selector#select` needs to happen. Since the `Puma::Client`
# object can be read immediately, it does not block, but instead returns
# right away.
#
# This behavior is accomplished by writing to `@trigger` which wakes up
# the `IO.select` and then there is logic to detect the value of `*`,
# the `NIO::Selector#select` and then there is logic to detect the value of `*`,
# pull the contents from `@input` and add them to the sockets array.
#
# If the object passed in has a timeout value in `timeout_at` then

0 comments on commit c242e76

Please sign in to comment.
You can’t perform that action at this time.