TSDuck Version 3.15-955 (TSDuck - The MPEG Transport Stream Toolkit)
ts::Guard Class Reference

Automatic guard class for mutex (ts::MutexInterface). More...

Inheritance diagram for ts::Guard:

Classes

class  GuardError
 Fatal low-level mutex guard error. More...
 

Public Member Functions

 Guard (MutexInterface &mutex, MilliSecond timeout=Infinite)
 Constructor, automatically acquire the mutex with a timeout. More...
 
virtual ~Guard ()
 Destructor, automatically release the mutex. More...
 
bool isLocked () const
 Check if the mutex was actually locked. More...
 

Detailed Description

Automatic guard class for mutex (ts::MutexInterface).

This class implements the guard design pattern for mutex, as defined by ts::MutexInterface.

The common pitfall in the usage of resources which must be explicitly released after having been acquired is the absence of release. This can be an omission in the code (no invocation of release() at all) or a premature exit from the code sequence between the acquire and release operations (exception or return statement).

Example:

Mutex mutex;
...
mutex.acquire();
...
// some exception occurs here and release() is never invoked.
...
mutex.release();

The guard design pattern mitigates this risk. Each critical sequence is a code block. Within the code block, an ancillary object, the guard, is created and refers to the common mutex object. The constructor of the guard automatically acquires the mutex and its destructor automatically releases the mutex.

There is no need for an explicit release of the mutex. If there is an exception or a premature exit of the code block, the C++ language guarantees that the destructor of the guard will be invoked and that the mutex will be released in all cases.

Example:

Mutex mutex;
...
{
MutexGuard guard (mutex); // mutex acquired
...
// some exception occurs here, no problem, don't worry
...
} // guard's destructor invoked, mutex always released

Constructor & Destructor Documentation

◆ Guard()

ts::Guard::Guard ( MutexInterface mutex,
MilliSecond  timeout = Infinite 
)

Constructor, automatically acquire the mutex with a timeout.

Unlike the other constructor (the one without timeout), there is no guarantee that the mutex is locked after construction. The user has to invoke isLocked() to check that the mutex was actually acquired before the timeout expired.

Parameters
[in,out]mutexA reference on the mutex object to acquire.
[in]timeoutMaximum number of milliseconds to wait for the mutex.
Exceptions
ts::Guard::GuardErrorThrown whenever an error occurs during the acquisition of the mutex. Exceeding the timeout is not error, the object is successfully constructed but isLocked() will return false.

◆ ~Guard()

virtual ts::Guard::~Guard ( )
virtual

Destructor, automatically release the mutex.

Exceptions
ts::Guard::GuardErrorThrown whenever an error occurs during the release of the mutex, i.e. when ts::MutexInterface::release() returns false.

Member Function Documentation

◆ isLocked()

bool ts::Guard::isLocked ( ) const
inline

Check if the mutex was actually locked.

This method is useful only with the object was constructed with a timeout. When the constructor without timeout was used, this method always return true.

Returns
True if the mutex was successfully acquired and false if the timeout expired.

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