pool is for any resource that is made once and lent to one caller at a time: a database connection, an HTTP connection, a worker. It has no native library. This is the generic pool that agentica-db uses for DbPool, with the same import path.

Add it in a project with an agentica.toml, with its prefixed tag and its folder as --subdir:

agentica add pool https://github.com/agentica-lang/packages --tag pool-0.1.3 --subdir pool

That writes this line of agentica.toml, and the entry of agentica.lock:

[dependencies]
pool = { git = "https://github.com/agentica-lang/packages", tag = "pool-0.1.3", subdir = "pool" }

A Pool.Spec[A, W] holds the config A and the functions that make, check and end the resources W. None of them runs in the owner task of the pool, so a slow or crashing one never stalls the pool or ends it:

  • init(config) makes a resource. It runs in a task of its own for each resource (its keeper), which owns the handles it opens, so they stay open while the resource lives. An init that never returns holds its place: the pool counts that resource as being made.
  • checkout(resource) (optional) runs before the body: in the caller with lease_ms 0, else in the task of the body (no task of its own), which the caller waits for at most 5 seconds (a checkout that waits, with a sleep, a channel, I/O or a compute def, is bounded; one that blocks in a plain native def call is not, since it holds its scheduler, and then the caller is held with it). An error (or a crash, or a hang) ends the resource, and the caller gets the next one without losing its place in line.
  • checkin(resource, outcome) gets the resource back after each body that ran, at most once (with TimedOut also for a body whose task was cancelled before its first step: do not count uses in checkin), with the outcome Done, Crashed or TimedOut. With lease_ms 0 it runs in the caller, with no limit. Above 0 it runs in the keeper, in a task of its own for at most 5 seconds, after the caller has its result: one that crashes or hangs ends the resource and never reaches the caller. An error ends the resource, and the pool makes another. After TimedOut the pool ends the resource whatever checkin returns, since the cancelled body may still run for a moment; after Crashed the body is dead and checkin decides.
  • ping(resource) checks an idle resource at each health tick, in its keeper; an error ends it.
  • terminate(resource) ends it, in its keeper (the task that owns the resource's handles, so it cannot move to a task with a limit). A terminate that never returns holds its place: the pool counts that resource as being ended and does not replace it, so each one makes the pool one resource smaller until the pool is closed, where the keeper is cancelled six seconds after the drain.

Pool.with(pool) do |resource| ... end runs the body with a resource and gives its result. Callers wait in line, first come, first served. With lease_ms above 0 (the default) the body runs in a task of its own, so a crash in it is an error for the caller and the resource still comes back. With lease_ms 0 it runs in the caller, which is about three times faster: a crash in it is a crash of the caller.

import Pool from "pkg/pool/pool"

struct Worker
  id: Int
end

def make(ids: ATS[String, Int]) -> Result[Worker]
  return ok(Worker(id: ids.add("next", 1)))
end

def check_in(worker: Worker, outcome: Pool.Outcome) -> Result[Void]
  case outcome
    Pool.Outcome.Done -> return ok()
    Pool.Outcome.Crashed -> return error("crashed")
    Pool.Outcome.TimedOut -> return error("timed out")
  end
end

def end_worker(worker: Worker) -> Void
  puts("ended worker #{worker.id}")
end

def ping(worker: Worker) -> Result[Void]
  return ok()
end

def main() -> Void
  ids: ATS[String, Int] = ATS.new()
  spec = Pool.Spec(config: ids, init: &make, checkin: &check_in, terminate: &end_worker, ping: &ping, size: 1)
  pool = Pool.start(spec).unwrap!
  puts(Pool.with(pool) do |worker| ok("worker #{worker.id}") end)
  Pool.close(pool, 1000)
end
Output
ok("worker 1")
ended worker 1

API #

Pool.start(spec: Spec[A, W]) -> Result[Pool[A, W]]
Pool.with(pool: Pool[A, W], body: Fn[W, Result[R]]) -> Result[R]
Pool.close(pool: Pool[A, W], drain_ms: Int) -> Void
Pool.timeout?(message: String) -> Bool

A Pool has the fields spec, owner (the owner task) and counts, which the pool keeps for reading: waiting (the callers in line, with those that gave up until the pool drops them), live (the resources made, being made or being ended) and closed once close has run. waiting and live are 0 once the close is over.

The Spec #

The other fields of the Spec, all in milliseconds unless noted, with their defaults:

  • checkout (none): the check before each body, above.
  • size (10): how many resources. With lazy: true (false) they are made when a caller needs one.
  • max_overflow (0): in a spike the pool makes up to this many resources more, so size + max_overflow is the most that exist (at most 1048576 in all).
  • overflow_idle_ms (1000): an overflow resource that no caller needs stays this long and is ended if it is still idle then, so the pool shrinks back to size, and a steady load a little over size does not make and end a resource for every request. 0 ends it as soon as it is given back.
  • checkout_ms (5000): how long a caller waits for a resource.
  • lease_ms (30000): how long a body may run. The body runs in a task of its own, and one past this time is cancelled and its caller gets an error. 0 runs the body in the caller, with no limit.
  • max_age_ms (0) and idle_ms (0): a resource older than max_age_ms is ended and replaced; one unused for idle_ms is ended (idle_ms needs lazy: true, since an eager pool would make a new one at once). 0 turns the rule off. Both need health_ms, which applies them.
  • max_waiting (1000): how many callers may wait for a busy resource at once, 0 or more. The callers that a resource being made, pinged or checked in will serve, or one the pool can still make, do not count. 0 lets nobody wait: a caller that finds every resource busy is refused, but a pool that can make a resource for it (lazy, or with overflow) makes it.
  • health_ms (5000): the interval of the health tick, which pings the resources idle for health_ms or more and applies max_age_ms and idle_ms. A resource in use is never pinged. 0 turns the tick off.

Errors #

Each error of the pool has a kind, so a caller tests e.is_a?("pool") or a kind below, never the text:

KindMessage
pool.timeout.checkoutpool error: checkout timed out after N ms, with the last error of init (also as cause) when the pool could not make a resource
pool.timeout.leasepool error: lease timed out after N ms
pool.fullpool error: queue full (max_waiting N)
pool.closedpool error: closed, or pool error: owner task ended
argumenta field of the Spec out of range, at Pool.start

e.is_a?("pool.timeout") is true for both timeouts, as Pool.timeout?(message) is for their text. An init that fails at the start of an eager pool stops the start with its own error. A body that crashes in its own task gives the crash (task.crashed). A caller that got a pool error never has its body run later, and a caller waits for a resource no longer than checkout_ms. A failed init is tried again after a second, not for every caller, and the callers that time out meanwhile see its error.

Callers that end #

The owner task watches the task of each caller. A caller that crashes or is cancelled while it holds a resource does not keep it: its keeper runs checkin with Crashed (a crash of a body that runs in the caller) or TimedOut (a cancel), and the resource comes back or is ended and replaced. checkin runs at most once for each body that ran, and TimedOut also for a body in a task of the pool that was cancelled before its first step (the pool prefers one checkin too many to a resource that keeps what the body took): a caller that ends before its body started has its resource ended without it, and so does one that ends (lease_ms 0) after it told the pool that it is checking in, whether its checkin had started or not. Cancelling a caller cancels its body too, also when the body runs in a task of its own. A caller cancelled while it waits leaves the line.

A task that has used the pool counts its crash as observed, since the pool hears of it: a run whose only unobserved crash is in such a task does not exit 1 for it (the crash still prints). The fix belongs in the language (agentica-lang/agentica#1522).

Closing #

Pool.close(pool, drain_ms) refuses new callers, lets the running bodies and the callers in line finish for up to drain_ms, fails the rest with pool error: closed, ends every resource and stops the pool.

  • Start the pool in a task that lives as long as it does, such as main: the owner task ends with the task that started it.
  • A body that runs in a task of its own and outlasts the drain is cancelled, its keeper runs checkin with TimedOut, and its caller gets pool error: closed. One that runs in its caller (lease_ms 0) is not cancelled: it finds its resource ended, and its result is its own.
  • ping, checkout and checkin have 5 seconds each in a task of their own. The keepers have six seconds after the drain to end their resources, so one in such a call still runs terminate; a keeper that is still running then is cancelled, and the VM closes the handles it owns.
  • A caller in line hears within a fifth of a second that the owner task has ended (pool error: owner task ended).