# MTLEvent A type that synchronizes memory operations to one or more resources within a single Metal device. ``` protocol MTLEvent : NSObjectProtocol, Sendable ``` ## Overview Each event represents an unsigned 64-bit integer that starts with a value of `0`, which can only increase over time. Create an [`MTLEvent`](/documentation/Metal/MTLEvent) by calling the [`makeEvent()`](/documentation/Metal/MTLDevice/makeEvent()) method of an [`MTLDevice`](/documentation/Metal/MTLDevice) instance. With an event, synchronize commands across a single Metal device by instructing it to wait before starting a workload, such as a compute pass, until another workload finishes. You do this by encoding signal and wait commands: - Add a signal command after encoding the producing workload that one or more other workloads depend on. - Add a wait command before encoding each consuming workload that depends on the producing workload. The Metal device begins running any dependent workloads when the event equals or exceeds the value that the wait command is waiting for. ### Synchronize one producing workload with an event When working with Metal 4 types, add wait and signal commands with an [`MTL4CommandQueue`](/documentation/Metal/MTL4CommandQueue) instance by calling its methods: - [`waitForEvent(_:value:)`](/documentation/Metal/MTL4CommandQueue/waitForEvent(_:value:)) - [`signalEvent(_:value:)`](/documentation/Metal/MTL4CommandQueue/signalEvent(_:value:)) Similarly for Metal 3 and earlier, add wait and signal commands with an [`MTLCommandBuffer`](/documentation/Metal/MTLCommandBuffer) instance by calling its methods: - [`encodeWaitForEvent(_:value:)`](/documentation/Metal/MTLCommandBuffer/encodeWaitForEvent(_:value:)) - [`encodeSignalEvent(_:value:)`](/documentation/Metal/MTLCommandBuffer/encodeSignalEvent(_:value:)) > Important: > You can signal an event only with a new value that’s greater than its current value. When a Metal device reaches a wait command, it compares the event’s current value to the command’s target value. The device proceeds to the subsequent commands only when another command updates the event with a value that’s equal to or greater than the target value. For an example that synchronizes workloads on different queues within the same device with a single event instance, see [Synchronizing events within a single device](/documentation/Metal/synchronizing-events-within-a-single-device). You can add signal and wait commands to any combination of [`MTL4CommandQueue`](/documentation/Metal/MTL4CommandQueue) and [`MTLCommandBuffer`](/documentation/Metal/MTLCommandBuffer) instances that all belong to the same Metal device. Even though you encode a wait command before the signal command that unblocks it, minimize the time between when they run because wait commands can time out. > Important: > Wait commands that time out in an ``doc://com.apple.metal/documentation/Metal/MTL4CommandQueue`` unblock subsequent work in the queue, > and wait commands that time out in an ``doc://com.apple.metal/documentation/Metal/MTLCommandBuffer`` terminate the command buffer > with the ``doc://com.apple.metal/documentation/Metal/MTLCommandBufferError-swift.struct/Code/timeout`` error code. One event signal can unblock multiple workloads waiting for it. For example, if workload A needs to run before starting workloads B and C, the B and C workloads can wait for one event to reach a specific value, such as `0x42`. When workload A finishes, the next command can unblock workloads B and C by signaling that event with the value `0x42` or greater. ### Synchronize multiple producing workloads with an event for each Multiple producing workloads can’t combine their signals with one event to unblock any dependent workloads. This is because an event’s signal method can only increase its value to a specific number, unlike a semaphore that can increment or decrement its current value by one. Instead, signal when each producing workload finishes by updating its own separate event. Dependent workloads can wait for the multiple events that correspond to the workloads they depend on. > Tip: For workloads with complicated dependency chains, consider other > access synchronization mechanisms that introduces. ## Topics ### Identifying the event [`device`](/documentation/Metal/MTLEvent/device) The device object that created the event. [`label`](/documentation/Metal/MTLEvent/label) A string that identifies the event. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)