Synchronization

onAcc::syncBlockThreads is the basic in-kernel synchronization primitive. It is a thread block barrier: every participating thread in the same thread block waits until the others reach the same point, and only then do they continue.

This is the primitive you need when one phase of a kernel produces data that a later phase in the same block will consume. The most common reason is block-local reuse, such as loading a chunk/tile once and then letting other threads read from it.

What syncBlockThreads Means

• It synchronizes threads inside a thread block.

• It does not synchronize different blocks with one another.

• It is a thread barrier, not just a memory-ordering hint.

• It is usually paired with shared memory, but the important concept is the collective phase boundary between “write” and “read”.

• It must be guaranteed that every thread in the block reaches the same barrier, otherwise the behavior is undefined.

If you only need memory ordering without a blocking thread barrier, check Memory Fences.

Chunk Reuse Example

The next kernel loads one data chunk into thread block-local shared memory, synchronizes the block, and then lets every thread read its own value together with the next neighbor. The key idea is the reuse pattern: one phase fills the chunk, the next phase consumes it. Without the synchronization point, those neighbor reads could race with threads that are still writing the chunk.

struct NeighborReuseKernel
{
    ALPAKA_FN_ACC void operator()(
        onAcc::concepts::Acc auto const& acc,
        concepts::IMdSpan auto out,
        concepts::IDataSource auto const& in,
        concepts::CVector auto chunkExtents) const
    {
        auto chunk = onAcc::declareSharedMdArray<int, uniqueId()>(acc, chunkExtents);

        /* Iterate in chunks over the output data.
         * It is assumed that the input data have at least the extents of the output.
         */
        for(auto chunkOffset : onAcc::makeIdxMap(
                acc,
                onAcc::worker::blocksInGrid,
                IdxRange{Vec{0u}, static_cast<uint32_t>(out.getExtents().x()), chunkExtents}))
        {
            // fill the shared data chunk
            for(auto idx : onAcc::makeIdxMap(acc, onAcc::worker::threadsInBlock, IdxRange{chunkExtents}))
                chunk[idx] = in[chunkOffset + idx];

            onAcc::syncBlockThreads(acc);

            for(auto idx : onAcc::makeIdxMap(acc, onAcc::worker::threadsInBlock, IdxRange{chunkExtents}))
            {
                auto neighborIdx = (idx.x() + 1u) % chunkExtents;
                out[chunkOffset + idx] = chunk[idx] + chunk[neighborIdx];
            }

            // avoid data race with the next loop iteration
            onAcc::syncBlockThreads(acc);
        }
    }
};

Practical Advice

• Place the barrier after the last write that other threads must see and before the first dependent read.

• Use synchronization to separate phases, not to “be safe” everywhere, else you will get a very slow kernel.

• If one thread block reuses the same shared memory again, e.g. in loops, add another barrier before overwriting data that other threads may still read.

Complete Source File

110_synchronization.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>

#include <numeric>
#include <vector>

using namespace alpaka;

struct NeighborReuseKernel
{
    ALPAKA_FN_ACC void operator()(
        onAcc::concepts::Acc auto const& acc,
        concepts::IMdSpan auto out,
        concepts::IDataSource auto const& in,
        concepts::CVector auto chunkExtents) const
    {
        auto chunk = onAcc::declareSharedMdArray<int, uniqueId()>(acc, chunkExtents);

        /* Iterate in chunks over the output data.
         * It is assumed that the input data have at least the extents of the output.
         */
        for(auto chunkOffset : onAcc::makeIdxMap(
                acc,
                onAcc::worker::blocksInGrid,
                IdxRange{Vec{0u}, static_cast<uint32_t>(out.getExtents().x()), chunkExtents}))
        {
            // fill the shared data chunk
            for(auto idx : onAcc::makeIdxMap(acc, onAcc::worker::threadsInBlock, IdxRange{chunkExtents}))
                chunk[idx] = in[chunkOffset + idx];

            onAcc::syncBlockThreads(acc);

            for(auto idx : onAcc::makeIdxMap(acc, onAcc::worker::threadsInBlock, IdxRange{chunkExtents}))
            {
                auto neighborIdx = (idx.x() + 1u) % chunkExtents;
                out[chunkOffset + idx] = chunk[idx] + chunk[neighborIdx];
            }

            // avoid data race with the next loop iteration
            onAcc::syncBlockThreads(acc);
        }
    }
};


TEMPLATE_LIST_TEST_CASE("tutorial in-kernel synchronization", "[docs]", docs::test::TestBackends)
{
    auto selector = onHost::makeDeviceSelector(TestType::makeDict());
    if(!selector.isAvailable())
        return;
    onHost::concepts::Device auto device = selector.makeDevice(0);
    onHost::Queue queue = device.makeQueue(queueKind::blocking);

    uint32_t dataExtent = 16u;
    std::vector<int> hostInput(dataExtent);
    std::iota(hostInput.begin(), hostInput.end(), 0);
    std::vector<int> hostOutput(dataExtent);

    auto inputBuffer = onHost::allocLike(device, hostInput);
    auto outputBuffer = onHost::allocLike(device, hostInput);

    onHost::memcpy(queue, inputBuffer, hostInput);

    constexpr uint32_t chunkSize = 8u;
    auto chunkExtents = CVec<uint32_t, chunkSize>{};
    onHost::concepts::FrameSpec auto frameSpec
        = onHost::FrameSpec{alpaka::divCeil(dataExtent, chunkSize), chunkExtents};
    queue.enqueue(frameSpec, KernelBundle{NeighborReuseKernel{}, outputBuffer, inputBuffer, chunkExtents});

    onHost::memcpy(queue, hostOutput, outputBuffer);
    onHost::wait(queue);

    for(size_t i = 0; i < dataExtent; ++i)
    {
        uint32_t blockOffset = i / chunkSize * chunkSize;
        CHECK(hostOutput[i] == static_cast<int>(blockOffset + i + ((i + 1) % chunkSize)));
    }
}