A mutex object to ensures atomicity. More...

Inheritance diagram for cppthread::mutex:

Public Types
typedef std::vector< mutex >	direct_vector_t
	A vector of mutexes.

typedef std::shared_ptr< mutex >	pointer_t
	Shared pointer to a mutex.

typedef std::vector< pointer_t >	vector_t
	A vector of mutexes.

Public Member Functions
	mutex ()
	An inter-thread mutex to ensure unicity of execution.

	mutex (mutex const &rhs)=delete

	~mutex ()
	Clean up a mutex object.

void	broadcast ()
	Broadcast a mutex signal.

bool	dated_wait (std::uint64_t const date)
	Wait on a mutex until the specified date.

bool	dated_wait (timespec const &date)
	Wait on a mutex until the specified date.

void	lock ()
	Lock a mutex.

mutex &	operator= (mutex const &rhs)=delete

void	safe_broadcast ()
	Broadcast a mutex signal.

void	safe_signal ()
	Signal a mutex.

void	signal ()
	Signal at least one mutex.

bool	timed_wait (std::uint64_t const usec)
	Wait on a mutex condition with a time limit.

bool	timed_wait (timespec const &nsec)
	Wait on a mutex condition with a time limit.

bool	try_lock ()
	Try locking the mutex.

void	unlock ()
	Unlock a mutex.

void	wait ()
	Wait on a mutex condition.

Private Attributes
std::shared_ptr< detail::mutex_impl >	f_impl
	The pthread mutex implementation.

std::uint32_t	f_reference_count = 0
	The lock reference count.

Detailed Description

This class is used by threads when some data accessed by more than one thread is about to be accessed. In most cases it is used with the guard class so it is safe even in the event an exception is raised.

{
    cppthread::guard lock(f_mutex);
 
    ...
} // <-- auto-unlock here

The mutex also includes a condition variable which can be signaled using the signal() function. This wakes threads that are currently waiting on the condition with one of the wait() functions.

{
    cppthread::guard lock(f_mutex);
 
    if(<some condition>)
    {
        // this unlocks, waits, and relocks your mutex
        f_mutex.wait();
    }
 
    ...
 
    f_mutex.signal();      // signal one other thread
       // or
    f_mutex.broadcast();   // signal all the other threads
} // <-- auto-unlock here

Note: We use a recursive mutex so you may lock the mutex any number of times. It has to be unlocked that many times. If you use the guard class, then the lock and unlock are fully automated and you won't run in any issues other than potential dead-locks.; The mutex copy and assignment operators are deleted. We do not allow you to copy a mutex because that is not a good idea. You probably have an issue in your code if you think you need to make a copy of a mutex. (although that our implementation, because of the f_impl, would allow for copies, it's still not a good idea.)

Definition at line 54 of file mutex.h.

Member Typedef Documentation

◆ direct_vector_t

cppthread::mutex::direct_vector_t

This type defines a vector of direct mutexes (i.e. not pointers to mutexes). This type can be used when you know the number of mutexes to allocate. Dynamically adding/removing mutexes with this type can be rather complicated.

Definition at line 59 of file mutex.h.

◆ pointer_t

cppthread::mutex::pointer_t

You can allocate mutexes as global variables, local variables, variable members and once in a while you may want to allocate them. In that case, we suggest that you use a shared pointer.

Definition at line 57 of file mutex.h.

◆ vector_t

cppthread::mutex::vector_t

This type defines a vector that can be used to manage mutexes. In this case, the mutexes must be allocated.

Definition at line 58 of file mutex.h.

Constructor & Destructor Documentation

◆ mutex()

cppthread::mutex::mutex ( )

The mutex object is used to lock part of the code that needs to be run by only one thread at a time. This is also called a critical section and a memory barrier.

In most cases one uses the guard object to temporarily lock the mutex using the FIFO to help ensure the mutex gets unlocked as required in the event an exception occurs.

{
   cppthread::guard lock(&my_mutex)
   ... // protected code
}

