Struct PooledSandbox 

pub struct PooledSandbox { /* private fields */ }

A sandbox acquired from a pool.

This wrapper ensures the sandbox is returned to the pool when dropped. It implements Deref and DerefMut to allow transparent access to the underlying Sandbox.

Implementations

impl PooledSandbox

pub fn sandbox(&self) -> &Sandbox

Get a reference to the underlying sandbox.

pub fn sandbox_mut(&mut self) -> &mut Sandbox

Get a mutable reference to the underlying sandbox.

pub fn detach(self) -> Sandbox

Detach the sandbox from the pool, preventing it from being returned.

This consumes the PooledSandbox and returns the underlying Sandbox. The sandbox will not be returned to the pool.

Note: This still releases the semaphore permit, so another sandbox can be created to take its place in the pool.

pub fn with_callbacks(self, callbacks: Vec<Box<dyn Callback>>) -> Self

Set callbacks for this request.

These will be cleared automatically when the sandbox is returned to the pool.

pub fn with_trace_handler<H: TraceHandler + 'static>(self, handler: H) -> Self

Set a trace handler for this request.

This will be cleared automatically when the sandbox is returned to the pool.

pub fn with_output_handler<H: OutputHandler + 'static>(self, handler: H) -> Self

Set an output handler for this request.

This will be cleared automatically when the sandbox is returned to the pool.

pub fn with_resource_limits(self, limits: ResourceLimits) -> Self

Set resource limits for this request.

These will be reset to defaults when the sandbox is returned to the pool.

pub fn with_vfs_storage(self, storage: Arc<dyn VfsStorage>) -> Self

Available on crate feature vfs only.

Set VFS storage for this request.

This will be cleared automatically when the sandbox is returned to the pool. The provided storage replaces the default scrubbing storage created during execution, allowing pre-populated files to be available to Python code.

Methods from Deref<Target = Sandbox>

pub async fn execute(&self, code: &str) -> Result<ExecuteResult, Error>

Execute Python code in the sandbox.

If an OutputHandler was configured, stdout is streamed to it during execution. If a TraceHandler was configured, trace events are emitted during execution.

Returns the final result including complete stdout and collected trace events.

Errors

Returns an error if the Python code fails to execute or a resource limit is exceeded.

pub async fn execute_with_journal(&self, code: &str) -> ReplayOutcome

Execute Python code with callback-result replay and journaling.

This behaves like execute but additionally records a CallbackJournal of every callback invocation, and — if a previous journal was configured via SandboxBuilder::with_replay_journal — replays matching callbacks from that journal instead of invoking them live. See the replay module for the full model.

The returned ReplayOutcome always carries the freshly-recorded journal, even when execution fails, so a later resubmission can replay everything that completed.

Each call uses fresh replay state, so a sandbox may be executed repeatedly without the journal cursor leaking between runs.

Security

Replayed journal entries are returned to Python verbatim — the callback is not re-executed. A crafted journal can therefore inject arbitrary values into the script. Only replay journals produced by a trusted source (e.g. a previous run of the same sandbox, or a journal verified via HMAC signature). See the replay module docs for details.

pub fn type_stubs(&self) -> &str

Get combined type stubs for all loaded libraries. Useful for including in LLM context windows.

pub fn callbacks(&self) -> &HashMap<String, Arc<dyn Callback>>

Get a reference to the registered callbacks.

pub fn preamble(&self) -> &str

Get the Python preamble code.

pub fn trace_handler(&self) -> &Option<Arc<dyn TraceHandler>>

Get a reference to the trace handler.

pub fn output_handler(&self) -> &Option<Arc<dyn OutputHandler>>

Get a reference to the output handler.

pub fn resource_limits(&self) -> &ResourceLimits

Get a reference to the resource limits.

pub fn executor(&self) -> Arc<PythonExecutor>

Get a reference to the Python executor.

This allows creating a SessionExecutor from a pooled sandbox, enabling state persistence between executions.

pub fn execute_cancellable(&self, code: &str) -> ExecutionHandle

Execute Python code with cancellation support.

Returns an ExecutionHandle that can be used to cancel the execution or wait for its completion.

Example

let handle = sandbox.execute_cancellable("while True: pass").await?;

// Cancel after 5 seconds from another task
let cancel_handle = handle.clone();
tokio::spawn(async move {
    tokio::time::sleep(Duration::from_secs(5)).await;
    cancel_handle.cancel();
});

// Wait for result
match handle.wait().await {
    Ok(result) => println!("Completed: {}", result.stdout),
    Err(Error::Cancelled) => println!("Cancelled"),
    Err(e) => println!("Error: {e}"),
}

Errors

Returns an error if the execution cannot be started.

Trait Implementations

impl Debug for PooledSandbox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for PooledSandbox

type Target = Sandbox

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for PooledSandbox

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for PooledSandbox

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.