Visible to Intel only — GUID: GUID-2FE5C740-FE49-4933-949E-4F2A0E1C41A9
Package Contents
Parallelizing Simple Loops
Parallelizing Complex Loops
Parallelizing Data Flow and Dependence Graphs
Work Isolation
Exceptions and Cancellation
Containers
Mutual Exclusion
Timing
Memory Allocation
The Task Scheduler
Design Patterns
Migrating from Threading Building Blocks (TBB)
Constrained APIs
Appendix A Costs of Time Slicing
Appendix B Mixing With Other Threading Packages
References
oneapi::tbb::info namespace
parallel_for_each Body semantics and requirements
parallel_sort ranges interface extension
Type-specified message keys for join_node
Scalable Memory Pools
Helper Functions for Expressing Graphs
concurrent_lru_cache
task_arena::constraints extensions
oneapi::tbb::info namespace extensions
task_group extensions
The customizing mutex type for concurrent_hash_map
Visible to Intel only — GUID: GUID-2FE5C740-FE49-4933-949E-4F2A0E1C41A9
Mutual Exclusion
Mutual exclusion controls how many threads can simultaneously run a region of code. In Intel® oneAPI Threading Building Blocks (oneTBB), mutual exclusion is implemented by mutexes and locks. A mutex is an object on which a thread can acquire a lock. Only one thread at a time can have a lock on a mutex; other threads have to wait their turn.
The simplest mutex is spin_mutex. A thread trying to acquire a lock on a spin_mutex busy waits until it can acquire the lock. A spin_mutex is appropriate when the lock is held for only a few instructions. For example, the following code uses a mutex FreeListMutex to protect a shared variable FreeList. It checks that only a single thread has access to FreeList at a time.
Node* FreeList;
typedef spin_mutex FreeListMutexType;
FreeListMutexType FreeListMutex;
Node* AllocateNode() {
Node* n;
{
FreeListMutexType::scoped_lock lock(FreeListMutex);
n = FreeList;
if( n )
FreeList = n->next;
}
if( !n )
n = new Node();
return n;
}
void FreeNode( Node* n ) {
FreeListMutexType::scoped_lock lock(FreeListMutex);
n->next = FreeList;
FreeList = n;
}
The constructor for scoped_lock waits until there are no other locks on FreeListMutex. The destructor releases the lock. The braces inside routine AllocateNode may look unusual. Their role is to keep the lifetime of the lock as short as possible, so that other waiting threads can get their chance as soon as possible.
CAUTION:
Be sure to name the lock object, otherwise it will be destroyed too soon. For example, if the creation of the scoped_lock object in the example is changed to
FreeListMutexType::scoped_lock (FreeListMutex);
then the scoped_lock is destroyed when execution reaches the semicolon, which releases the lock beforeFreeList is accessed.
The following shows an alternative way to write AllocateNode:
Node* AllocateNode() {
Node* n;
FreeListMutexType::scoped_lock lock;
lock.acquire(FreeListMutex);
n = FreeList;
if( n )
FreeList = n->next;
lock.release();
if( !n )
n = new Node();
return n;
}
Method acquire waits until it can acquire a lock on the mutex; method release releases the lock.
It is recommended that you add extra braces where possible, to clarify to maintainers which code is protected by the lock.
If you are familiar with C interfaces for locks, you may be wondering why there are not simply acquire and release methods on the mutex object itself. The reason is that the C interface would not be exception safe, because if the protected region threw an exception, control would skip over the release. With the object-oriented interface, destruction of the scoped_lock object causes the lock to be released, no matter whether the protected region was exited by normal control flow or an exception. This is true even for our version of AllocateNode that used methods acquire and release – the explicit release causes the lock to be released earlier, and the destructor then sees that the lock was released and does nothing.
All mutexes in oneTBB have a similar interface, which not only makes them easier to learn, but enables generic programming. For example, all of the mutexes have a nested scoped_lock type, so given a mutex of type M, the corresponding lock type is M::scoped_lock.
TIP:
It is recommended that you always use a typedef for the mutex type, as shown in the previous examples. That way, you can change the type of the lock later without having to edit the rest of the code. In the examples, you could replace the typedef with typedef queuing_mutex FreeListMutexType, and the code would still be correct.