Peano 4
No Matches
tarch::mpi::BooleanSemaphore Class Reference

Boolean semaphore across MPI ranks. More...

#include <BooleanSemaphore.h>

Collaboration diagram for tarch::mpi::BooleanSemaphore:

Data Structures

class  BooleanSemaphoreService

Public Member Functions

 BooleanSemaphore ()
 Create new boolean semaphore spanning all MPI ranks.
 ~BooleanSemaphore ()

Private Member Functions

void enterCriticalSection ()
 Waits until I can enter the critical section.
void leaveCriticalSection ()
 Tells the semaphore that it is about to leave.
 BooleanSemaphore (const BooleanSemaphore &)=delete
 You may not copy a semaphore.
BooleanSemaphoreoperator= (const BooleanSemaphore &)=delete
 You may not copy a semaphore.

Private Attributes

const int _semaphoreNumber
tarch::multicore::BooleanSemaphore _localRankLockRequestSemaphore

Static Private Attributes

static tarch::logging::Log _log
static int _semaphoreCounter


class Rank
class tarch::mpi::Lock

Detailed Description

Boolean semaphore across MPI ranks.

Only one thread on one rank gets access to a certain code region. This means that this particular semaphore represents a critical section across both threads and ranks in one go. It is inherently multithreading-safe.

Each boolean semaphore constructs a unique global number which is used to identify the semaphore within the whole system. When we request a lock, we send an integer message with this number to the global master through the semaphore tag. If we we release it, we send the negative number back.

As an mpi semaphore includes all ranks and all threads, it is something that is more general than a "normal" tarch::multicore::BooleanSemaphore. Therefore, the mpi semaphore hosts a multicore semaphore. As long as a thread on the local rank has blocked a critical section, we don't even have to go to the global master.

However, this is not the only semaphore: On the global master, we need a second semaphore to protect the global semaphore map. This map might be changed even if we are not in a critical section.


The implementation is straightforward:

  1. Lock the local rank.
  2. Send the integer tied to this boolean semaphore to the global master. Wait for the go ahead message to return.
  3. The master receives the lock request in the BooleanSemaphoreService. It tries to acquire a lock. Until it is successful, it continues to call receiveDanglingMessages().
  4. Once the master is successful in getting the lock, it send an integer message back to the sender. The sender now is allowed to proceed.
  5. Once successful, the rank releases the lock, which materialises in another message to the global master. This time, we can send logically unblocking, i.e. we don't have to wait for an answer.

Multiple request handling routines (calls of acquireLock()) can be active at the same time, i.e. reside on the global master's call stack. They will be served one by one, although implicitly in reverse order as we work with the call stack. It is important to poll receiveDanglingMessages() all the time, as we might wait for a lock to be freed, but for the lock to be freed, we have to check unexpected aka dangling messages.

Tobias Weinzierl

Definition at line 71 of file BooleanSemaphore.h.

Constructor & Destructor Documentation

◆ BooleanSemaphore() [1/2]

tarch::mpi::BooleanSemaphore::BooleanSemaphore ( const BooleanSemaphore & )

You may not copy a semaphore.

◆ BooleanSemaphore() [2/2]

tarch::mpi::BooleanSemaphore::BooleanSemaphore ( )

Create new boolean semaphore spanning all MPI ranks.

Register a new global semaphore. Please note that global semaphores have to be static, and that each rank has to have the same one and create the MPI semaphores in the same order (SPMD programming paradigm).

What happens is that the constructor grabs a unique number for this MPI semaphore, and stores it in _semaphoreNumber. This number will later be used globally to identify this semaphore type.

Definition at line 25 of file BooleanSemaphore.cpp.

References _semaphoreCounter.

◆ ~BooleanSemaphore()

tarch::mpi::BooleanSemaphore::~BooleanSemaphore ( )

Definition at line 31 of file BooleanSemaphore.cpp.

Member Function Documentation

◆ enterCriticalSection()

void tarch::mpi::BooleanSemaphore::enterCriticalSection ( )

Waits until I can enter the critical section.

This operation is protected, as you should not invoke it directly. Use tarch::mpi::Lock to acquire it. With such a lock object, you can be sure that the lock is released (the latest when the object is destroyed. This way, your code is a little bit more deadlock-free. You cannot forget to release an MPI semaphore.

Definition at line 15 of file BooleanSemaphore.cpp.

References _localRankLockRequestSemaphore, _semaphoreNumber, tarch::mpi::BooleanSemaphore::BooleanSemaphoreService::acquireLock(), tarch::multicore::BooleanSemaphore::enterCriticalSection(), and tarch::mpi::BooleanSemaphore::BooleanSemaphoreService::getInstance().

Here is the call graph for this function:

◆ leaveCriticalSection()

void tarch::mpi::BooleanSemaphore::leaveCriticalSection ( )

Tells the semaphore that it is about to leave.

See also

Definition at line 20 of file BooleanSemaphore.cpp.

◆ operator=()

BooleanSemaphore & tarch::mpi::BooleanSemaphore::operator= ( const BooleanSemaphore & )

You may not copy a semaphore.

Friends And Related Symbol Documentation

◆ Rank

friend class Rank

Definition at line 308 of file BooleanSemaphore.h.

◆ tarch::mpi::Lock

friend class tarch::mpi::Lock

Definition at line 309 of file BooleanSemaphore.h.

Field Documentation

◆ _localRankLockRequestSemaphore

tarch::multicore::BooleanSemaphore tarch::mpi::BooleanSemaphore::_localRankLockRequestSemaphore
explain why we lock locally first

Definition at line 320 of file BooleanSemaphore.h.

Referenced by enterCriticalSection().

◆ _log

tarch::logging::Log tarch::mpi::BooleanSemaphore::_log

Definition at line 311 of file BooleanSemaphore.h.

◆ _semaphoreCounter

int tarch::mpi::BooleanSemaphore::_semaphoreCounter

Definition at line 313 of file BooleanSemaphore.h.

Referenced by BooleanSemaphore().

◆ _semaphoreNumber

const int tarch::mpi::BooleanSemaphore::_semaphoreNumber

Definition at line 315 of file BooleanSemaphore.h.

Referenced by enterCriticalSection().

The documentation for this class was generated from the following files: