Class: Kobako::Pool

Inherits:
Object
  • Object
show all
Defined in:
lib/kobako/pool.rb

Overview

Kobako::Pool — a bounded set of warm, identically set-up Sandboxes handed out one exclusive holder at a time (docs/behavior.md B-46..B-48).

Construction forwards every Kobako::Sandbox.new keyword verbatim and holds the optional block as the per-Sandbox setup hook; a checkout prefers an idle Sandbox and constructs a new one only when none is idle and fewer than slots exist (B-46). #with blocks up to checkout_timeout seconds when every slot is held (E-46), applies the TrapError discard-and-recreate contract at checkin (B-47), and the Pool releases everything with its own reachability — there is no teardown verb (B-48).

Constant Summary collapse

DEFAULT_CHECKOUT_TIMEOUT_SECONDS =

The #with wait bound applied when checkout_timeout is not given (docs/behavior.md B-46).

5.0

Instance Method Summary collapse

Constructor Details

#initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup) ⇒ Pool

Build a Pool of up to slots Sandboxes (docs/behavior.md B-46). slots is a positive Integer; checkout_timeout bounds the #with wait in seconds (nil waits indefinitely); every other keyword is forwarded verbatim to Kobako::Sandbox.new. The optional block runs exactly once per constructed Sandbox — it is the setup window for #define / #preload before that Sandbox’s first checkout. No Sandbox is constructed here. Raises ArgumentError for an invalid slots / checkout_timeout (docs/behavior.md E-47).



34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/kobako/pool.rb', line 34

def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
  validate_slots!(slots)
  @slots = slots
  @checkout_timeout = normalize_checkout_timeout(checkout_timeout)
  @sandbox_options = sandbox_options
  @setup = setup
  @idle = [] # : Array[Kobako::Sandbox]
  @constructed = 0
  @mutex = Mutex.new
  @slot_freed = ConditionVariable.new
end

Instance Method Details

#with ⇒ Object

Yield one exclusively-held Sandbox to the block and return the block’s value (docs/behavior.md B-47). Blocks while every slot is held; raises Kobako::PoolTimeoutError once the wait exceeds checkout_timeout (docs/behavior.md E-46). The Sandbox returns to the pool at block exit — unless the block raised Kobako::TrapError, in which case the unrecoverable Sandbox is discarded and its slot refills by a fresh construction on next demand.



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/kobako/pool.rb', line 55

def with
  sandbox = checkout
  begin
    yield sandbox
  rescue TrapError
    release_capacity!
    sandbox = nil
    raise
  ensure
    checkin(sandbox) if sandbox
  end
end