ConditionVariableEntry Struct Reference

Waiting on a condition variable. More...

Inherits DoublyLinkedListLinkImpl< ConditionVariableEntry >.

Public Member Functions
bool	Add (const void *object)
	Watch the published condition variable associated with the object.
ConditionVariable *	Variable () const
	Get a pointer to the added condition variable object.
status_t	Wait (const void *object, uint32 flags=0, bigtime_t timeout=0)
	Convenience method to add a condition variable and immediately wait on it.
status_t	Wait (uint32 flags=0, bigtime_t timeout=0)
	Wait for the condition variable to be notified.

Detailed Description

Waiting on a condition variable.

Waiting on a condition variable is implemented by creating a ConditionVariableEntry, associating it to a condition variable (using either Add(const void*) or ConditionVariable::Add(ConditionVariableEntry*) ), and then waiting for the condition variable to be notified using Wait(uint32, bigtime_t).

Member Function Documentation

Add()

bool ConditionVariableEntry::Add

(

const void *

object

)

Watch the published condition variable associated with the object.

This method is used to watch a condition variable previously published using ConditionVariable::Publish(const cvoid*, const char*). The condition variable corresponding to the object will be located and the condition variable entry will be added to it.

A ConditionVariableEntry can only be added to one single ConditionVariable.

It is safe to delete a ConditionVariableEntry without having waited for the corresponding event.

Returns

false if the entry could not be added. In that case, calling Wait() will immediately fail and return the corresponding error code B_ENTRY_NOT_FOUND.

Variable()

ConditionVariable * ConditionVariableEntry::Variable

(

)

const

Get a pointer to the added condition variable object.

This allows to access the ConditionVariable object previously added to the condition variable. It is especially useful if you need to access a published condition variable, which you cannot access directly until adding it to a ConditionVariableEntry.

This returns NULL if the condition variable entry is not attached attached to any condition variable, including when the condition variable has already notified the entry.

Wait() [1/2]

status_t ConditionVariableEntry::Wait	(	const void *	object,
		uint32	flags = 0,
		bigtime_t	timeout = 0
	)

Convenience method to add a condition variable and immediately wait on it.

This combines the effect of the Add and Wait methods. You can use this if you are waiting on a published condition variable, and do not need to perform any other work between adding and waiting (such as releasing other locks to perform a "lock switch").

Wait() [2/2]

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

Wait for the condition variable to be notified.

Parameters

flags	timeout and semaphore flags to use
timeout	in microseconds if enabled by flags

Returns

The status code passed to Notify to wake up the thread

Wait for the previously added condition variable to be notified. The thread is blocked until then, or until a timeout occurs. The entry is then removed from the condition variable waiting list. It can be reused by adding it to the same or another condition variable.

If the condition variable was already notified since this entry was added to it, the function returns immediately and does not block the thread.

The flags can be used to:

• Limit the wait to a timeout using B_RELATIVE_TIMEOUT or B_ABSOLUTE_TIMEOUT
• Control semaphore behavior (B_CAN_INTERRUPT, B_KILL_CAN_INTERRUPT)