Contents

MTLEvent

A type that synchronizes memory operations to one or more resources within a single Metal device.

Declaration

protocol MTLEvent : NSObjectProtocol, Sendable

Mentioned in

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 by calling the makeEvent() method of an 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 instance by calling its methods:

Similarly for Metal 3 and earlier, add wait and signal commands with an MTLCommandBuffer instance by calling its methods:

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.

You can add signal and wait commands to any combination of MTL4CommandQueue and 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.

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.

Topics

Identifying the event

See Also

Synchronizing with events