Getting started

A Pyroxide task is a Python callable that returns a TaskHandle when you submit it. The handle lets you inspect, wait for, await, cancel, or release that piece of work.

Decorate and submit

from pyroxide import task

@task
def square(value: int) -> int:
    return value * value

handle = square(12)
print(handle.status)    # Pending, Running, or Completed
print(handle.result())  # 144

The decorated callable accepts one payload argument. Calling square(12) does not run the function inline; it submits the payload and returns immediately.

result() waits for completion. By default it also consumes the task record, so the handle should not be queried again.

Wait without consuming

Use wait() when you need the terminal status before reading the result:

handle = square(12)
status = handle.wait(timeout_sec=2)
result = handle.result()

wait() returns Completed or Failed. It raises TimeoutError if the deadline expires and RuntimeError if the task was cancelled.

Use consume=False when more than one part of your code must inspect a finished handle:

handle = square(12)
result = handle.result(consume=False)
print(handle.status)
handle.close()

close() releases a terminal record. If work is still running, it marks the record for automatic release after completion. A context manager does the same cleanup:

with square(12) as handle:
    result = handle.result()

Await inside an event loop

Do not call blocking result() on an event-loop thread. Await the asynchronous form:

result = await square(12).result_async(timeout_sec=2)

The result and exception semantics match result(). A handle supports only one active asynchronous waiter. See Concurrency and asyncio for a complete example.

Understand status

Cancellation depends on the execution boundary. Pending work can be cancelled; running in-process work cannot be safely interrupted. Read Task cancellation before relying on it for control flow.

Do more

• Choose threads, processes, WASM, or native execution.
• Submit related payloads as a batch.
• Run CPU-bound Python in an isolated process.
• Prepare the engine for production.

Shut Pyroxide down during application teardown:

import pyroxide

pyroxide.shutdown(wait=True, cancel_pending=False)

Shutdown is idempotent and irreversible in the current process. The default waits for accepted work to finish.