33 Thread support library [thread]

33.2 Requirements [thread.req]

33.2.5 Requirements for Lockable types [thread.req.lockable]

33.2.5.1 In general [thread.req.lockable.general]

1
#
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.
2
#
[ 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
 ]
3
#
The standard library templates unique_­lock ([thread.lock.unique]), shared_­lock ([thread.lock.shared]), scoped_­lock ([thread.lock.scoped]), 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
 ]

33.2.5.2 BasicLockable requirements [thread.req.lockable.basic]

1
#
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()
2
#
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()
3
#
Requires: The current execution agent shall hold a lock on m.
4
#
Effects: Releases a lock on m held by the current execution agent.
5
#
Throws: Nothing.

33.2.5.3 Lockable requirements [thread.req.lockable.req]

1
#
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()
2
#
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.
3
#
Return type: bool.
4
#
Returns: true if the lock was acquired, false otherwise.

33.2.5.4 TimedLockable requirements [thread.req.lockable.timed]

1
#
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)
2
#
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.
3
#
Return type: bool.
4
#
Returns: true if the lock was acquired, false otherwise.
m.try_lock_until(abs_time)
5
#
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.
6
#
Return type: bool.
7
#
Returns: true if the lock was acquired, false otherwise.