pike.git / src / threads.c

version» Context lines:

pike.git/src/threads.c:2583:   /*! @endclass    */      /*! @class Condition    *!    *! Implementation of condition variables.    *!    *! Condition variables are used by threaded programs    *! to wait for events happening in other threads.    *! +  *! In order to prevent races (which is the whole point of condition +  *! variables), the modification of a shared resource and the signal notifying +  *! modification of the resource must be performed inside the same mutex +  *! lock, and the examining of the resource and waiting for a signal that +  *! the resource has changed based on that examination must also happen +  *! inside the same mutex lock. +  *! +  *! Typical wait operation: +  *! @ol +  *! @item Take mutex lock +  *! @item Read/write shared resource +  *! @item Wait for the signal with the mutex lock in released state +  *! @item Reacquire mutex lock +  *! @item If needed, jump back to step 2 again +  *! @item Release mutex lock +  *! @endol +  *! +  *! Typical signal operation: +  *! @ol +  *! @item Take mutex lock +  *! @item Read/write shared resource +  *! @item Send signal +  *! @item Release mutex lock +  *! @endol +  *! +  *! @example +  *! You have some resource that multiple treads want to use. To +  *! protect this resource for simultaneous access, you create a shared mutex. +  *! Before you read or write the resource, you take the mutex so that you +  *! get a consistent and private view of / control over it. When you decide +  *! that the resource is not in the state you want it, and that you need +  *! to wait for some other thread to modify the state for you before you +  *! can continue, you wait on the conditional variable, which will +  *! temporarily relinquish the mutex during the wait. This way a +  *! different thread can take the mutex, update the state of the resource, +  *! and then signal the condition (which does not in itself release the +  *! mutex, but the signalled thread will be next in line once the mutex is +  *! released). +  *!    *! @note    *! Condition variables are only available on systems with thread    *! support. The Condition class is not simulated otherwise, since that    *! can't be done accurately without continuations.    *!    *! @seealso    *! @[Mutex]    */      struct pike_cond {