Block the calling thread until an asio::awaitable completes. More...

#include <neograph/graph/cancel.h>
#include <asio/any_io_executor.hpp>
#include <asio/awaitable.hpp>
#include <asio/bind_cancellation_slot.hpp>
#include <asio/cancellation_signal.hpp>
#include <asio/co_spawn.hpp>
#include <asio/detached.hpp>
#include <asio/error.hpp>
#include <asio/io_context.hpp>
#include <asio/post.hpp>
#include <asio/query.hpp>
#include <asio/system_error.hpp>
#include <asio/thread_pool.hpp>
#include <asio/traits/static_query.hpp>
#include <atomic>
#include <condition_variable>
#include <cstddef>
#include <exception>
#include <mutex>
#include <optional>
#include <type_traits>
#include <utility>

Include dependency graph for run_sync.h:

Functions
bool	neograph::async::detail::on_serial_io_context (const asio::any_io_executor &executor) noexcept
	Whether `executor` runs on the private io_context of a blocking bridge on this thread (`run_sync`, `GraphEngine::run`).

template<typename T >
T	neograph::async::run_sync (asio::awaitable< T > aw, neograph::graph::CancelToken *cancel=nullptr)
	Run `aw` to completion on a fresh single-threaded io_context and return its result.

void	neograph::async::run_sync (asio::awaitable< void > aw, neograph::graph::CancelToken *cancel=nullptr)
	Void specialization — same semantics, no return value.

template<typename T >
T	neograph::async::run_sync_pool (asio::awaitable< T > aw, std::size_t n_threads)
	Run `aw` to completion on a fresh N-worker asio::thread_pool and return its result.

void	neograph::async::run_sync_pool (asio::awaitable< void > aw, std::size_t n_threads)
	Void specialization — same semantics, no return value.

const asio::execution_context *&	neograph::async::detail::serial_io_context () noexcept
	The io_context an engine run is currently driving on this thread through `run_sync_operation`, or null.

Detailed Description

Block the calling thread until an asio::awaitable completes.

Bridge utility for synchronous callers of owned coroutine operations. The Provider::dispatch() facade uses it to drain dispatch_async() while retaining the same prepared request and genuine SDK outcome.

The helper owns a private io_context for the duration of the call; it does not share the caller's executor. This is intentional — sharing would deadlock a single-threaded io_context that already sits inside run(). Cost: a tiny io_context construction per call. Fine for sync-facade use, not for hot loops.

run_sync_pool is the N-worker variant. The default run_sync drives a single-threaded io_context so asio::experimental:: make_parallel_group inside the awaitable serializes on one thread; the pool variant spreads those branches across workers so sync callers of a parallel-fan-out coroutine still get real CPU parallelism. Per-call pool spin-up is not free (one std::thread per worker), so engines with a hot super-step loop should own a long-lived executor instead of calling this per run().

Definition in file run_sync.h.

Function Documentation

◆ on_serial_io_context()

bool neograph::async::detail::on_serial_io_context ( const asio::any_io_executor & executor )

inlinenoexcept

Whether executor runs on the private io_context of a blocking bridge on this thread (run_sync, GraphEngine::run).

A coroutine there that waits for the host's event loop would wait for ever.

Definition at line 68 of file run_sync.h.

References neograph::async::detail::on_serial_io_context(), and neograph::async::detail::serial_io_context().

Referenced by neograph::async::detail::on_serial_io_context().

◆ run_sync()

template<typename T >

T neograph::async::run_sync	(	asio::awaitable< T >	aw,
		neograph::graph::CancelToken *	cancel = `nullptr`
	)

Run aw to completion on a fresh single-threaded io_context and return its result.

Any exception thrown inside the coroutine is rethrown on the caller's thread.

The awaitable should use co_await asio::this_coro::executor to obtain an executor for nested operations; that executor will be the temporary io_context created here.

When cancel is non-null, the wrapper binds its private execution child's slot. Parent cancellation cascades to that child; cleanup does not grant the child authority to cancel its parent. Provider dispatch supplies the explicit ProviderRequest::cancel_token; there is no ambient cancellation authority.

Executor-bound objects, tracked work and coroutines must remain inside this call's lifetime. Finite caller-thread stop handlers are drained; escaping the raw context to stop it from another thread is not supported. Completion alone is not scheduler quiescence: foreign posting tails and late cancellation notifications are drained before the private context is destroyed.

Definition at line 421 of file run_sync.h.

References neograph::async::run_sync().

Referenced by neograph::async::run_sync(), and neograph::async::run_sync().

◆ run_sync_pool()

template<typename T >

T neograph::async::run_sync_pool	(	asio::awaitable< T >	aw,
		std::size_t	n_threads
	)

Run aw to completion on a fresh N-worker asio::thread_pool and return its result.

Unlike run_sync, inner make_parallel_group branches execute on separate worker threads, so a sync caller of a parallel-fan-out coroutine still sees real CPU parallelism.

n_threads is clamped to at least 1. Pool construction spawns one std::thread per worker; cost is non-trivial for hot paths.

Definition at line 564 of file run_sync.h.

References neograph::async::run_sync_pool().

Referenced by neograph::async::run_sync_pool(), and neograph::async::run_sync_pool().

◆ serial_io_context()

const asio::execution_context *& neograph::async::detail::serial_io_context ( )

inlinenoexcept

The io_context an engine run is currently driving on this thread through run_sync_operation, or null.

That context is private to the call and is run by the calling thread alone, so every handler on it is already serialised. Fan-out code uses this to avoid wrapping each branch in a strand that cannot add any ordering. A foreign or unknown context never matches, which keeps the strand.

Definition at line 61 of file run_sync.h.

References neograph::async::detail::serial_io_context().