WPILibC++ 2024.3.2
Synchronization.h File Reference
#include <climits>
#include <initializer_list>
#include <span>

Go to the source code of this file.

Classes

class  wpi::Event
 An atomic signaling event for synchronization. More...
 
class  wpi::Semaphore
 A semaphore for synchronization. More...
 
class  wpi::SignalObject< T >
 RAII wrapper for signaling handles. More...
 

Namespaces

namespace  wpi
 

Typedefs

typedef unsigned int WPI_Handle
 Generic handle for all WPI handle-based interfaces. More...
 
typedef WPI_Handle WPI_EventHandle
 An event handle. More...
 
typedef WPI_Handle WPI_SemaphoreHandle
 A semaphore handle. More...
 

Functions

WPI_EventHandle wpi::CreateEvent (bool manualReset=false, bool initialState=false)
 Creates an event. More...
 
void wpi::DestroyEvent (WPI_EventHandle handle)
 Destroys an event. More...
 
void wpi::SetEvent (WPI_EventHandle handle)
 Sets an event to signaled state. More...
 
void wpi::ResetEvent (WPI_EventHandle handle)
 Sets an event to non-signaled state. More...
 
WPI_SemaphoreHandle wpi::CreateSemaphore (int initialCount=0, int maximumCount=INT_MAX)
 Creates a semaphore. More...
 
void wpi::DestroySemaphore (WPI_SemaphoreHandle handle)
 Destroys a semaphore. More...
 
bool wpi::ReleaseSemaphore (WPI_SemaphoreHandle handle, int releaseCount=1, int *prevCount=nullptr)
 Releases N counts of a semaphore. More...
 
bool wpi::WaitForObject (WPI_Handle handle)
 Waits for an handle to be signaled. More...
 
bool wpi::WaitForObject (WPI_Handle handle, double timeout, bool *timedOut)
 Waits for an handle to be signaled, with timeout. More...
 
std::span< WPI_Handlewpi::WaitForObjects (std::span< const WPI_Handle > handles, std::span< WPI_Handle > signaled)
 Waits for one or more handles to be signaled. More...
 
std::span< WPI_Handlewpi::WaitForObjects (std::initializer_list< WPI_Handle > handles, std::span< WPI_Handle > signaled)
 Waits for one or more handles to be signaled. More...
 
std::span< WPI_Handlewpi::WaitForObjects (std::span< const WPI_Handle > handles, std::span< WPI_Handle > signaled, double timeout, bool *timedOut)
 Waits for one or more handles to be signaled, with timeout. More...
 
std::span< WPI_Handlewpi::WaitForObjects (std::initializer_list< WPI_Handle > handles, std::span< WPI_Handle > signaled, double timeout, bool *timedOut)
 Waits for one or more handles to be signaled, with timeout. More...
 
void wpi::CreateSignalObject (WPI_Handle handle, bool manualReset=false, bool initialState=false)
 Sets up signaling for an arbitrary handle. More...
 
void wpi::SetSignalObject (WPI_Handle handle)
 Sets a handle to signaled state. More...
 
void wpi::ResetSignalObject (WPI_Handle handle)
 Sets a handle to non-signaled state. More...
 
void wpi::DestroySignalObject (WPI_Handle handle)
 Cleans up signaling for a handle. More...
 
WPI_EventHandle WPI_CreateEvent (int manual_reset, int initial_state)
 Creates an event. More...
 
void WPI_DestroyEvent (WPI_EventHandle handle)
 Destroys an event. More...
 
void WPI_SetEvent (WPI_EventHandle handle)
 Sets an event to signaled state. More...
 
void WPI_ResetEvent (WPI_EventHandle handle)
 Sets an event to non-signaled state. More...
 
WPI_SemaphoreHandle WPI_CreateSemaphore (int initial_count, int maximum_count)
 Creates a semaphore. More...
 
void WPI_DestroySemaphore (WPI_SemaphoreHandle handle)
 Destroys a semaphore. More...
 
int WPI_ReleaseSemaphore (WPI_SemaphoreHandle handle, int release_count, int *prev_count)
 Releases N counts of a semaphore. More...
 
int WPI_WaitForObject (WPI_Handle handle)
 Waits for an handle to be signaled. More...
 
int WPI_WaitForObjectTimeout (WPI_Handle handle, double timeout, int *timed_out)
 Waits for an handle to be signaled, with timeout. More...
 
int WPI_WaitForObjects (const WPI_Handle *handles, int handles_count, WPI_Handle *signaled)
 Waits for one or more handles to be signaled. More...
 
int WPI_WaitForObjectsTimeout (const WPI_Handle *handles, int handles_count, WPI_Handle *signaled, double timeout, int *timed_out)
 Waits for one or more handles to be signaled, with timeout. More...
 
void WPI_CreateSignalObject (WPI_Handle handle, int manual_reset, int initial_state)
 Sets up signaling for an arbitrary handle. More...
 
void WPI_SetSignalObject (WPI_Handle handle)
 Sets a handle to signaled state. More...
 