The lock can be tried to see whether another thread already has the lock and fail if so. See the try_lock() function.

The class also includes a condition in order to send signals and wait on signals. There are two ways to send signals and three ways to wait. Note that to call any one of the wait functions you must first have the mutex locked, what otherwise happens is undefined.

{
     // wake one waiting thread
     my_mutex.signal();
 
     // wake all the waiting thread
     my_mutex.broadcast();
 
     // wait on the signal forever
     {
         cppthread::guard lock(&my_mutex);
         my_mutex.wait();
     }
 
     // wait on the signal for the specified amount of time
     {
         cppthread::guard lock(&my_mutex);
         my_mutex.timed_wait(1000000UL); // wait up to 1 second
     }
 
     // wait on the signal for until date or later or the signal
     {
         cppthread::guard lock(&my_mutex);
         my_mutex.dated_wait(date); // wait on signal or until date
     }
}

If you need a FIFO of messages between your threads, look at the snap_fifo template.

Note: Care must be used to always initialized a mutex before it is possibly accessed by more than one thread. This is usually the case in the constructor of your objects.

Exceptions

cppthread_exception_invalid_error If any one of the initialization functions fails, this exception is raised. The function also logs the error.

Definition at line 229 of file mutex.cpp.

References cppthread::end(), f_impl, and cppthread::log.

Here is the call graph for this function:

◆ ~mutex()

cppthread::mutex::~mutex ( )

This function ensures that the mutex object is cleaned up, which means the mutex and conditions get destroyed.

This destructor verifies that the mutex is not currently locked. A locked mutex can't be destroyed. If still locked, then an error is sent to the logger and the function calls exit(1).

Definition at line 319 of file mutex.cpp.

References cppthread::end(), f_impl, f_reference_count, and cppthread::log.

Here is the call graph for this function:

Member Function Documentation

◆ broadcast()

void cppthread::mutex::broadcast ( )

Our mutexes include a condition that get signaled by calling this function. This function actually signals all the threads that are currently listening to the mutex signal. The order in which the threads get awaken is unspecified.

The function ensures that the mutex is locked before broadcasting the signal so you do not have to lock the mutex yourself.

Note: We also offer a safe_broadcast(). If you expect absolutely all the other threads to receive the signal, then make sure to use the safe_broadcast() function instead. However, if you are already in a guarded block, then there is no need for an additional lock and this function will work exactly as expected.

Exceptions

cppthread_exception_invalid_error If one of the pthread system functions return an error, the function raises this exception.

See also: safe_broadcast()

Definition at line 838 of file mutex.cpp.

References cppthread::end(), f_impl, lock(), and cppthread::log.

Referenced by cppthread::fifo< T >::done(), and cppthread::fifo< T >::pop_front().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dated_wait() [1/2]

bool cppthread::mutex::dated_wait ( std::uint64_t const usec )

This function waits on the mutex condition to be signaled up until the specified date is passed.

Warning: This function cannot be called if the mutex is not locked or the wait will fail in unpredictable ways.

Exceptions

cppthread_exception_mutex_failed_error This exception is raised whenever the thread wait function fails.

Parameters

[in] usec The date when the mutex times out in microseconds.

Returns: true if the condition occurs before the function times out, false if the function times out.

Definition at line 642 of file mutex.cpp.

References dated_wait().

Referenced by dated_wait().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dated_wait() [2/2]

bool cppthread::mutex::dated_wait ( timespec const & date )

This function waits on the mutex condition to be signaled up until the specified date is passed.

Warning: This function cannot be called if the mutex is not locked or the wait will fail in unpredictable ways.

Exceptions

cppthread_exception_mutex_failed_error This exception is raised whenever the thread wait function fails.

Parameters

[in] date The date when the mutex times out in nanoseconds.

Returns: true if the condition occurs before the function times out, false if the function times out.

Definition at line 668 of file mutex.cpp.

References cppthread::end(), f_impl, and cppthread::log.

Here is the call graph for this function:

◆ lock()

void cppthread::mutex::lock ( )

