Package com.tnsai.quality.sandbox

Class SandboxPool

java.lang.Object

com.tnsai.quality.sandbox.SandboxPool

All Implemented Interfaces:

AutoCloseable

public final class SandboxPool
extends Object
implements AutoCloseable

Reuses Sandbox instances across multiple borrowers to skip the cold-start cost (TNS-296).

Borrowers acquire a leased sandbox via borrow(), run one or more Sandbox.execute(com.tnsai.quality.sandbox.Command) calls, and return it via SandboxPool.Lease.close() (typically through try-with-resources). The pool's sizing is bounded by maxSize — if every sandbox is in flight a new borrower waits up to acquireTimeout or, on timeout, creates a fresh non-pooled sandbox so the caller is never blocked indefinitely.

Sandbox identity

The pool keys reuse on the SandboxSpec value. Borrowing with a different spec spins a fresh sandbox — pool entries are not coerced to mismatched specs. Most consumers use one spec per pool (one pool per agent role) and let the dimensions stay stable.

Concurrency

The pool is thread-safe. Individual Sandbox instances are not — but the pool guarantees a leased sandbox is held by exactly one borrower at a time, so the single-thread contract is preserved.

Since:

0.10.0 (TNS-296)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	SandboxPool.Lease	Lease wrapping a borrowed sandbox.

Constructor Summary

Constructors

Constructor	Description
SandboxPool(SandboxFactory factory, SandboxSpec spec, int maxSize, Duration acquireTimeout)

Method Summary

Modifier and Type	Method	Description
SandboxPool.Lease	borrow()	Borrow a sandbox.
void	close()	Drain the pool — terminate every idle sandbox.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SandboxPool

public SandboxPool(SandboxFactory factory,
 SandboxSpec spec,
 int maxSize,
 Duration acquireTimeout)

Method Details

borrow

public SandboxPool.Lease borrow()

Borrow a sandbox. Returns a SandboxPool.Lease the caller closes to return the sandbox to the pool. If the pool is full and acquireTimeout elapses without a return, a fresh non-pooled sandbox is created so the caller is never blocked indefinitely (graceful degradation under burst load).

Throws:

SandboxException - if the pool has been closed

close

public void close()

Drain the pool — terminate every idle sandbox. In-flight leases are not interrupted; they terminate on close() because the pool flag triggers the non-pooled branch in release(com.tnsai.quality.sandbox.Sandbox, boolean).

Specified by:

close in interface AutoCloseable