Getting Started

This guide explains how to use the async-pool gem to manage connection pooling.

Installation

Add this gem to your project:

$ bundle add async-pool

Core Concepts

class Async::Pool::Controller provides support for both singleplex (one stream at a time) and multiplex resources (multiple streams at a time).
class Async::Pool::Resource is provided as an interface and to document how to use the pools. However, you wouldn't need to use this in practice and just implement the appropriate interface on your own objects.

Simplex Usage

A simplex pool is one where each resource can only be used one at a time. This is the most common type of pool, where each resource represents a single connection, e.g. HTTP/1.

pool = Async::Pool::Controller.new(Async::Pool::Resource)

pool.acquire do |resource|
	# resource is implicitly released when exiting the block.
end

resource = pool.acquire

# Return the resource back to the pool:
pool.release(resource)

Multiplex Usage

A multiplex pool is one where each resource can be used multiple times concurrently. This is useful for resources that can handle multiple connections at once, e.g. HTTP/2.

pool = Async::Pool::Controller.wrap do
	# This resource can be used concurrently by up to 4 tasks:
	Async::Pool::Resource.new(2)
end

resources = 4.times.map do
	# Acquire a resource from the pool:
	pool.acquire
end

resources.each do |resource|
	# Return the resource back to the pool:
	pool.release(resource)
end

Limit and Concurrency

There are two key parameters to consider when using a pool:

limit is the maximum number of resources that can be acquired at once.
concurrency is the maximum number of resources that can be created concurrently.

If the pool does not have any resources available, and the number of resources is less than the limit, a new resource will be created, otherwise the task will wait until a resource is available.

Creating resources can take time, and if multiple tasks are waiting for resources, it may be beneficial to create resources concurrently. Simplex resources are probably better created concurrently, while multiplex resources may be better created serially, as after a resource is created, it can be used by multiple tasks.