void WPI_ResetSignalObject (WPI_Handle handle)
 Sets a handle to non-signaled state. More...
 
void WPI_DestroySignalObject (WPI_Handle handle)
 Cleans up signaling for a handle. More...
 

Typedef Documentation

◆ WPI_EventHandle

An event handle.

◆ WPI_Handle

typedef unsigned int WPI_Handle

Generic handle for all WPI handle-based interfaces.

Handle data layout:

  • Bits 0-23: Type-specific
  • Bits 24-30: Type
  • Bit 31: Error

◆ WPI_SemaphoreHandle

A semaphore handle.

Function Documentation

◆ WPI_CreateEvent()

WPI_EventHandle WPI_CreateEvent ( int  manual_reset,
int  initial_state 
)

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_resettrue for manual reset, false for automatic reset
initial_statetrue to make the event initially in signaled state
Returns
Event handle

◆ WPI_CreateSemaphore()

WPI_SemaphoreHandle WPI_CreateSemaphore ( int  initial_count,
int  maximum_count 
)

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_countinitial value for the semaphore's internal counter
maximum_countmaximum value for the samephore's internal counter
Returns
Semaphore handle

◆ WPI_CreateSignalObject()

void WPI_CreateSignalObject ( WPI_Handle  handle,
int  manual_reset,
int  initial_state 
)

Sets up signaling for an arbitrary handle.

With this function, any handle can operate like an event handle.

Parameters
handlehandle
manual_resettrue for manual reset, false for automatic reset
initial_statetrue to make the handle initially in signaled state

◆ WPI_DestroyEvent()

void WPI_DestroyEvent ( WPI_EventHandle  handle)

Destroys an event.

Destruction wakes up any waiters.

Parameters
handleevent handle

◆ WPI_DestroySemaphore()

void WPI_DestroySemaphore ( WPI_SemaphoreHandle  handle)

Destroys a semaphore.

Destruction wakes up any waiters.

Parameters
handlesemaphore handle

◆ WPI_DestroySignalObject()

void WPI_DestroySignalObject ( WPI_Handle  handle)

Cleans up signaling for a handle.

Destruction wakes up any waiters.

Parameters
handlehandle

◆ WPI_ReleaseSemaphore()

int WPI_ReleaseSemaphore ( WPI_SemaphoreHandle  handle,
int  release_count,
int *  prev_count 
)

Releases N counts of a semaphore.

Parameters
handlesemaphore handle
release_countamount to add to semaphore's internal counter; must be positive
prev_countif non-null, previous count (output parameter)
Returns
Non-zero on successful release, zero on failure (e.g. release count would exceed maximum value, or handle invalid)

◆ WPI_ResetEvent()

void WPI_ResetEvent ( WPI_EventHandle  handle)

Sets an event to non-signaled state.

Parameters
handleevent handle

◆ WPI_ResetSignalObject()

void WPI_ResetSignalObject ( WPI_Handle  handle)

Sets a handle to non-signaled state.

Parameters
handlehandle

◆ WPI_SetEvent()

void WPI_SetEvent ( WPI_EventHandle  handle)

Sets an event to signaled state.

Parameters
handleevent handle

◆ WPI_SetSignalObject()

void WPI_SetSignalObject ( WPI_Handle  handle)

Sets a handle to signaled state.

Parameters
handlehandle

◆ WPI_WaitForObject()

int WPI_WaitForObject ( WPI_Handle  handle)

Waits for an handle to be signaled.

Parameters
handlehandle to wait on
Returns
Non-zero if handle was signaled, zero otherwise (e.g. object was destroyed)

◆ WPI_WaitForObjects()

int WPI_WaitForObjects ( const WPI_Handle handles,
int  handles_count,
WPI_Handle signaled 
)

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
handlesarray of handles to wait on
handles_countlength of the handles array
signaledoutput array for storage of signaled handles; must be at least the size of the handles input array
Returns
number of signaled handles

◆ WPI_WaitForObjectsTimeout()

int WPI_WaitForObjectsTimeout ( const WPI_Handle handles,
int  handles_count,
WPI_Handle signaled,
double  timeout,
int *  timed_out 
)

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
handlesarray of handles to wait on
handles_countlength of the handles array
signaledoutput array for storage of signaled handles; must be at least the size of the handles input array
timeouttimeout in seconds
timed_outif non-null, set to non-zero if timeout reached without any handle being signaled; set to zero otherwise (output)
Returns
number of signaled handles

◆ WPI_WaitForObjectTimeout()

int WPI_WaitForObjectTimeout ( WPI_Handle  handle,
double  timeout,
int *  timed_out 
)

Waits for an handle to be signaled, with timeout.

Parameters
handlehandle to wait on
timeouttimeout in seconds
timed_outif non-null, set to non-zero if timeout reached without handle being signaled; set to zero otherwise (output)
Returns
Non-zero if handle was signaled, zero otherwise (e.g. object was destroyed or timed out)