# API Reference

## Channels

A two-way message link between a Python process and a helper process that it spawns.

[Channel](Channel.md#pymizu.Channel)  
A shared-memory SPSC channel handle (process-private).

## Channel Methods

Methods for the Channel class

[Channel.create()](Channel.create.md#pymizu.Channel.create)  
Create a channel and spawn its peer.

[Channel.attach()](Channel.attach.md#pymizu.Channel.attach)  
Attach to the channel named by a join token (the peer side).

[Channel.token](Channel.token.md#pymizu.Channel.token)  
The join token for the peer's attach.

[Channel.send()](Channel.send.md#pymizu.Channel.send)  
Send one payload.

[Channel.send_batch()](Channel.send_batch.md#pymizu.Channel.send_batch)  
Send several payloads in one crossing; return the number

[Channel.recv()](Channel.recv.md#pymizu.Channel.recv)  
Receive one payload.

[Channel.recv_async()](Channel.recv_async.md#pymizu.Channel.recv_async)  
The event-driven receive: an `asyncio.Future` for the next

[Channel.\_\_aiter\_\_()](Channel.__aiter__.md#pymizu.Channel.__aiter__)  
Iterate over received payloads until CLOSED or PEER_GONE --

[Channel.recv_batch()](Channel.recv_batch.md#pymizu.Channel.recv_batch)  
Receive up to `n` payloads in one crossing; a list

[Channel.close()](Channel.close.md#pymizu.Channel.close)  
Orderly close: signal the peer and wait up to `timeout`

[Channel.close_signal()](Channel.close_signal.md#pymizu.Channel.close_signal)  
Signal close without waiting (the peer's recv side sees

[Channel.destroy()](Channel.destroy.md#pymizu.Channel.destroy)  
Tear down the handle immediately, without the close

[Channel.alive()](Channel.alive.md#pymizu.Channel.alive)  
True while the peer process is alive.

[Channel.info()](Channel.info.md#pymizu.Channel.info)  
A read-only wire-state snapshot of the channel (dict).

[Channel.\_\_enter\_\_()](Channel.__enter__.md#pymizu.Channel.__enter__)  

[Channel.\_\_exit\_\_()](Channel.__exit__.md#pymizu.Channel.__exit__)  

[Channel.\_\_iter\_\_()](Channel.__iter__.md#pymizu.Channel.__iter__)  
Iterate over received payloads until CLOSED or PEER_GONE.

## Task pools

A set of worker processes that divide submitted tasks among themselves.

[Pool](Pool.md#pymizu.Pool)  
A shared-memory work-stealing task pool handle (process-private).

[Task](Task.md#pymizu.Task)  
A task handle from \_Pool.submit(). Collected exactly once; an uncollected handle's finalizer releases its slot.

[PreparedMap](PreparedMap.md#pymizu.PreparedMap)  
A map staged once into a persistent region, run many times.

[PoolExecutor](PoolExecutor.md#pymizu.PoolExecutor)  
A `concurrent.futures.Executor` over a pymizu pool.

## Pool Methods

Methods for the Pool class

[Pool.create()](Pool.create.md#pymizu.Pool.create)  
Create a pool and spawn its worker processes.

[Pool.attach()](Pool.attach.md#pymizu.Pool.attach)  
Attach to a live pool as a submitter, by its join token.

[Pool.token](Pool.token.md#pymizu.Pool.token)  
The join token for worker/submitter attach.

[Pool.submit()](Pool.submit.md#pymizu.Pool.submit)  
Submit `fn(*args, **kwargs)` as a task; return a Task handle.

[Pool.submit_batch()](Pool.submit_batch.md#pymizu.Pool.submit_batch)  
Submit one task per zero-arg callable in `fns` in one

[Pool.collect_any()](Pool.collect_any.md#pymizu.Pool.collect_any)  
Wait on several tasks.

[Pool.collect_all()](Pool.collect_all.md#pymizu.Pool.collect_all)  
Wait until every task is terminal.

[Pool.collect_any_async()](Pool.collect_any_async.md#pymizu.Pool.collect_any_async)  
The event-driven [`collect_any()`](../reference/Pool.collect_any.md#pymizu.Pool.collect_any):

[Pool.collect_all_async()](Pool.collect_all_async.md#pymizu.Pool.collect_all_async)  
The event-driven [`collect_all()`](../reference/Pool.collect_all.md#pymizu.Pool.collect_all):

[Pool.map()](Pool.map.md#pymizu.Pool.map)  
Map `fn` over the elements of `x` on the pool; return the

[Pool.starmap()](Pool.starmap.md#pymizu.Pool.starmap)  
Map `fn` over `x`, unpacking each element as the call's

[Pool.map_prepare()](Pool.map_prepare.md#pymizu.Pool.map_prepare)  
Stage a map once for repeated runs; return a

[Pool.retire()](Pool.retire.md#pymizu.Pool.retire)  
Ask the worker in `slot` to exit cleanly (non-blocking,

[Pool.spawn_workers()](Pool.spawn_workers.md#pymizu.Pool.spawn_workers)  
Spawn `n` additional workers into free registry slots and

[Pool.stop()](Pool.stop.md#pymizu.Pool.stop)  
Orderly shutdown (controller only).

[Pool.shutdown()](Pool.shutdown.md#pymizu.Pool.shutdown)  
Alias for [`stop()`](../reference/Pool.stop.md#pymizu.Pool.stop) -- the

[Pool.destroy()](Pool.destroy.md#pymizu.Pool.destroy)  
Tear down the pool handle immediately, without the shutdown

[Pool.status()](Pool.status.md#pymizu.Pool.status)  
A read-only wire-state snapshot of the pool (dict).

[Pool.dump()](Pool.dump.md#pymizu.Pool.dump)  
A read-only debugging snapshot of the whole pool region (dict).

[Pool.stats()](Pool.stats.md#pymizu.Pool.stats)  
Cumulative per-worker and per-submitter counters since each

[Pool.trace()](Pool.trace.md#pymizu.Pool.trace)  
Register a hook called as `fn(event, id)` at each task

[Pool.\_\_enter\_\_()](Pool.__enter__.md#pymizu.Pool.__enter__)  

[Pool.\_\_exit\_\_()](Pool.__exit__.md#pymizu.Pool.__exit__)  

## Task Methods

Methods for the Task class

[Task.state](Task.state.md#pymizu.Task.state)  

[Task.pool](Task.pool.md#pymizu.Task.pool)  

[Task.collect()](Task.collect.md#pymizu.Task.collect)  
collect(timeout=None) -\> value \| sentinel

[Task.result()](Task.result.md#pymizu.Task.result)  
result(timeout=None) -\> value \| sentinel

[Task.cancel()](Task.cancel.md#pymizu.Task.cancel)  
cancel() -\> bool

[Task.collect_async()](Task.collect_async.md#pymizu.Task.collect_async)  
collect_async() -\> asyncio.Future

[Task.\_\_await\_\_()](Task.__await__.md#pymizu.Task.__await__)  
Return an iterator to be used in await expression.

## Cross-language interop

R peers and workers (the mizu R package), neutral task specifications, and the data.frame's Python home.

[call](call.md#pymizu.call)  
A task specification for a pool of another language's workers.

[r_launcher()](r_launcher.md#pymizu.r_launcher)  
Return a [`Channel.create()`](../reference/Channel.create.md#pymizu.Channel.create) launcher

[r_pool_launcher()](r_pool_launcher.md#pymizu.r_pool_launcher)  
Return a [`Pool.create()`](../reference/Pool.create.md#pymizu.Pool.create) launcher

[Frame](Frame.md#pymizu.Frame)  
A data.frame's Python home: named columns with a row count.

[DimArray](DimArray.md#pymizu.DimArray)  
An `ndarray` carrying R labels ([names](../reference/Frame.names.md#pymizu.Frame.names) / `dimnames` /

## Frame Methods

Methods for the Frame class

[Frame.names](Frame.names.md#pymizu.Frame.names)  

[Frame.row_names](Frame.row_names.md#pymizu.Frame.row_names)  

[Frame.to_dict()](Frame.to_dict.md#pymizu.Frame.to_dict)  
to_dict() -\> dict

[Frame.from_arrow()](Frame.from_arrow.md#pymizu.Frame.from_arrow)  
from_arrow(obj) -\> Frame

[Frame.\_\_arrow_c_stream\_\_()](Frame.__arrow_c_stream__.md#pymizu.Frame.__arrow_c_stream__)  
**arrow_c_stream**(requested_schema=None) -\> capsule

[Frame.\_\_len\_\_()](Frame.__len__.md#pymizu.Frame.__len__)  
Return len(self).

[Frame.\_\_reduce\_\_()](Frame.__reduce__.md#pymizu.Frame.__reduce__)  

## Outcomes and errors

Terminal transport states return as the sentinel singletons FULL / TIMEOUT / CLOSED / PEER_GONE (identity-tested, never raised); real failures raise from the exception hierarchy.

[Sentinel](Sentinel.md#pymizu.Sentinel)  
Terminal-state sentinel returned by pymizu verbs. Identity-tested against pymizu.FULL / TIMEOUT / CLOSED / PEER_GONE.

[is_sentinel()](is_sentinel.md#pymizu.is_sentinel)  
is_sentinel(x) -\> bool

[is_remote_error()](is_remote_error.md#pymizu.is_remote_error)  
Test whether a received channel value is a remote error.

[MizuError](MizuError.md#pymizu.MizuError)  
Base class for all pymizu errors.

[ShmError](ShmError.md#pymizu.ShmError)  
A shared-memory region operation failed. Also an OSError: the failure is at the OS layer.

[StartupError](StartupError.md#pymizu.StartupError)  
A channel peer or pool worker failed to attach within the startup timeout.

[SubmitTimeoutError](SubmitTimeoutError.md#pymizu.SubmitTimeoutError)  
Pool.submit() timed out waiting for injection-ring space. Also a TimeoutError.

[SlotsExhaustedError](SlotsExhaustedError.md#pymizu.SlotsExhaustedError)  
Pool.submit() found no free result slot: too many outstanding (uncollected) tasks.

[StoppedError](StoppedError.md#pymizu.StoppedError)  
The pool is stopped; no further submission is possible.

[CancelledError](CancelledError.md#pymizu.CancelledError)  
The task was cancelled before it ran.

[TaskError](TaskError.md#pymizu.TaskError)  
The task callable raised. Carries 'remote_type' and 'remote_traceback' attributes describing the worker-side exception.

[WorkerDiedError](WorkerDiedError.md#pymizu.WorkerDiedError)  
The executing worker died mid-task. Carries 'slot' and 'pid' attributes identifying the worker.

[DeclinedError](DeclinedError.md#pymizu.DeclinedError)  
A send on a foreign-language channel of a value outside the portable interchange subset. Carries 'path' and 'reason' attributes.

## Housekeeping

The process-wide default pool, the evaluating worker's own pool handle, and orphan reaping.

[default_pool()](default_pool.md#pymizu.default_pool)  
The process-wide default pool, or None when none is set.

[set_default_pool()](set_default_pool.md#pymizu.set_default_pool)  
Set the process-wide default pool; None clears it.

[using_pool()](using_pool.md#pymizu.using_pool)  
Use [pool](../reference/Task.pool.md#pymizu.Task.pool) as the default for the with block, then restore.

[current_pool()](current_pool.md#pymizu.current_pool)  
The evaluating worker's own pool handle, inside a task.

[current_rng()](current_rng.md#pymizu.current_rng)  
The running element's own numpy Generator, inside a seeded map.

[prune()](prune.md#pymizu.prune)  
Remove orphaned shared memory regions.