# addScheduledHandler(_:) Registers a completion handler the GPU device calls immediately after it schedules the command buffer to run on the GPU. ``` func addScheduledHandler(_ block: @escaping MTLCommandBufferHandler) ``` ## Parameters `block` A Swift closure or an Objective-C block that Metal calls after it schedules the command buffer to run on the GPU. ## Discussion You can register one or more scheduling completion handlers for the same command buffer. The GPU device’s driver (on the CPU) calls the completion handlers after it finishes scheduling the command buffer to run on the GPU. > Important: > You can only call this method before calling the command buffer’s ``doc://com.apple.metal/documentation/Metal/MTLCommandBuffer/commit()`` method. The GPU device schedules each command buffer — along with tasks from other command buffers — after it identifies the command buffer’s dependencies. At that time, the GPU device sets the command buffer’s status to [`MTLCommandBufferStatus.scheduled`](/documentation/Metal/MTLCommandBufferStatus/scheduled) and calls your completion handler. > Note: > The command buffer’s ``doc://com.apple.metal/documentation/Metal/MTLCommandBuffer/status`` property may be equal to another (larger) value by the time your completion handler runs, including ``doc://com.apple.metal/documentation/Metal/MTLCommandBufferStatus/completed``. You can use the command buffer’s [`kernelEndTime`](/documentation/Metal/MTLCommandBuffer/kernelEndTime) and [`kernelStartTime`](/documentation/Metal/MTLCommandBuffer/kernelStartTime) properties to calculate how much time the CPU spends scheduling the command buffer. ```swift commandBuffer.addScheduledHandler { commandBuffer in let start = commandBuffer.kernelStartTime let end = commandBuffer.kernelEndTime let scheduleDuration = end - start /* ... */ } ``` --- 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)