B_ QuRT_ User_ Guide(20)

13 Condition variables,

Threads use conditional variables to synchronize their execution based on values in shared data items . Conditional variables are useful in situations where a thread must normally continuously poll a data item until it contains a specific value —— Using conditional variables, threads can accomplish the same task without polling .

Condition variables are always associated with mutexes （ The first 5 section ） Use it together , To ensure that shared data items are checked and updated without thread contention .

For threads waiting for specific conditions of shared data items , It must first lock the mutex that controls access to the data item . If the conditions are not met , Then the thread performs the wait condition operation on the condition variable （ Suspend the thread and unlock the mutex ）.

For a thread, send a signal that the condition is true on the shared data item , It must first lock the mutex that controls access to the data item , Then perform the signal condition operation , Finally, the mutex is explicitly unlocked .

Signal condition operation is used to wake up a single waiting thread . If multiple threads are waiting for a condition variable , They can all be awakened by broadcast conditional operation .

 Be careful ： Failure to properly lock and unlock mutexes using conditional variables may cause the thread to never hang （ Or pause but never wake up ）.    

because QuRT Allow the thread to be awakened by false conditions , So the thread should always verify the target condition when it is awakened .

Condition variables are shared objects that support the following operations ：

• qurt_cond_broadcast()
• qurt_cond_destroy()
• qurt_cond_init()
• qurt_cond_signal()
• qurt_cond_wait()
• qurt_cond_wait2()
• Data Types

13.1 qurt_cond_broadcast()

13.1.1 Function document

13.1.1.1 void qurt_cond_broadcast ( qurt_cond_t ∗ cond )

Notify multiple waiting threads that the specified condition is true .
When a thread wants to broadcast a condition that is true on a shared data item , It must perform the following process ：

1. Lock mutexes that control access to data items .
2. Perform broadcast condition operation .
3. Unlock the mutex .

 Be careful ： Failure to properly lock and unlock mutexes of condition variables may cause the thread to never hang （ Or pause but never wake up ）.
 Use condition variables only with regular mutexes —— Trying to use recursive mutexes or priority inheritance mutexes can lead to undefined behavior .

Related data types
qurt_cond_t

Parameters

in	cond	Pointer to the conditional variable object to signal .

Return value
None.

Dependency relationship
None.

13.2 qurt_cond_destroy()

13.2.1 Function document

13.2.1.1 void qurt_cond_destroy ( qurt_cond_t ∗ cond )

Destroy the specified condition variable .

 Be careful ： Conditions must be destroyed when they are no longer in use .   Failure to do so will result in  QuRT  A resource leak in the kernel .
 Do not destroy the conditions that are still in use .   If this happens , be  QuRT  The behavior of is undefined .

Related data types
qurt_cond_t

Parameters

in	cond	Pointer to the condition variable object to destroy .

Return value
None.

13.3 qurt_cond_init()

13.3.1 Function document

13.3.1.1 void qurt_cond_init ( qurt_cond_t ∗ cond )

Initialize a condition variable object .

Related data types
qurt_cond_t

Parameters

out	cond	Pointer to initialized condition variable object .

Return value
None.

Dependency relationship
None.

13.4 qurt_cond_signal()

13.4.1 Function document

13.4.1.1 void qurt_cond_signal ( qurt_cond_t ∗ cond )

Notifies the waiting thread that the specified condition is true .
When a thread wants to signal that a condition is true on a shared data item , It must perform the following process ：

1. Lock mutexes that control access to data items .
2. Perform signal condition operation .
3. Unlock the mutex .

 Be careful ： Failure to properly lock and unlock mutexes on condition variables may cause the thread to never hang （ Or pause but never wake up ）.
 Use condition variables only with regular mutexes —— Trying to use recursive mutexes or priority inheritance mutexes can lead to undefined behavior .

Related data types
qurt_cond_t

Parameters

in	cond	Pointer to the conditional variable object to signal .

Return value
None.

Dependency relationship
None.

13.5 qurt_cond_wait()

13.5.1 Function document

13.5.1.1 void qurt_cond_wait ( qurt_cond_t ∗ cond, qurt_mutex_t ∗ mutex )

Suspends the current thread , Until the specified condition is true . When a thread wants to wait for a specific condition for a shared data item , It must perform the following process ：

1. Lock mutexes that control access to data items .
2. If the conditions are not met , Wait for the condition variable （ Hung thread , Unlock the mutex ）.

 Be careful ： Failure to properly lock and unlock mutexes of condition variables may cause the thread to never hang （ Or pause but never wake up ）.    
 Use condition variables only with regular mutexes —— Trying to use recursive mutexes or priority inheritance mutexes can lead to undefined behavior .

Related data types
qurt_cond_t
qurt_mutex_t

Parameters

in	cond	Pointer to the condition variable object to wait for .
in	mutex	Pointer to the mutex associated with the condition variable to wait for .

Return value
None.

Dependency relationship
None.

13.6 qurt_cond_wait2()

13.6.1 Function document

13.6.1.1 void qurt_cond_wait2 ( qurt_cond_t ∗ cond, qurt_rmutex2_t ∗ mutex )

Suspends the current thread , Until the specified condition is true . When a thread wants to wait for a specific condition for a shared data item , It must perform the following process ：

1. Lock mutexes that control access to data items .
2. If the conditions are not met , Wait for the condition variable （ Hung thread , Unlock the mutex ）.

 Be careful ： Failure to properly lock and unlock mutexes of condition variables may cause the thread to never hang （ Or pause but never wake up ）.
 Use condition variables only with regular mutexes —— Trying to use recursive mutexes or priority inheritance mutexes can lead to undefined behavior .
 This is the  qurt_cond_wait()  same  API, In the use of  qurt_rmutex2_t  This version is used for mutexes of type .

Related data types
qurt_cond_t
qurt_rmutex2_t

Parameters

in	cond	Pointer to the condition variable object to wait for .
in	mutex	Pointer to the mutex associated with the condition variable to wait for .

Return value
None.

Dependency relationship
None.

13.7 data type

This section describes the data types of conditional variable services .

• Conditional variables in QuRT Said to qurt_cond_t Object of type .

13.7.1 Data structure document

13.7.1.1 union qurt_cond_t

QuRT Condition variable type .