This function locks the mutex. The function waits until the mutex is available if it is not currently available. To avoid waiting one may want to use the try_lock() function instead.

Although the function cannot fail, the call can lock up a process if two or more mutexes are used and another thread is already waiting on this process.

Exceptions

cppthread_exception_invalid_error If the lock fails, this exception is raised.

Definition at line 369 of file mutex.cpp.

References cppthread::end(), f_impl, f_reference_count, and cppthread::log.

Referenced by cppthread::guard::guard(), broadcast(), cppthread::fifo< T >::byte_size(), cppthread::fifo< T >::clear(), cppthread::fifo< T >::done(), cppthread::fifo< T >::empty(), cppthread::fifo< T >::is_done(), cppthread::guard::is_locked(), cppthread::guard::lock(), cppthread::fifo< T >::pop_front(), cppthread::fifo< T >::push_back(), safe_broadcast(), safe_signal(), and cppthread::fifo< T >::size().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ safe_broadcast()

void cppthread::mutex::safe_broadcast ( )

Our mutexes include a condition that get signaled by calling this function. This function actually signals all the threads that are currently listening to the mutex signal. The order in which the threads get awaken is unspecified.

The function ensures that the mutex is locked before broadcasting the signal so you do not have to lock the mutex yourself. Note that is not required to lock a mutex before broadcasting a signal. The effects are similar.

Exceptions

cppthread_exception_invalid_error If one of the pthread system functions return an error, the function raises this exception.

See also: broadcast()

Definition at line 799 of file mutex.cpp.

References cppthread::end(), f_impl, lock(), and cppthread::log.

Here is the call graph for this function:

◆ safe_signal()

void cppthread::mutex::safe_signal ( )

Our mutexes include a condition that get signaled by calling this function. This function wakes up one listening thread.

The function ensures that the mutex is locked before sending the signal so you do not have to lock the mutex yourself.

Exceptions

cppthread_exception_invalid_error If one of the pthread system functions return an error, the function raises this exception.

See also: signal()

Definition at line 765 of file mutex.cpp.

References cppthread::end(), f_impl, lock(), and cppthread::log.

Here is the call graph for this function:

◆ signal()

void cppthread::mutex::signal ( )

Our mutexes include a condition that get signaled by calling this function. This function wakes up one or more listening threads.

The function does not lock the mutext before sending the signal. This is useful if you already are in a guarded block or you do not mind waking up more than one thread as a result of the call.

Note: If you need to wake up exactly one other thread, then make sure to use the safe_signal() function instead.

Exceptions

cppthread_exception_invalid_error If one of the pthread system functions return an error, the function raises this exception.

See also: safe_signal()

Definition at line 737 of file mutex.cpp.

References cppthread::end(), f_impl, and cppthread::log.

Referenced by cppthread::thread::internal_thread(), and cppthread::fifo< T >::push_back().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ timed_wait() [1/2]

bool cppthread::mutex::timed_wait ( std::uint64_t const usecs )

At times it is useful to wait on a mutex to become available without polling the mutex, but only for some time. This function waits for the number of specified micro seconds. The function returns early if the condition was triggered. Otherwise it waits until the specified number of micro seconds elapsed and then returns.

Warning: This function cannot be called if the mutex is not locked or the wait will fail in unpredictable ways.

Exceptions

cppthread_exception_system_error	This exception is raised if a function returns an unexpected error.
cppthread_exception_mutex_failed_error	This exception is raised when the mutex wait function fails.

Parameters

[in] usecs The maximum number of micro seconds to wait until you receive the signal.

Returns: true if the condition was raised, false if the wait timed out.

Definition at line 549 of file mutex.cpp.

References timed_wait().

Referenced by cppthread::fifo< T >::pop_front(), and timed_wait().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ timed_wait() [2/2]

bool cppthread::mutex::timed_wait ( timespec const & nsecs )

At times it is useful to wait on a mutex to become available without polling the mutex, but only for some time. This function waits for the number of specified nano seconds. The function returns early if the condition was triggered. Otherwise it waits until the specified number of nano seconds elapsed and then returns.

