Condition Struct Reference

#include <evo/thread.h>

Detailed Description

Condition object for thread synchronization.

• Used to make one or more threads sleep until a notification is signalled
• This works with an associated mutex, which is created if needed
• This is a low-level interface with public members
• Thread safe
• Linking:
  • Linux/Unix: -pthread
  • Cygwin: -lpthread
  • Windows: Usually multithreaded by default – MSVC project settings: C/C++ -> Code Generation -> Runtime Library

Public Types
typedef pthread_cond_t	Handle
typedef SmartLock< Condition >	Lock
	Lock object type – see SmartLock. More...

Public Member Functions
	Condition ()
	Default constructor. More...
	Condition (Mutex &mutex)
	Constructor. More...
	~Condition ()
	Destructor. More...
void	lock ()
	Lock associated mutex. More...
void	lock_notify ()
	Lock associated mutex, call notify(), then unlock. More...
void	lock_notify_all ()
	Lock associated mutex, call notify_all(), then unlock. More...
bool	lock_wait (ulong timeout_ms=Condition::INF)
	Lock associated mutex, call wait(), then unlock. More...
void	notify ()
	Notify and wake a waiting thread. More...
void	notify_all ()
	Notify and wake all waiting threads. More...
bool	trylock ()
	Try to lock associated mutex, fail if already locked (non-blocking). More...
bool	trylock (ulong timeout_ms)
	Try to lock associated mutex with a timeout. More...
void	unlock ()
	Unlock associated mutex. More...
bool	wait (ulong timeout_ms=Condition::INF, bool locked=true)
	Wait for notification or timeout. More...
bool	wait_inf (bool locked=true)
	Wait for notification. More...

Public Attributes
Handle	handle
	Condition object handle – do not modify. More...
Mutex *	mutex
	Pointer to associated mutex, never NULL – do not modify. More...
bool	owned
	Whether associated mutex is owned by this – do not modify. More...

Static Public Attributes
static const ulong	INF = ULONG_MAX
	Infinite wait timeout value. More...

Member Typedef Documentation

Handle

typedef pthread_cond_t Handle

Lock

typedef SmartLock<Condition> Lock

Lock object type – see SmartLock.

Constructor & Destructor Documentation

Condition() [1/2]

Condition ( )

inline

Default constructor.

• This creates (and owns) a new default mutex to use

Condition() [2/2]

Condition ( Mutex &  mutex )

inline

Constructor.

• This associates with an existing mutex (doesn't assume ownership)
• Associated mutex must remain valid while used here

Parameters

mutex

Mutex to associate with

~Condition()

~Condition ( )

inline

Destructor.

Member Function Documentation

lock()

void lock ( )

inline

Lock associated mutex.

• Must call unlock() after each lock(), otherwise results are undefined
• Results are undefined if already locked by current thread

lock_notify()

void lock_notify ( )

inline

Lock associated mutex, call notify(), then unlock.

• This wakes up a waiting thread

lock_notify_all()

void lock_notify_all ( )

inline

Lock associated mutex, call notify_all(), then unlock.

• This wakes up all waiting threads

lock_wait()

bool lock_wait ( ulong  timeout_ms = Condition::INF )

inline

Lock associated mutex, call wait(), then unlock.

Parameters

timeout_ms

Wait timeout in milliseconds, 0 for immediate (no wait), INF for indefinitely

Returns

Whether condition was notified, false on error (timed out)

notify()

void notify ( )

inline

Notify and wake a waiting thread.

• Mutex lock is not required, but ideally mutex should be locked for most consistent/predictable behavior
• See lock_notify()

notify_all()

void notify_all ( )

inline

Notify and wake all waiting threads.

• Mutex lock is not required, but ideally mutex should be locked for most consistent/predictable behavior
• See lock_notify_all()

trylock() [1/2]

bool trylock ( )

inline

Try to lock associated mutex, fail if already locked (non-blocking).

• On success, must call unlock() to unlock mutex
• Results are undefined if already locked by current thread

Returns

Whether successful, false if lock failed because mutex is already locked

trylock() [2/2]

bool trylock ( ulong  timeout_ms )

inline

Try to lock associated mutex with a timeout.

• On success, must call unlock() to unlock mutex
• Results are undefined if already locked by current thread
• OSX: This does a spin wait (which consumes CPU) since OSX doesn't support timeout on pthread mutex lock
• Windows: This does a spin wait (which consumes CPU) since Windows doesn't support timeout on Critical Section lock

Parameters

timeout_ms

Timeout in milliseconds

Returns

Whether successful, false on timeout

unlock()

void unlock ( )

inline

Unlock associated mutex.

• Results are undefined if called while mutex not locked

wait()

bool wait ( ulong  timeout_ms = Condition::INF, bool  locked = true  )

inline

Wait for notification or timeout.

• Either the associated mutex must already be locked, or set locked to false to lock here
• Associated mutex is atomically unlocked during wait, and will be locked again when this returns
• This may wake up early for no apparent reason, so actual state should be tracked with another variable
• Waiting forever is usually not ideal, threads should wake periodically to check if cancelled
• When locked=false:
  • This will try to lock with timeout_ms
  • Windows & OSX: Trying to lock does a spin wait (which consumes CPU) – to avoid this lock first then pass locked=true

Parameters

timeout_ms	Wait timeout in milliseconds, 0 for immediate (no wait), INF for indefinitely
locked	Whether to assume associated mutex is locked, false to lock it here

Returns

Whether condition was notified, false on error (timed out)

wait_inf()

bool wait_inf ( bool  locked = true )

inline

Wait for notification.

• This calls wait() with INF timeout
• See notes for wait()

Parameters

locked

Whether to assume associated mutex is locked, false to lock it here

Returns

Whether condition was notified, false on error (timed out)

Member Data Documentation

handle

Handle handle

Condition object handle – do not modify.

INF

const ulong INF = ULONG_MAX

static

Infinite wait timeout value.

mutex

Mutex* mutex

Pointer to associated mutex, never NULL – do not modify.

owned

bool owned

Whether associated mutex is owned by this – do not modify.

---

The documentation for this struct was generated from the following file:

• evo/thread.h