hpx::mutex, hpx::timed_mutex#

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

class mutex#

#include <mutex.hpp>

mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. mutex offers exclusive, non-recursive ownership semantics:

A calling thread owns a mutex from the time that it successfully calls either lock or try_lock until it calls unlock.
When a thread owns a mutex, all other threads will block (for calls to lock) or receive a false return value (for try_lock) if they attempt to claim ownership of the mutex.
A calling thread must not own the mutex prior to calling lock or try_lock.

The behavior of a program is undefined if a mutex is destroyed while still owned by any threads, or a thread terminates while owning a mutex. The mutex class satisfies all requirements of Mutex and StandardLayoutType.

hpx::mutex is neither copyable nor movable.

Subclassed by hpx::timed_mutex

Public Functions

HPX_NON_COPYABLE(mutex)#: hpx::mutex is neither copyable nor movable

inline HPX_HOST_DEVICE_CONSTEXPR mutex(char const*const = "") noexcept#

Constructs the mutex. The mutex is in unlocked state after the constructor completes.

Note

Because the default constructor is constexpr, static mutexes are initialized as part of static non-local initialization, before any dynamic non-local initialization begins. This makes it safe to lock a mutex in a constructor of any static object.

Parameters: description – description of the mutex.

~mutex()#: Destroys the mutex. The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex.

void lock(char const *description, error_code &ec = throws)#

Locks the mutex. If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired. If lock is called by a thread that already owns the mutex, the behavior is undefined: for example, the program may deadlock. hpx::mutex can detect the invalid usage and throws a std::system_error with error condition resource_deadlock_would_occur instead of deadlocking. Prior unlock() operations on the same mutex synchronize- with (as defined in std::memory_order) this operation.

Note

lock() is usually not called directly: std::unique_lock, std::scoped_lock, and std::lock_guard are used to manage exclusive locking.

Parameters

description – Description of the mutex
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

void lock returns void.

inline void lock(error_code &ec = throws)#

Locks the mutex. If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired. If lock is called by a thread that already owns the mutex, the behavior is undefined: for example, the program may deadlock. hpx::mutex can detect the invalid usage and throws a std::system_error with error condition resource_deadlock_would_occur instead of deadlocking. Prior unlock() operations on the same mutex synchronize - with(as defined in std::memory_order) this operation.

Note

lock() is usually not called directly: std::unique_lock, std::scoped_lock, and std::lock_guard are used to manage exclusive locking. This overload essentially calls void lock(char const* description, error_code& ec =throws); with description as mutex::lock.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: void lock returns void.

bool try_lock(char const *description, error_code &ec = throws)#

Tries to lock the mutex. Returns immediately. On successful lock acquisition returns true, otherwise returns false. This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread. If try_lock is called by a thread that already owns the mutex, the behavior is undefined. Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. Note that prior lock() does not synchronize with this operation if it returns false.

Parameters

description – Description of the mutex
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool try_lock returns true on successful lock acquisition, otherwise returns false.

inline bool try_lock(error_code &ec = throws)#

Note

This overload essentially calls

void try_lock(char const* description,
              error_code& ec = throws);

with description as mutex::try_lock.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: bool try_lock returns true on successful lock acquisition, otherwise returns false.

void unlock(error_code &ec = throws)#

Unlocks the mutex. The mutex must be locked by the current thread of execution, otherwise, the behavior is undefined. This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same mutex.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: unlock returns void.

class timed_mutex : private hpx::mutex #

#include <mutex.hpp>

The timed_mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. In a manner similar to mutex, timed_mutex offers exclusive, non-recursive ownership semantics. In addition, timed_mutex provides the ability to attempt to claim ownership of a timed_mutex with a timeout via the member functions try_lock_for() and try_lock_until(). The timed_mutex class satisfies all requirements of TimedMutex and StandardLayoutType.

hpx::timed_mutex is neither copyable nor movable.

Public Functions

HPX_NON_COPYABLE(timed_mutex)#: hpx::timed_mutex is neither copyable nor movable

