---
title: MTLEvent
framework: metal
role: symbol
role_heading: Protocol
path: metal/mtlevent
---

# MTLEvent

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

## Declaration

```swift
protocol MTLEvent : NSObjectProtocol, Sendable
```

## Mentioned in

About synchronization events Synchronizing passes with a fence Understanding the Metal 4 core API

## Overview

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: waitForEvent(_:value:) signalEvent(_:value:) Similarly for Metal 3 and earlier, add wait and signal commands with an MTLCommandBuffer instance by calling its methods: encodeWaitForEvent(_:value:) 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. 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. important: Wait commands that time out in an MTL4CommandQueue unblock subsequent work in the queue, and wait commands that time out in an MTLCommandBuffer terminate the command buffer with the MTLCommandBufferError.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 Resource synchronization introduces.

## Topics

### Identifying the event

- [device](metal/mtlevent/device.md)
- [label](metal/mtlevent/label.md)

## Relationships

### Inherits From

- [NSObjectProtocol](objectivec/nsobjectprotocol.md)
- [Sendable](swift/sendable.md)
- [SendableMetatype](swift/sendablemetatype.md)

### Inherited By

- [MTLSharedEvent](metal/mtlsharedevent.md)

## See Also

### Synchronizing with events

- [Implementing a multistage image filter using heaps and events](metal/implementing-a-multistage-image-filter-using-heaps-and-events.md)
- [About synchronization events](metal/about-synchronization-events.md)
- [Synchronizing events within a single device](metal/synchronizing-events-within-a-single-device.md)
- [Synchronizing events across multiple devices or processes](metal/synchronizing-events-across-multiple-devices-or-processes.md)
- [Synchronizing events between a GPU and the CPU](metal/synchronizing-events-between-a-gpu-and-the-cpu.md)
- [MTLSharedEvent](metal/mtlsharedevent.md)
- [MTLSharedEventHandle](metal/mtlsharedeventhandle.md)
- [MTLSharedEventListener](metal/mtlsharedeventlistener.md)
- [MTLSharedEventNotificationBlock](metal/mtlsharedeventnotificationblock.md)