Protocol

MTLEvent

An object you use to synchronize access to Metal resources.

Declaration

@protocol MTLEvent

Overview

Don’t implement this protocol yourself; instead, to create a MTLEvent object, call the newEvent method of a MTLDevice object. A basic event object that this method creates can be used to synchronize commands executing on a single Metal device.

An event is represented by a monotonically increasing unsigned 64-bit integer. An event starts with a value of 0. To signal a change to the event, call encodeSignalEvent:value: on a command buffer, passing in the new value for this event. The new value should be larger than previous changes to the event. Metal signals the event after all scheduled commands prior to the event have finished, updating the event's value if the new value is larger than its current value.

To wait for an event to be signaled, call encodeWaitForEvent:value: on a command buffer, passing in the value for which to wait. When the device object executes the command buffer and reaches this wait command, it compares the event's current value to the value you passed in. If the event's current value is less than the value you passed in, the device object will not start any new commands until the event is updated to a value equal to or greater than the value you requested.

You can encode signalling and waiting on events into different command buffers, even command buffers executing on two different command queues for the same device. You can also encode these commands independently of each other, meaning, for example, that you can wait on signals you haven't encoded yet.

For more information, see Synchronizing Events Within a Single Device.

Topics

Identifying the Event

device

The device object that created the event.

Required.

label

A string that identifies the event.

Required.

Relationships

Inherits From

Inherited By

See Also

Events

About Synchronization Events

Synchronize access to resources in your app by signaling events.

Synchronizing Events Within a Single Device

Use nonshareable events to synchronize your app’s work within a single device.

Synchronizing Events Across Multiple Devices

Use shareable events to synchronize your app’s work across multiple devices.

Synchronizing Events Between a GPU and the CPU

Use shareable events to synchronize your app's work between a GPU and the CPU.

Image Filter Graph with Heaps and Events

Demonstrates how to use heaps and events to optimize a multistage image filter.

MTLSharedEvent

An object you use to synchronize access to Metal resources across multiple CPUs, GPUs, and processes.

MTLSharedEventListener

A listener for shareable event notifications.

MTLSharedEventHandle

An object you use to recreate a shareable event.