prefactor_core.queue.base module

prefactor_core.queue.base module

Queue infrastructure for prefactor-core.

This module provides the foundation layer for async queue-based processing. All queue implementations must satisfy the Queue interface to be used with the TaskExecutor.

class prefactor_core.queue.base.Queue

Bases: ABC, Generic[T]

Abstract base class for all queue implementations.

This interface defines the contract for queue operations used by the TaskExecutor. Implementations must be thread-safe and support async operations.

abstractmethod async close(num_waiters: int = 1) → None

Close the queue and signal workers to stop.

After closing, no new items can be added. Workers should finish processing remaining items and then exit.

• Parameters: num_waiters – Number of workers currently blocked in get() that need to be woken up so they can observe the closed state.

abstract property closed : bool

Check if the queue has been closed.

• Returns: True if close() has been called, False otherwise.

abstractmethod async get() → T

Remove and return an item from the queue.

This method blocks until an item is available or the queue is closed.

• Returns: The next item from the queue.
• Raises: QueueClosedError – If the queue is closed and empty.

abstractmethod async put(item: T) → None

Add an item to the queue.

This method should return immediately without blocking the caller. The item will be processed asynchronously by workers.

• Parameters: item – The item to add to the queue.
• Raises: QueueClosedError – If the queue has been closed.

abstractmethod size() → int

Return the current number of items in the queue.

• Returns: The queue size (non-negative integer).

exception prefactor_core.queue.base.QueueClosedError

Bases: Exception

Raised when attempting to use a closed queue.