| # Vulkan Timeline Semaphores | |
| [Vulkan Timeline | |
| Semaphores](https://www.khronos.org/blog/vulkan-timeline-semaphores) are a | |
| synchronization primitive accessible both from the device and the host. A | |
| timeline semaphore represents a monotonically increasing 64-bit unsigned | |
| value. Whereas binary Vulkan semaphores are waited on just to become signaled, | |
| timeline semaphores are waited on to reach a specific value. Once a timeline | |
| semaphore reaches a certain value, it is considered signaled for every value | |
| less than or equal to that | |
| value. [`vkWaitSemaphores`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkWaitSemaphores.html) | |
| is used to wait for semaphores on the host. It can operate in one of two modes: | |
| "wait for all" and "wait for any". | |
| In SwiftShader, Vulkan Timeline Semaphores are implemented as an unsigned 64-bit | |
| integer protected by a mutex with changes signaled by a condition | |
| variable. Waiting for all timeline semaphores in a set is implemented by simply | |
| waiting for each of the semaphores in turn. Waiting for any semaphore in a set | |
| is a bit more complex. | |
| ## Wait for any semaphore | |
| A "wait for any" of a set of semaphores is represented by a | |
| `TimelineSemaphore::WaitForAny` object. Additionally, `TimelineSemaphore` | |
| contains an internal list of all `WaitForAny` objects that wait for it, as well | |
| as for which values they wait. When signaled, the timeline semaphore looks | |
| through this list and, in turn, signals any `WaitForAny` objects that are | |
| waiting for a value less than or equal to the timeline semaphore's new value. | |
| A `WaitForAny` object is created from a `VkSemaphoreWaitInfo`. During | |
| construction, it checks the value of each timeline semaphore provided against | |
| the value for which it is waiting. If it has not yet been reached, the wait | |
| object registers itself with the timeline semaphore. If it _has_ been reached, | |
| the wait object is immediately signaled and no further timeline semaphores are | |
| checked. | |
| Once a `WaitForAny` object is signaled, it remains signaled. There is no way to | |
| change what semaphores or values to wait for after construction. Any subsequent | |
| calls to `wait()` will return `VK_SUCCESS` immediately. | |
| When a `WaitForAny` object is destroyed, it unregisters itself from every | |
| `TimelineSemaphore` it was waiting for. It is expected that the number of | |
| concurrent waits are few, and that the wait objects are short-lived, so there | |
| should not be a build-up of wait objects in any timeline semaphore. |