await — the readiness plane (L4 graph)

The third data call. await blocks until the vertex’s value is assigned again, or until the deadline expires. It is single-shot and lives wholly in the state plane: it observes assigns at its own vertex and takes no part in propagation (reference 02 §Assign, propagate, and the coalescing sweep). The mental model is epoll on one identity — read/write are the data plane, :field writes the control plane, await the readiness plane, all on one vertex (CONTEXT.md §Field-write).

What to notice

• await is not subtree-scoped. A subscription observes its vertex and every descendant (vertical bubbling, RFC-0005); await does not. The example writes a descendant first and the waiter stays parked — the write to the vertex itself is what wakes it.

• A timeout is a distinct answer. The second await expires and returns TIMEOUT, which is what lets a consumer distinguish a quiet vertex from a delivered value. An await carrying a :field selector is refused outright (SCHEMA_NOT_FOUND) rather than silently giving a whole-vertex wakeup — not exercised here, see reference 02 §Owner-declared application fields.

• Ordering is the caller’s. The example sleeps 50 ms to let the waiter park, then join()s after the write, so every wake is complete and visible when the checks run. There is no stated ordering between a registration and a concurrent operation on the same address (reference 02 §Registration racing a concurrent operation) — a caller that needs one orders it itself.

Source

/*
 * SPDX-License-Identifier: Apache-2.0
 * SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC
 */

/**
 * @file
 * @brief ONE CONCEPT — the readiness plane: `await` blocks until the next store here.
 *
 * `await` is the third of the three data calls (`CONTEXT.md` §read / write / await). It is
 * single-shot and lives wholly in the state plane: it observes assigns AT ITS OWN VERTEX and
 * is not subtree-scoped, so a write to a descendant does not wake it
 * (`docs/reference/02-graph-model.md` §Assign, propagate). A deadline that expires answers
 * `TIMEOUT`, which is why a consumer can tell a quiet vertex from a delivered value.
 *
 * Runs under ctest as `example_graph_await`; returns non-zero on any failed check.
 */

#include <chrono>
#include <cstdio>
#include <cstring>
#include <span>
#include <string_view>
#include <thread>

#include "libtracer/tracer.hpp"

namespace {

using namespace std::chrono_literals;
using tr::graph::path_t;
using tr::graph::role_t;
using tr::graph::status_t;

/** @brief An owned one-segment view over @p text. */
tr::view::view_t value_of(std::string_view text) {
    return *tr::view::over_bytes(std::as_bytes(std::span<const char>(text.data(), text.size())));
}

/** @brief Report expectation @p what and record a failure on @p ok. */
void check(bool& ok, bool cond, const char* what) {
    std::printf("  [%s] %s\n", cond ? "ok" : "FAIL", what);
    ok = ok && cond;
}

}  // namespace

int main() {
    tr::graph::graph_t g;
    bool ok = true;

    const auto temp = g.register_vertex(path_t("/sensor/temp"), role_t::STORED_VALUE);
    const auto child = g.register_vertex(path_t("/sensor/temp/raw"), role_t::STORED_VALUE);

    // A waiter parks in await(); the writer wakes it with the value it stored.
    bool woke = false;
    std::thread waiter([&] {
        const auto r = g.await(temp, 2s);
        woke = r && (*r)->only().bytes().size() == 5;
    });
    std::this_thread::sleep_for(50ms);  // let the waiter park before the write lands

    (void)g.write(child, value_of("noise"));  // a DESCENDANT write — not this vertex
    (void)g.write(temp, value_of("21.5C"));
    waiter.join();
    check(ok, woke, "await returns the value assigned at its own vertex");

    // await is not subtree-scoped, and the deadline is honoured: nothing writes /sensor/temp
    // again, so this one expires rather than picking up the descendant write above.
    const auto quiet = g.await(temp, 20ms);
    check(ok, !quiet && quiet.error() == status_t::TIMEOUT, "an expired deadline answers TIMEOUT");
    std::printf("await woke once and timed out once, as expected\n");
    return ok ? 0 : 1;
}

See also: graph module · in-process pub/sub (the same primitive alongside subscriptions) · concurrency and scaling.