Events and Synchronization

As soon as you need to know if a tasks in a queue is already executed or you think about task parallelism you need events. This allows to describe dependencies between tasks in different queues without blocking the host thread. In alpaka, queues describe execution order, and events describe dependencies between queues.

Queue Rules

• Operations inside one queue execute in FIFO order.

• Different queues may run independently.

• onHost::wait(queue) waits until all work in that queue is complete.

• onHost::wait(event) waits until the event has been processed which means that all previous enqueues tasks are completed.

• queue1.waitFor(event) inserts a dependency so work in queue1 enqueued after starts only after the event is reached.

Use Cases

Multiple queues are primarily used in the following scenarios:

• Host and device queues: Run independent tasks on the host CPU and the device (e.g., a GPU) and synchronize both devices.

• Many queues for many devices: For example, in multi-GPU systems, each GPU requires its own queue.

• Many queues for a single device: Enables better utilization of a single device. The performance benefits depend on the API.

Creating and Using an Event

In the following example, we create two queues (queue0 and queue1). Both execute functions on the host via enqueueHostFn(). Without synchronization between the queues using events, a race condition is possible. It is possible that queue1 increments the value valueA before valueA is set to 41 in queue0.

// Create two queues on the same device.
onHost::Queue queue0 = device.makeQueue();
onHost::Queue queue1 = device.makeQueue();
int valueA = 0;
int valueB = 0;

// Create an event.
auto event = device.makeEvent();

queue0.enqueueHostFn([&valueA]() { valueA = 41; });
/* Enqueue an event to connect two queues without forcing the host to block between them.
Another queue can wait until this point is reached. */
queue0.enqueue(event);
queue0.enqueueHostFn([&valueB]() { valueB = 23; });

/* A task enqueued after the event will wait until the event is complete before it starts executing.
 * That does not mean that the followed calls are blocking, if a call is blocking the executor depends on the queue
 * kind.
 */
queue1.waitFor(event);
/* This operation is guaranteed to be called after valueA in queue0 is updated.
 * The update of valueB in queue0 can run in parallel to the additional increment of valueA in queue1.
 */
queue1.enqueueHostFn([&valueA]() { valueA += 1; });

onHost::wait(queue0);
onHost::wait(queue1);

// An enqueued event can be checked for completion. This is useful for example to check if a long-running task is
// finished.
CHECK(event.isComplete());

Complete Source File

160_events.cpp

/* Copyright 2026 René Widera
 * SPDX-License-Identifier: ISC
 */

#include "docsTest.hpp"

#include <alpaka/alpaka.hpp>

#include <catch2/catch_template_test_macros.hpp>
#include <catch2/catch_test_macros.hpp>

using namespace alpaka;

TEMPLATE_LIST_TEST_CASE("tutorial events and synchronization", "[docs]", docs::test::TestBackends)
{
    auto selector = onHost::makeDeviceSelector(TestType::makeDict()[object::deviceSpec]);
    if(!selector.isAvailable())
        return;
    onHost::concepts::Device auto device = selector.makeDevice(0);
    // Create two queues on the same device.
    onHost::Queue queue0 = device.makeQueue();
    onHost::Queue queue1 = device.makeQueue();
    int valueA = 0;
    int valueB = 0;

    // Create an event.
    auto event = device.makeEvent();

    queue0.enqueueHostFn([&valueA]() { valueA = 41; });
    /* Enqueue an event to connect two queues without forcing the host to block between them.
    Another queue can wait until this point is reached. */
    queue0.enqueue(event);
    queue0.enqueueHostFn([&valueB]() { valueB = 23; });

    /* A task enqueued after the event will wait until the event is complete before it starts executing.
     * That does not mean that the followed calls are blocking, if a call is blocking the executor depends on the queue
     * kind.
     */
    queue1.waitFor(event);
    /* This operation is guaranteed to be called after valueA in queue0 is updated.
     * The update of valueB in queue0 can run in parallel to the additional increment of valueA in queue1.
     */
    queue1.enqueueHostFn([&valueA]() { valueA += 1; });

    onHost::wait(queue0);
    onHost::wait(queue1);

    // An enqueued event can be checked for completion. This is useful for example to check if a long-running task is
    // finished.
    CHECK(event.isComplete());
    CHECK(valueA == 42);
    CHECK(valueB == 23);
}