timed_mutex(char const *const description = "")#

Constructs a timed_mutex. The mutex is in unlocked state after the call.

Parameters: description – Description of the timed_mutex.

~timed_mutex()#: Destroys the timed_mutex. The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex.

bool try_lock_until(hpx::chrono::steady_time_point const &abs_time, char const *description, error_code &ec = throws)#

Tries to lock the mutex. Blocks until specified abs_time has been reached or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false. If abs_time has already passed, this function behaves like try_lock(). As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point before abs_time. Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. If try_lock_until is called by a thread that already owns the mutex, the behavior is undefined.

Parameters

abs_time – time point to block until
description – Description of the timed_mutex
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool try_lock_until returns true if the lock was acquired successfully, otherwise false.

inline bool try_lock_until(hpx::chrono::steady_time_point const &abs_time, error_code &ec = throws)#

Note

This overload essentially calls

bool try_lock_until(
  hpx::chrono::steady_time_point const& abs_time,
  char const* description, error_code& ec = throws);

with description as mutex::try_lock_until.

Parameters

abs_time – time point to block until
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool try_lock_until returns true if the lock was acquired successfully, otherwise false.

inline bool try_lock_for(hpx::chrono::steady_duration const &rel_time, char const *description, error_code &ec = throws)#

Tries to lock the mutex. Blocks until specified rel_time has elapsed or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false. If rel_time is less or equal rel_time.zero(), the function behaves like try_lock(). This function may block for longer than rel_time due to scheduling or resource contention delays. As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point during rel_time. Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. If try_lock_for is called by a thread that already owns the mutex, the behavior is undefined.

Parameters

rel_time – minimum duration to block for
description – Description of the timed_mutex
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool try_lock_for returns true if the lock was acquired successfully, otherwise false.

inline bool try_lock_for(hpx::chrono::steady_duration const &rel_time, error_code &ec = throws)#

Note

This overload essentially calls

bool try_lock_for(
    hpx::chrono::steady_duration const& rel_time,
    char const* description, error_code& ec = throws)

with description as mutex::try_lock_for.

Parameters

rel_time – minimum duration to block for
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool try_lock_for returns true if the lock was acquired successfully, otherwise false.

void lock(char const *description, error_code &ec = throws)#

Note

lock() is usually not called directly: std::unique_lock, std::scoped_lock, and std::lock_guard are used to manage exclusive locking.

Parameters

description – Description of the mutex
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

void lock returns void.

inline void lock(error_code &ec = throws)#

Locks the mutex. If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired. If lock is called by a thread that already owns the mutex, the behavior is undefined: for example, the program may deadlock. hpx::mutex can detect the invalid usage and throws a std::system_error with error condition resource_deadlock_would_occur instead of deadlocking. Prior unlock() operations on the same mutex synchronize - with(as defined in std::memory_order) this operation.

Note

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: void lock returns void.

bool try_lock(char const *description, error_code &ec = throws)#

Parameters

description – Description of the mutex
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool try_lock returns true on successful lock acquisition, otherwise returns false.

inline bool try_lock(error_code &ec = throws)#

Note

This overload essentially calls

void try_lock(char const* description,
              error_code& ec = throws);

with description as mutex::try_lock.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: bool try_lock returns true on successful lock acquisition, otherwise returns false.

void unlock(error_code &ec = throws)#

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: unlock returns void.

namespace lcos

namespace local

namespace threads

Typedefs

using thread_id_ref_type = thread_id_ref #

using thread_self = coroutines::detail::coroutine_self#

Functions

thread_id get_self_id() noexcept#: The function get_self_id returns the HPX thread id of the current thread (or zero if the current thread is not a HPX thread).

thread_self *get_self_ptr() noexcept#: The function get_self_ptr returns a pointer to the (OS thread specific) self reference to the current HPX thread.

HPX master documentation

hpx::mutex, hpx::timed_mutex

hpx::mutex, hpx::timed_mutex#