Warning: This function cannot be called if the mutex is not locked or the wait will fail in unpredictable ways.

Exceptions

cppthread_exception_system_error	This exception is raised if a function returns an unexpected error.
cppthread_exception_mutex_failed_error	This exception is raised when the mutex wait function fails.

Parameters

[in] nsecs The maximum number of nano seconds to wait until you receive the signal.

Returns: true if the condition was raised, false if the wait timed out.

See also: dated_wait(timespec date)

Definition at line 583 of file mutex.cpp.

References cppthread::end(), f_impl, and cppthread::log.

Here is the call graph for this function:

◆ try_lock()

bool cppthread::mutex::try_lock ( )

This function tries locking the mutex. If the mutex cannot be locked because another process already locked it, then the function returns immediately with false.

Exceptions

cppthread_exception_invalid_error If the lock fails, this exception is raised.

Returns: true if the lock succeeded, false otherwise.

Definition at line 400 of file mutex.cpp.

References cppthread::end(), f_impl, f_reference_count, and cppthread::log.

Here is the call graph for this function:

◆ unlock()

void cppthread::mutex::unlock ( )

This function unlock the specified mutex. The function must be called exactly once per call to the lock() function, or successful call to the try_lock() function.

The unlock never waits.

Exceptions

cppthread_exception_invalid_error	If the unlock fails, this exception is raised.
cppthread_exception_not_locked_error	If the function is called too many times, then the lock count is going to be zero and this exception will be raised.

Definition at line 443 of file mutex.cpp.

References cppthread::end(), f_impl, f_reference_count, and cppthread::log.

Referenced by cppthread::guard::is_locked(), cppthread::guard::lock(), and cppthread::guard::unlock().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wait()

void cppthread::mutex::wait ( )

At times it is useful to wait on a mutex to become available without polling the mutex (which uselessly wastes precious processing time.) This function can be used to wait on a mutex condition.

This version of the wait() blocks until a signal is received.

Warning: This function cannot be called if the mutex is not locked or the wait will fail in unpredictable ways.

Exceptions

cppthread_exception_not_locked_once_error	This exception is raised if the reference count is not exactly 1. In other words, the mutex must be locked by the caller but only one time.
cppthread_exception_mutex_failed_error	This exception is raised in the event the conditional wait fails.

Definition at line 494 of file mutex.cpp.

References cppthread::end(), f_impl, and cppthread::log.

Referenced by cppthread::fifo< T >::pop_front(), and cppthread::thread::start().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ f_impl

cppthread::mutex::f_impl

private

This variable member holds the actual pthread mutex. The mutex implementation manages this field as required.

Definition at line 82 of file mutex.h.

Referenced by mutex(), ~mutex(), broadcast(), dated_wait(), lock(), safe_broadcast(), safe_signal(), signal(), timed_wait(), try_lock(), unlock(), and wait().

◆ f_reference_count

cppthread::mutex::f_reference_count = 0

private

The mutex tracks the number of times the mutex gets locked. In the end, the lock reference must be zero for the mutex to be properly destroyed.

Definition at line 84 of file mutex.h.

Referenced by ~mutex(), lock(), try_lock(), and unlock().

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

/home/alexis/snapwebsites/snapcpp/contrib/cppthread/cppthread/mutex.h
/home/alexis/snapwebsites/snapcpp/contrib/cppthread/cppthread/mutex.cpp

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ direct_vector_t

◆ pointer_t

◆ vector_t

Constructor & Destructor Documentation

◆ mutex()

◆ ~mutex()

Member Function Documentation

◆ broadcast()

◆ dated_wait() [1/2]

◆ dated_wait() [2/2]

◆ lock()

◆ safe_broadcast()

◆ safe_signal()

◆ signal()

◆ timed_wait() [1/2]

◆ timed_wait() [2/2]

◆ try_lock()

◆ unlock()

◆ wait()

Member Data Documentation

◆ f_impl

◆ f_reference_count