Connection Pools

HTTP requests from a session are thread-safe.

Each Session maintains its own thread-safe connection pool. Pools can be configured via the :pool_options option, using the following variables:

• :max_connections_per_origin: maximum number of connections a pool allows (default: Float::INFINITY)
• :pool_timeout: the number of seconds a session will wait for a connection to be checked out (default: 5)

Each time a request is to be performed, a matching connection to the given origin and set of options will be checked out from the pool; if there is none, and the threshold of connections to that origin ((defined by the :max_connections_per_origin pool option)) isn’t reached, a new one will be initiated; if the threshold has been reached, the thread will wait for some seconds (defined by the :pool_timeout pool option), after which, if there’s none available, a HTTPX::PoolTimeoutError exception is raised. After requests are performed and the session no longer needs it, the connection is checked back into the pool.

# same (default) pool
4.times.map do |i|
  # requests performed on the same (default) connection, initialized with the default options.
  Thread.start do
    HTTPX.get("https://example.com/#{i}")
  end
end.map(&:join).map(&:value)

# 4 separate sessions, 4 different pools
4.times.map do |i|
  # each pool will manage its own connection to "https://example.com" origin
  Thread.start do
    http = HTTPX.accept("application/json")
    http.get("https://example.com/#{i}")
  end
end.map(&:join).map(&:value)

# session with maximum 3 number of connections per origin and a pool timeout of 10 seconds
http = HTTPX.with(pool_options: { max_connections_per_origin: 3, pool_timeout: 10 })

4.times.map do |i|
  # 3 connections max allowed by the pool, last request will wait for the first of the others to finish.
  Thread.start { http.get("https://example.com/#{i}") }
end.map(&:join).map(&:value)

Next: Debugging