wpiutil.sync functions

wpiutil.sync.create_signal_object(handle: SupportsInt | SupportsIndex, manual_reset: bool = False, initial_state: bool = False) → None

Sets up signaling for an arbitrary handle. With this function, any handle can operate like an event handle.

Parameters:

  • handle – Event handle

  • manual_reset – true for manual reset, false for automatic reset

  • initial_state – true to make the handle initially in signaled state

wpiutil.sync.destroy_event(handle: SupportsInt | SupportsIndex) → None

Destroys an event. Destruction wakes up any waiters.

Parameters:

handle – event handle

wpiutil.sync.destroy_semaphore(handle: SupportsInt | SupportsIndex) → None

Destroys a semaphore. Destruction wakes up any waiters.

Parameters:

handle – semaphore handle

wpiutil.sync.destroy_signal_object(handle: SupportsInt | SupportsIndex) → None

Cleans up signaling for a handle. Destruction wakes up any waiters.

Parameters:

handle – handle

wpiutil.sync.make_event(manual_reset: bool = False, initial_state: bool = False) → int

Creates an event. Events have binary state (signaled or not signaled) and may be either automatically reset or manually reset. Automatic-reset events go to non-signaled state when a WaitForObject is woken up by the event; manual-reset events require ResetEvent() to be called to set the event to non-signaled state; if ResetEvent() is not called, any waiter on that event will immediately wake when called.

Parameters:

  • manual_reset – true for manual reset, false for automatic reset

  • initial_state – true to make the event initially in signaled state

Returns:

Event handle

wpiutil.sync.make_semaphore(initial_count: SupportsInt | SupportsIndex = 0, maximum_count: SupportsInt | SupportsIndex = 2147483647) → int

Creates a semaphore. Semaphores keep an internal counter. Releasing the semaphore increases the count. A semaphore with a non-zero count is considered signaled. When a waiter wakes up it atomically decrements the count by 1. This is generally useful in a single-supplier, multiple-consumer scenario.

Parameters:

  • initial_count – initial value for the semaphore’s internal counter

  • maximum_count – maximum value for the semaphore’s internal counter

Returns:

Semaphore handle

wpiutil.sync.release_semaphore(handle: SupportsInt | SupportsIndex, release_count: SupportsInt | SupportsIndex = 1) → tuple[bool, int]

Releases N counts of a semaphore.

Parameters:

  • handle – semaphore handle

  • release_count – amount to add to semaphore’s internal counter; must be positive

  • prev_count – if non-null, previous count (output parameter)

Returns:

True on successful release, false on failure (e.g. release count would exceed maximum value, or handle invalid)

wpiutil.sync.reset_event(handle: SupportsInt | SupportsIndex) → None

Sets an event to non-signaled state.

Parameters:

handle – event handle

wpiutil.sync.reset_signal_object(handle: SupportsInt | SupportsIndex) → None

Sets a handle to non-signaled state.

Parameters:

handle – handle

wpiutil.sync.set_event(handle: SupportsInt | SupportsIndex) → None

Sets an event to signaled state.

Parameters:

handle – event handle

wpiutil.sync.set_signal_object(handle: SupportsInt | SupportsIndex) → None

Sets a handle to signaled state.

Parameters:

handle – handle

wpiutil.sync.wait_for_object(*args, **kwargs)

Overloaded function.

  1. wait_for_object(handle: typing.SupportsInt | typing.SupportsIndex) -> bool

Waits for an handle to be signaled.

Parameters:

handle – handle to wait on

Returns:

True if handle was signaled, false otherwise (e.g. object was destroyed)

  1. wait_for_object(handle: typing.SupportsInt | typing.SupportsIndex, timeout: typing.SupportsFloat | typing.SupportsIndex) -> tuple[bool, bool]

Waits for an handle to be signaled, with timeout.

Parameters:

  • handle – handle to wait on

  • timeout – timeout in seconds

  • timed_out – if non-null, set to true if timeout reached without handle being signaled; set to false otherwise (output)

Returns:

True if handle was signaled, false otherwise (e.g. object was destroyed or timed out)

wpiutil.sync.wait_for_objects(*args, **kwargs)

Overloaded function.

  1. wait_for_objects(handles: List[typing.SupportsInt | typing.SupportsIndex]) -> list[int]

Waits for one or more handles to be signaled.

Invalid handles are treated as signaled; the returned array will have the handle error bit set for any invalid handles.

Parameters:

  • handles – array of handles to wait on

  • signaled – output array for storage of signaled handles; must be at least the size of the handles input array

Returns:

array of signaled handles (points into signaled array)

  1. wait_for_objects(handles: List[typing.SupportsInt | typing.SupportsIndex], timeout: typing.SupportsFloat | typing.SupportsIndex) -> tuple[list[int], bool]

Waits for one or more handles to be signaled, with timeout.

Invalid handles are treated as signaled; the returned array will have the handle error bit set for any invalid handles.

Parameters:

  • handles – array of handles to wait on

  • signaled – output array for storage of signaled handles; must be at least the size of the handles input array

  • timeout – timeout in seconds

  • timed_out – if non-null, set to true if timeout reached without any handle being signaled; set to false otherwise (output)

Returns:

array of signaled handles (points into signaled array)