flowno.core.event_loop.commands

Internal Command Types for the Flowno Event Loop

This module defines the command types used by the Flowno event loop to implement its cooperative multitasking system. Commands are yielded by coroutines and interpreted by the event loop to perform operations like task scheduling, I/O operations, and synchronization.

Warning

These command types are used internally by the Flowno event loop to control task scheduling, socket operations, and asynchronous queue interactions. They are not part of the public API. Normal users should rely on the public awaitable primitives (e.g. sleep(), spawn(), etc.) rather than yielding these commands directly.

class flowno.core.event_loop.commands.CancelCommand(task_handle: TaskHandle[_T])

Internal command to cancel a task and wait for its result.

Parameters:

task_handle – A handle to the task to cancel.

Note

This is used internally to implement the awaitable TaskHandle.cancel() method. Unlike the non-awaitable cancel, this suspends until the cancelled task finishes and returns its result value.

class flowno.core.event_loop.commands.Command

Base abstract class for all internal command types.

Note

These commands are part of the Flowno event loop’s internal control mechanism. Application developers should not use or yield these commands directly.

class flowno.core.event_loop.commands.ConditionNotifyCommand(condition: Any, all: bool)

Notify waiters on a condition variable.

Parameters:

• condition – The Condition synchronization primitive to notify.

• all – If True, notify all waiters (notify_all). If False, notify one waiter (notify).

Note

This command wakes one or all tasks waiting on the condition. Notified tasks are moved to the lock’s wait queue and must reacquire the lock. The task must hold the lock before calling notify().

class flowno.core.event_loop.commands.ConditionWaitCommand(condition: Any)

Wait on a condition variable (atomically releases lock).

Parameters:

condition – The Condition synchronization primitive to wait on.

Note

This command atomically releases the associated lock and blocks the task until another task calls notify() or notify_all() on the condition. When the task wakes up, it automatically reacquires the lock before continuing. The task must hold the lock before calling wait().

class flowno.core.event_loop.commands.EventSetCommand(event: Any)

Set an event, waking all waiting tasks.

Parameters:

event – The Event synchronization primitive to set.

Note

This command sets the event and wakes all tasks blocked on event.wait(). The event remains set permanently (one-shot semantics).

class flowno.core.event_loop.commands.EventWaitCommand(event: Any)

Wait for an event to be set (one-shot signal).

Parameters:

event – The Event synchronization primitive to wait on.

Note

This command blocks the task until the event is set. If the event is already set when this command is issued, the task resumes immediately.

class flowno.core.event_loop.commands.ExitCommand(return_value: object = None, exception: Exception | None = None)

Internal command to forcibly terminate the event loop.

Parameters:

• return_value – Optional value to return from run_until_complete (when join=True).

• exception – Optional exception to raise from run_until_complete.

Note

This command causes the event loop to terminate immediately, regardless of any remaining tasks. Similar to sys.exit() but specific to the event loop.

class flowno.core.event_loop.commands.JoinCommand(task_handle: TaskHandle[_T])

Internal command to suspend a task until another task finishes.

Parameters:

task_handle – A handle to the task to join.

Note

This is used internally to implement the TaskHandle.join() awaitable.

class flowno.core.event_loop.commands.LockAcquireCommand(lock: Any)

Acquire a lock (mutual exclusion).

Parameters:

lock – The Lock synchronization primitive to acquire.

Note

This command blocks the task until the lock becomes available. If the lock is already available, the task acquires it immediately.

class flowno.core.event_loop.commands.LockReleaseCommand(lock: Any)

Release a lock, waking the next waiting task.

Parameters:

lock – The Lock synchronization primitive to release.

Note

This command releases the lock and wakes the next waiting task (FIFO order). Only the lock owner can release the lock.

class flowno.core.event_loop.commands.SleepCommand(end_time: float)

Internal command to suspend a task until a specified time.

Parameters:

end_time – The time (as a DeltaTime) until which the task should sleep.

Note

Users should use the public sleep() primitive rather than yielding a SleepCommand.

class flowno.core.event_loop.commands.SocketAcceptCommand(handle: SocketHandle)

Internal command requesting to accept a new connection on a socket.

class flowno.core.event_loop.commands.SocketCommand(handle: SocketHandle)

Base internal command for socket operations.

Parameters:

handle – The socket handle associated with this operation.

Note

These commands are used by the event loop to implement non-blocking I/O.

class flowno.core.event_loop.commands.SocketRecvCommand(handle: SocketHandle)

Internal command indicating that data is to be received from a socket.

class flowno.core.event_loop.commands.SocketSendCommand(handle: SocketHandle)

Internal command indicating that data is to be sent over a socket.

class flowno.core.event_loop.commands.SpawnCommand(raw_task: Coroutine[Command, Any, _T_co])

Internal command to spawn a new raw task.

Parameters:

raw_task – The raw task coroutine to be scheduled.

Note

Users should use the public spawn() primitive instead of yielding a SpawnCommand directly.

class flowno.core.event_loop.commands.StreamCancelCommand(stream: Stream[Any], producer_node: FinalizedNode[Unpack[tuple[object, ...]], tuple[object, ...]], consumer_input: FinalizedInputPortRef[Any])

Internal command to cancel a stream, causing the producer to receive StreamCancelled.

Parameters:

• stream – The stream being cancelled

• producer_node – The node producing data to the stream

• consumer_input – The input port reference of the consuming node

Note

This command is yielded by consumers to cancel streams and notify producers.