How a Program store call is awaited, and how a synchronous caller waits for one (#556). More...

#include <neograph/api.h>
#include <neograph/program/blocking.h>
#include <asio/awaitable.hpp>
#include <asio/co_spawn.hpp>
#include <asio/io_context.hpp>
#include <asio/use_awaitable.hpp>
#include <exception>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>

Include dependency graph for store_call.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	neograph::program::detail::BlockingIoContext
	The private io_context of one blocking wait. More...

struct	neograph::program::BlockingStorePolicy
	When a `Blocking...Store` may wait for a store call that does not complete at once. More...

class	neograph::program::detail::InlineStoreCalls
	While one is alive on a thread, a `Sync...Store` completes its awaitable operations on that thread even when it offloads. More...

Functions
template<typename R >
R	neograph::program::detail::block_on_store (asio::awaitable< R > call, const BlockingStorePolicy &policy, std::string_view operation)
	Waits for `call` on a private io_context of the calling thread.

template<typename R >
asio::awaitable< R >	neograph::program::detail::failed_store_call (std::exception_ptr error)
	An awaitable that throws `error` when it is awaited: an operation the store does not support.

NEOGRAPH_API bool	neograph::async::in_host_turn () noexcept
	True while the calling thread is running a turn of a HostLoop (#556).

NEOGRAPH_PROGRAM_API bool	neograph::program::detail::offload_store_call (bool offloads) noexcept
	Whether a `Sync...Store` whose offloads() is `offloads` moves its next operation to the pool.

template<typename R , typename Fn >
asio::awaitable< R >	neograph::program::detail::offload_sync_call (Fn fn)
	Runs the synchronous operation `fn` on a thread of the bounded pool and resumes the awaiting coroutine on its own executor.

NEOGRAPH_PROGRAM_API asio::awaitable< void >	neograph::program::detail::offload_to_blocking_pool (std::function< void()> work)
	Runs `work` on a thread of a bounded pool and resumes the awaiting coroutine on its own executor.

void	neograph::program::detail::run_blocking_wait (BlockingIoContext &wait)
	Runs the context until its coroutine is done; a context whose loop threw is not reused.

template<typename R >
R	neograph::program::detail::run_to_completion (asio::awaitable< R > call, std::string_view operation)
	Runs `call` to completion on a private io_context of the calling thread, with InlineStoreCalls in force: the way the synchronous API runs the coroutine body it shares with its awaitable form.

Detailed Description

How a Program store call is awaited, and how a synchronous caller waits for one (#556).

The Program store interfaces return asio::awaitable. A store whose backend is synchronous (the in-memory store, SQLite, PostgreSQL) derives from the matching Sync...Store class, which implements the awaitable interface over the store's synchronous ..._sync operations: at once on the calling thread, or, for a backend that blocks for long, on a thread of a bounded pool. A caller that cannot suspend uses the matching Blocking...Store: it calls a synchronous store's operation directly, and otherwise drives the awaitable on a private io_context and waits for it, unless its policy says that waiting here would hang the thread that has to complete the call.

Definition in file store_call.h.

Function Documentation

◆ block_on_store()

template<typename R >

R neograph::program::detail::block_on_store	(	asio::awaitable< R >	call,
		const BlockingStorePolicy &	policy,
		std::string_view	operation
	)

Waits for call on a private io_context of the calling thread.

The wait ends when the call does: Asio keeps the context running for as long as the coroutine exists, so a store that completes only through another event loop would never end it. That wait is refused before the call starts (check_blocking_store_call), not detected afterwards.

Definition at line 163 of file store_call.h.

References neograph::program::detail::block_on_store(), neograph::program::detail::BlockingIoContext::discard(), and neograph::program::detail::run_blocking_wait().

Referenced by neograph::program::detail::block_on_store().

◆ 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.

◆ offload_sync_call()

template<typename R , typename Fn >

asio::awaitable< R > neograph::program::detail::offload_sync_call ( Fn fn )

Runs the synchronous operation fn on a thread of the bounded pool and resumes the awaiting coroutine on its own executor.

fn owns everything it needs, so the work stays valid if the awaiting coroutine is destroyed first.

Definition at line 109 of file store_call.h.

References neograph::program::detail::offload_sync_call(), and neograph::program::detail::offload_to_blocking_pool().

Referenced by neograph::program::detail::offload_sync_call().

◆ offload_to_blocking_pool()

NEOGRAPH_PROGRAM_API asio::awaitable< void > neograph::program::detail::offload_to_blocking_pool ( std::function< void()> work )

Runs work on a thread of a bounded pool and resumes the awaiting coroutine on its own executor.

The pool is the one that the checkpoint stores use for a synchronous backend. Throws SynchronousCheckpointStoreUnavailable in a build without threads.

References neograph::program::detail::offload_to_blocking_pool().

Referenced by neograph::program::detail::offload_sync_call(), and neograph::program::detail::offload_to_blocking_pool().

◆ run_to_completion()

template<typename R >

R neograph::program::detail::run_to_completion	(	asio::awaitable< R >	call,
		std::string_view	operation
	)

Runs call to completion on a private io_context of the calling thread, with InlineStoreCalls in force: the way the synchronous API runs the coroutine body it shares with its awaitable form.

Over stores that complete at once the coroutine never suspends. The caller decides beforehand whether waiting is allowed here (check_blocking_store_call): a store that completes only in a later turn of a host's event loop would never finish this wait.

Definition at line 212 of file store_call.h.

References neograph::program::detail::BlockingIoContext::discard(), neograph::program::detail::run_blocking_wait(), and neograph::program::detail::run_to_completion().

Referenced by neograph::program::detail::run_to_completion().

Classes