ConditionVariable Struct Reference

Condition variable for thread and interrupt synchronization. More...

Public Member Functions
void	Add (ConditionVariableEntry *entry)
	Add a ConditionVariableEntry to the waiting list for this condition variable.
int32	EntriesCount ()
	Return the number of ConditionVariableEntries that are currently in the ConditionVariable.
void	Init (const void *object, const char *objectType)
	Initialize an anonymous (unpublished) condition variable.
int32	NotifyAll (status_t result=B_OK)
	Notify all the threads waiting on the condition variable.
int32	NotifyOne (status_t result=B_OK)
	Notify one of the threads waiting on the condition variable.
void	Publish (const void *object, const char *objectType)
	Initialize and publish a condition variable associated with an object.
void	Unpublish ()
	Unpublish a previously published condition variable.
status_t	Wait (mutex *lock, uint32 flags=0, bigtime_t timeout=0)
	Convenience method for atomically unlocking a mutex and waiting on a condition variable.
status_t	Wait (recursive_lock *lock, uint32 flags=0, bigtime_t timeout=0)
	Convenience method for atomically unlocking a recursive_lock and waiting on a condition variable.
status_t	Wait (uint32 flags=0, bigtime_t timeout=0)
	Convenience method for waiting without an explicit ConditionVariableEntry.

Static Public Member Functions
static int32	NotifyAll (const void *object, status_t result)
	Notify all threads waiting on the published condition variable for object.
static int32	NotifyOne (const void *object, status_t result)
	Notify one thread waiting on the published condition variable for object.

Detailed Description

Condition variable for thread and interrupt synchronization.

Condition variables implement the wait/notify pattern. They are usually associated with an "object" (for the condition variable's own purposes, that is just an opaque pointer).

One thread will use the Wait functions or a ConditionVariableEntry to wait on the condition variable. When another thread or an interrupt needs to wake up one such thread, it does so by notifying the condition variable.

Condition variables are usually used in combination with a mutex, recursive_lock, or some other direct use of the ConditionVariableEntry struct with its two-step interface (Add() then Wait()) allows usage of any other locking design, or even with no locking at all if the order of operations is already guaranteed by the code structure.

There are no restrictions on the destruction order: a condition variable may be destructed while there are condition variable entries waiting on it, or the condition variable entries may be destructed before they are notified.

Member Function Documentation

EntriesCount()

int32 ConditionVariable::EntriesCount ( )

inline

Return the number of ConditionVariableEntries that are currently in the ConditionVariable.

The threads associated with such entries may already be waiting, or still executing other code between their Add and Wait steps.

References atomic_get().

Init()

void ConditionVariable::Init	(	const void *	object,
		const char *	objectType
	)

Initialize an anonymous (unpublished) condition variable.

Parameters

object	Object that the condition variable is associated with.
objectType	String describing the associated object, for debugging purposes.

Anonymous condition variables cannot be used with ConditionVariableEntry::Add() and will not appear in the kernel debugger list of condition variables (it can still be examined by the dump command if you have a pointer to it). The other methods can be used without restrictions.

NotifyAll() [1/2]

static int32 ConditionVariable::NotifyAll ( const void *  object, status_t  result  )

static

Notify all threads waiting on the published condition variable for object.

Returns

The number of threads that were notified

NotifyAll() [2/2]

int32 ConditionVariable::NotifyAll ( status_t  result = B_OK )

inline

Notify all the threads waiting on the condition variable.

Parameters

result

Result value that will be returned by the Wait call in the notified thread.

Returns

Number of threads that will the result value

NotifyOne() [1/2]

static int32 ConditionVariable::NotifyOne ( const void *  object, status_t  result  )

static

Notify one thread waiting on the published condition variable for object.

Returns

The number of threads that were notified (0 or 1)

NotifyOne() [2/2]

int32 ConditionVariable::NotifyOne ( status_t  result = B_OK )

inline

Notify one of the threads waiting on the condition variable.

Parameters

result

Result value that will be returned by the Wait call in the notified thread.

Returns

Number of threads that will receive the result value (0 if no ConditionVariableEntry was attached, or 1 if there were)

If the thread was already blocked by calling Wait, its execution is resumed.

If the thread had added a ConditionVariableEntry to the condition variable but is not yet waiting on it, the call to Wait will not block, and will immediately return the result value.

Publish()

void ConditionVariable::Publish	(	const void *	object,
		const char *	objectType
	)

Initialize and publish a condition variable associated with an object.

The condition variable is published: ConditionVariableEntry::Add() can be used on the associated object, and the condition variable will be present in the kernel debugger's condition variables list.

Publication allows to associate a condition variable with another object that is accessed from multiple drivers or kernel modules. For example, this can be used to notify some events from low level drivers to higher level ones (interrupts, hot-pluggable device being removed, ...) by publishing condition variables associated to device tree nodes.

Wait() [1/3]

status_t ConditionVariable::Wait	(	mutex *	lock,
		uint32	flags = 0,
		bigtime_t	timeout = 0
	)

Convenience method for atomically unlocking a mutex and waiting on a condition variable.

Create and add a temporary ConditionVariableEntry to the condition variable, unlock the mutex, wait on the condition variable, and re-acquire the mutex.

This allows to use the condition variable safely for inter-thread synchronization with mutex.

Wait() [2/3]

status_t ConditionVariable::Wait	(	recursive_lock *	lock,
		uint32	flags = 0,
		bigtime_t	timeout = 0
	)

Convenience method for atomically unlocking a recursive_lock and waiting on a condition variable.

Create and add a temporary ConditionVariableEntry to the condition variable, unlock the recursive_lock, wait on the condition variable, and re-acquire the recursive_lock.

The recursion count of the recursive lock is preserved.

This allows to use the condition variable safely for inter-thread synchronization with a recursive_lock.

Wait() [3/3]

status_t ConditionVariable::Wait	(	uint32	flags = 0,
		bigtime_t	timeout = 0
	)

Convenience method for waiting without an explicit ConditionVariableEntry.

Create and add a temporary ConditionVariableEntry to the condition variable, then wait on it.