An execution agent is an entity such as a thread that may perform work in parallel with other execution agents. [ Note: Implementations or users may introduce other kinds of agents such as processes or thread-pool tasks. — end note ] The calling agent is determined by context, e.g. the calling thread that contains the call, and so on.
[ Note: Some lockable objects are “agent oblivious” in that they work for any execution agent model because they do not determine or store the agent's ID (e.g., an ordinary spin lock). — end note ]
The standard library templates unique_lock ([thread.lock.unique]), lock_guard ([thread.lock.guard]), lock, try_lock ([thread.lock.algorithm]), and condition_variable_any ([thread.condition.condvarany]) all operate on user-supplied lockable objects. The BasicLockable requirements, the Lockable requirements, and the TimedLockable requirements list the requirements imposed by these library types in order to acquire or release ownership of a lock by a given execution agent. [ Note: The nature of any lock ownership and any synchronization it may entail are not part of these requirements. — end note ]
A type L meets the BasicLockable requirements if the following expressions are well-formed and have the specified semantics (m denotes a value of type L).
m.lock()
Effects: Blocks until a lock can be acquired for the current execution agent. If an exception is thrown then a lock shall not have been acquired for the current execution agent.
m.unlock()
Requires: The current execution agent shall hold a lock on m.
Effects: Releases a lock on m held by the current execution agent.
Throws: Nothing.
A type L meets the Lockable requirements if it meets the BasicLockable requirements and the following expressions are well-formed and have the specified semantics (m denotes a value of type L).
m.try_lock()
Effects: attempts to acquire a lock for the current execution agent without blocking. If an exception is thrown then a lock shall not have been acquired for the current execution agent.
Return type: bool.
Returns: true if the lock was acquired, false otherwise.
A type L meets the TimedLockable requirements if it meets the Lockable requirements and the following expressions are well-formed and have the specified semantics (m denotes a value of type L, rel_time denotes a value of an instantiation of duration ([time.duration]), and abs_time denotes a value of an instantiation of time_point ([time.point])).
m.try_lock_for(rel_time)
Effects: attempts to acquire a lock for the current execution agent within the relative timeout ([thread.req.timing]) specified by rel_time. The function shall not return within the timeout specified by rel_time unless it has obtained a lock on m for the current execution agent. If an exception is thrown then a lock shall not have been acquired for the current execution agent.
Return type: bool.
Returns: true if the lock was acquired, false otherwise.
m.try_lock_until(abs_time)
Effects: attempts to acquire a lock for the current execution agent before the absolute timeout ([thread.req.timing]) specified by abs_time. The function shall not return before the timeout specified by abs_time unless it has obtained a lock on m for the current execution agent. If an exception is thrown then a lock shall not have been acquired for the current execution agent.
Return type: bool.
Returns: true if the lock was acquired, false otherwise.