Rust pump and backends

def is_rust_available() -> bool

Report cached Rust availability, honouring testing overrides for dispatch.

def observe_pump(hook: PumpHook) -> PumpHookRegistration

Register a hook for Rust-pump routing events in the current context.

Count declined hand-offs into a metrics collector::

    from cuprum.adapters.metrics_adapter import InMemoryMetrics
    from cuprum.adapters.pump_metrics import PumpMetricsHook

    metrics = InMemoryMetrics()
    with observe_pump(PumpMetricsHook(metrics)):
        pipeline.run_sync()

class PumpEvent(
    phase: PumpPhase,
    reason: RustPumpDeclineReason | None = None,
    outcome: RustPumpHandoffOutcome | None = None,
    duration_s: float | None = None,
    elapsed_s: float | None = None,
    exec_id: ExecId | None = None,
)

A Rust-pump routing decision reported to registered pump hooks.

The event carries the phase, a closed-set reason or hand-off outcome, the monotonic wait duration for completed native-pump cleanup, the monotonic elapsed grace wait, and the source stage token needed to correlate cleanup tracing. Descriptor numbers, command arguments, exception types, and tracebacks are all either unbounded as metric labels or a disclosure risk, and the DEBUG log records emitted alongside these events carry the diagnostic detail — including the pump's traceback — for the cases that need it.

A decline names the seam that refused::

    event = PumpEvent(
        phase="declined",
        reason=RustPumpDeclineReason.READER_PAUSE_FAILED,
    )
    assert event.reason == "reader_pause_failed"

A cancellation-masked failure carries no reason::

    assert PumpEvent(phase="failed_after_cancel").reason is None

A completed cleanup carries its monotonic duration::

    cleanup = PumpEvent(phase="cleanup_completed", duration_s=0.25)
    assert cleanup.duration_s == 0.25

phase: PumpPhase

reason: RustPumpDeclineReason | None

outcome: RustPumpHandoffOutcome | None

duration_s: float | None

elapsed_s: float | None

exec_id: ExecId | None

PumpHook = cabc.Callable[[PumpEvent], None]

A synchronous consumer of PumpEvent values.

Pump hooks are synchronous by contract. Every emission site is synchronous — one on the Python-pump fall-back path and the others inside cancellation unwinding — so there is no task to attach an awaitable to and no point at which awaiting it could be ordered against the transfer it describes. A hook that returns an awaitable is reported and discarded rather than run.

class PumpHookRegistration(hook: PumpHook) -> None

Bases: _TokenTupleRegistration['PumpHook']

Registration handle for a Rust-pump observation hook.

Supports detach() and context-manager use. The handle captures a contextvars.Token when it installs the extended hook tuple, and detach restores the exact tuple that was current when the handle was created — the same discipline _TokenRegistration applies to execution contexts. Detach in the contextvars.Context that created the registration; resetting a ContextVar with a token from another context raises ValueError.

Prefer with blocks, which detach in last-in-first-out order; detaching out of order restores a tuple that discards later registrations.

def detach() -> None

RustPumpDeclineReason

Bases: enum.StrEnum

Why an inter-stage hop fell back from the Rust pump to the Python one.

A closed set rather than free text. Operators filter on cuprum_reason and aggregate the reason metric label, so a typo at a new call site would produce a value their filters silently miss; as an enum it is a type error instead. Members are str, so the logged field and the metric label stay plain strings. PLATFORM_UNSUPPORTED means the current operating system and asyncio transport combination cannot safely use the native Rust pump. DUPLICATE_FDS_UNAVAILABLE means a transport's pipe description could not be re-opened or duplicated for the native worker: the descriptors existed when extraction read them, but one was already closed by the time duplication re-opened it.

The member value is the string operators see::

    assert RustPumpDeclineReason.RAW_FD_UNAVAILABLE == "raw_fd_unavailable"

RAW_FD_UNAVAILABLE = 'raw_fd_unavailable'

READER_UNRESUMABLE = 'reader_unresumable'

READER_PAUSE_FAILED = 'reader_pause_failed'

BLOCKING_MODE_UNAVAILABLE = 'blocking_mode_unavailable'

DUPLICATE_FDS_UNAVAILABLE = 'duplicate_fds_unavailable'

PLATFORM_UNSUPPORTED = 'platform_unsupported'

RustPumpHandoffOutcome

Bases: enum.StrEnum

A bounded result of attempting the Rust writer-resource hand-off.

SUBMITTED = 'submitted'

DUPLICATE_WRITER_FAILED = 'duplicate_writer_failed'

BLOCKING_SETUP_FAILED = 'blocking_setup_failed'

EXECUTOR_SUBMISSION_REJECTED = 'executor_submission_rejected'

NATIVE_LOAD_FAILED = 'native_load_failed'

READER_PREPARATION_FAILED = 'reader_preparation_failed'

BUFFER_VALIDATION_FAILED = 'buffer_validation_failed'

PLATFORM_WRITER_TRANSFER_FAILED = 'platform_writer_transfer_failed'

WINDOWS_RAW_HANDLE_REJECTED = 'windows_raw_handle_rejected'

NATIVE_IO_FAILED = 'native_io_failed'

def observe_pump_span(tracer: Tracer) -> PumpHopSpanRegistration

Register a tracer for Rust-pump executor-hop spans.

class PumpHopSpanRegistration(tracer: Tracer) -> None

Bases: _TokenTupleRegistration['Tracer']

Registration handle for one Rust-pump hop tracer.

The handle restores the precise preceding registration tuple when detached. It should therefore be detached in the contextvars.Context that created it and in last-in-first-out order when registrations nest.

Unlike the other registrations built on _TokenTupleRegistration, this one refuses an out-of-order detach rather than quietly discarding whatever a later registration added: it keeps the tuple it installed so _release can compare it against the live one first.

def detach() -> None

PumpHopOutcome

Bases: enum.StrEnum

The bounded terminal outcomes of one Rust-pump executor hop.

SUCCEEDED = 'succeeded'

FAILED = 'failed'

CANCELLED = 'cancelled'

FAILED_AFTER_CANCEL = 'failed_after_cancel'