host_loop.h File Reference

Runs coroutines on an Asio io_context that a host's own event loop pumps (#535). More...

#include <neograph/api.h>
#include <runtime/host.h>
#include <asio/any_io_executor.hpp>
#include <asio/awaitable.hpp>
#include <asio/co_spawn.hpp>
#include <asio/execution_context.hpp>
#include <asio/io_context.hpp>
#include <asio/prefer.hpp>
#include <asio/query.hpp>
#include <asio/require.hpp>
#include <chrono>
#include <cstddef>
#include <exception>
#include <functional>
#include <memory>
#include <type_traits>
#include <utility>

Include dependency graph for host_loop.h:

Go to the source code of this file.

Classes
class	neograph::async::detail::PumpedExecutor< Executor >
	The io_context's executor, plus a turn of the loop whenever work is executed on it. More...

Functions
NEOGRAPH_API void	neograph::async::forget_deadline (const asio::any_io_executor &executor, std::chrono::steady_clock::time_point at) noexcept
	Takes back one note_deadline for at, once the Asio timer it was for is cancelled, so that the loop does not keep a host timer armed for a deadline nothing waits for.
NEOGRAPH_API void	neograph::async::detail::host_loop_wake (HostLoopCore *core) noexcept
	Schedules a turn of the loop. Does nothing once the loop is closed.
NEOGRAPH_API bool	neograph::async::in_host_turn () noexcept
	True while the calling thread is running a turn of a HostLoop (#556).
NEOGRAPH_API bool	neograph::async::is_host_pumped (const asio::any_io_executor &executor) noexcept
	True when executor is run by a HostLoop, including an executor derived from it (a strand of it, or one with other properties).
NEOGRAPH_API void	neograph::async::note_deadline (const asio::any_io_executor &executor, std::chrono::steady_clock::time_point at) noexcept
	Tells the loop that runs executor about an Asio timer that expires at at, so that a turn is scheduled then.

Detailed Description

Runs coroutines on an Asio io_context that a host's own event loop pumps (#535).

A WebAssembly host (a browser, a Worker, Node) owns the thread. NeoGraph cannot block it, and nothing in it can block, so the engine's io_context is run in short turns that the host schedules: a turn runs the handlers that are ready and returns. HostLoop schedules those turns on a SchemaProvider host executor (sp::runtime::Executor, the interface a Client runs on), the same seam that the SDK's own work goes through. The SDK's tasks and the engine's turns are then all tasks of the host's event loop.

A turn is scheduled when:

• work is posted to executor(), whether by spawn, by a cancellation, or by the SDK completing a call that a coroutine awaits (the completion posts the coroutine's continuation);
• a deadline noted with wake_at or note_deadline arrives, for an Asio timer that the loop cannot see. It is never scheduled while the loop has nothing to do, so an idle loop costs the host nothing.

The loop runs no thread and calls no blocking function. A synchronous entry point (GraphEngine::run, Provider::dispatch) drives a private io_context to completion and would wait for work that only the host can do; when it reaches a provider on a host-pumped executor it fails with the SDK's runtime.blocking.host_pumped refusal instead. Use the _async forms on a HostLoop.

HostLoop is not thread-safe. Create it, use executor() and destroy it on the host's thread.

Definition in file host_loop.h.

Function Documentation

forget_deadline()

NEOGRAPH_API void neograph::async::forget_deadline ( const asio::any_io_executor &  executor, std::chrono::steady_clock::time_point  at  )

noexcept

Takes back one note_deadline for at, once the Asio timer it was for is cancelled, so that the loop does not keep a host timer armed for a deadline nothing waits for.

Does nothing for an executor that no HostLoop runs.

in_host_turn()

NEOGRAPH_API bool neograph::async::in_host_turn ( )

noexcept

True while the calling thread is running a turn of a HostLoop (#556).

Declared in <neograph/async/host_loop.h>.

Code there that blocks its thread waits for work that only a later turn can do, and that turn cannot start until this one returns.

is_host_pumped()

NEOGRAPH_API bool neograph::async::is_host_pumped ( const asio::any_io_executor &  executor )

noexcept

True when executor is run by a HostLoop, including an executor derived from it (a strand of it, or one with other properties).

Nothing that waits for work on such an executor can finish: only the host's own turn runs it.

note_deadline()

NEOGRAPH_API void neograph::async::note_deadline ( const asio::any_io_executor &  executor, std::chrono::steady_clock::time_point  at  )

noexcept

Tells the loop that runs executor about an Asio timer that expires at at, so that a turn is scheduled then.

A timer cannot do that itself: the host's loop does not see Asio's timer queue. Does nothing for an executor that no HostLoop runs. Code that waits on an Asio timer under a HostLoop calls it, as the engine's own waits do. A turn can run before Asio dispatches the timer, because the host's clock runs ahead of Asio's or Asio learns that the timer is due from a thread of its own; the loop then looks again shortly, until Asio has dispatched it.