morph::reactive::Query< A, R > Class Template Reference

A derived async resource: the result of fetching whatever its tracked key names. More...

#include <control.hpp>

Inheritance diagram for morph::reactive::Query< A, R >:

Public Types
using	Key = std::function<std::optional<A>()>
	The tracked key: which request the query currently stands for, or nullopt for none.
using	Fetch = std::function<async::Completion<R>(A const&)>
	Issues one request.

Public Member Functions
	Query (Runtime &runtime, Fetch fetch, Key key, QueryOptions options={})
	Builds a query over any fetcher — the test seam, and the way to query a non-bridge source.
template<typename M, typename S>
	Query (Runtime &runtime, bridge::BridgeHandler< M, S > &handler, Key key, QueryOptions options={})
	Builds a query that fetches through a bridge handler.
	~Query () override
	Clears the query's invalidation link, so no mutation refetches it any more, and cancels what it has in flight.
	Query (Query const &)=delete
Query &	operator= (Query const &)=delete
	Query (Query &&)=delete
Query &	operator= (Query &&)=delete
bool	pending () const
	Whether a request for the current key is in flight. Tracked.
std::optional< R > const &	value () const
	The last successful result. Tracked.
std::exception_ptr	error () const
	The last failure. Tracked.
void	refetch () override
	Re-issues the current key under a new generation, ending a debounce wait; idle stays idle. Refused, and reported, off the Runtime's owner (detail::site::kOffOwner) and inside a Computed's computation (detail::site::kIssueInComputed); nothing is issued then.
std::shared_ptr< InvalidationLink >	link () const
	This query's link, for MutationOptions::invalidates.
template<typename Pub, typename M, typename S>
void	refreshOn (bridge::BridgeHandler< M, S > &handler)
	Re-fetches whenever the bridge publishes a Pub on handler's instance.
Public Member Functions inherited from morph::reactive::Refetchable
	Refetchable (Refetchable const &)=delete
Refetchable &	operator= (Refetchable const &)=delete
	Refetchable (Refetchable &&)=delete
Refetchable &	operator= (Refetchable &&)=delete

Detailed Description

template<typename A, typename R = typename model::ActionTraits<A>::Result>
class morph::reactive::Query< A, R >

A derived async resource: the result of fetching whatever its tracked key names.

An internal Effect reads key. When the key changes — equality-gated when == is usable for A (kEqualityUsable), otherwise on every re-run — the query fetches it under a fresh generation of its CallbackScope, so a reply for a superseded key is dropped (latest wins) and a call that carries a stop source (a bridge call whose handler returns a Task) is asked to stop. Destroying the query does the same to the call in flight. nullopt means idle: nothing in flight, value and error cleared. value() is kept while a refetch or a new key is in flight. A failure clears it when the call was for a different key than the one value() was fetched for, so a view never shows one key's result beside another key's failure; a failed refetch of the same key keeps it. Without == on A, every re-run of the key counts as a different key.

With QueryOptions::refreshEvery, the query re-fetches its current key one period after each call is issued, whatever issued it: a key change, refetch(), an invalidation, or the timer itself. A tick that finds a call in flight issues nothing and waits another period, so a timed refresh never supersedes a call and a fetch slower than the period still delivers. While idle no timer runs. A tick off the Runtime's owner is reported (detail::site::kOffOwner) and refused, and the timer then stays stopped until the next call is issued. Destroying the query cancels the timer, and a tick that arrives afterwards is dropped.

The fetcher runs untracked, whoever issues the call: a refetch() from inside an Effect does not subscribe that Effect to what the fetcher reads. refetch() inside a Computed's computation is reported (detail::site::kIssueInComputed) and refused before anything is issued.

With QueryOptions::debounce, a changed key is fetched only once it has stayed the same for that long: the call for the key it replaces is superseded at once (its reply is dropped), pending() is true while the query waits, and each further change restarts the wait. The first key, and a change to idle, apply at once; so does refetch(), which also ends a wait. Destroying the query cancels the wait.

A fetcher that throws instead of returning a Completion fails the request: the exception becomes error() and nothing is pending. A key that throws is an Effect that throws: reported (detail::site::kEffectThrew), and the query keeps its state. A delivery off the Runtime's owner is reported (detail::site::kOffOwner) and dropped.

The key or the fetcher may destroy the query (a remount), and so may another handler of the reply or an Effect the reply wakes; the query is not touched afterwards. The action a fetcher receives belongs to the query, so a fetcher that destroys the query must not use it afterwards.

Template Parameters

A	The action (request) type.
R	The result type; defaults to the action's registered result.

Definition at line 182 of file control.hpp.

Member Typedef Documentation

Key

template<typename A, typename R = typename model::ActionTraits<A>::Result>

using morph::reactive::Query< A, R >::Key = std::function<std::optional<A>()>

The tracked key: which request the query currently stands for, or nullopt for none.

Definition at line 185 of file control.hpp.

Fetch

template<typename A, typename R = typename model::ActionTraits<A>::Result>

using morph::reactive::Query< A, R >::Fetch = std::function<async::Completion<R>(A const&)>

Issues one request.

Definition at line 187 of file control.hpp.

Constructor & Destructor Documentation

Query() [1/2]

template<typename A, typename R = typename model::ActionTraits<A>::Result>

morph::reactive::Query< A, R >::Query ( Runtime & runtime, Fetch fetch, Key key, QueryOptions options = {} )

inline

Builds a query over any fetcher — the test seam, and the way to query a non-bridge source.

Parameters

runtime	The runtime. Borrowed: it must outlive the query.
fetch	Issues a request; its Completion must deliver on the runtime's owner.
key	The tracked key.
options	Timed refresh and debounce; see QueryOptions.

Exceptions

std::invalid_argument

when options.refreshEvery or options.debounce is negative, or either is positive while options.scheduler is null; nothing has been fetched then.

Definition at line 196 of file control.hpp.

Query() [2/2]

template<typename A, typename R = typename model::ActionTraits<A>::Result>

template<typename M, typename S>

morph::reactive::Query< A, R >::Query ( Runtime & runtime, bridge::BridgeHandler< M, S > & handler, Key key, QueryOptions options = {} )

inline

Builds a query that fetches through a bridge handler.

Checks the handler's callback executor against the runtime's owner (detail::checkHandlerExecutor).

Template Parameters

M	The handler's model type.
S	The handler's sharing policy.

Parameters

runtime	The runtime. Borrowed: it must outlive the query.
handler	Executes the requests; its callbacks must be delivered on the runtime's owner. Borrowed.
key	The tracked key.
options	Timed refresh and debounce; see QueryOptions.

Exceptions

std::invalid_argument

when options.refreshEvery or options.debounce is negative, or either is positive while options.scheduler is null; nothing has been fetched then.

Definition at line 235 of file control.hpp.

~Query()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

morph::reactive::Query< A, R >::~Query ( )

inlineoverride

Clears the query's invalidation link, so no mutation refetches it any more, and cancels what it has in flight.

Definition at line 243 of file control.hpp.

Member Function Documentation

pending()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

bool morph::reactive::Query< A, R >::pending ( ) const

inlinenodiscard

Whether a request for the current key is in flight. Tracked.

Returns

True from issue to delivery.

Definition at line 251 of file control.hpp.

value()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

std::optional< R > const & morph::reactive::Query< A, R >::value ( ) const

inlinenodiscard

The last successful result. Tracked.

Returns

The result, kept while a refetch or a new key is in flight and through a failed refetch of the same key; nullopt before the first, while idle, and after a failure for a different key. Valid until the next delivery.

Definition at line 257 of file control.hpp.

error()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

std::exception_ptr morph::reactive::Query< A, R >::error ( ) const

inlinenodiscard

The last failure. Tracked.

Returns

The exception, or null; cleared by the next success. After a key change, the previous key's failure remains until the new key settles.

Definition at line 262 of file control.hpp.

refetch()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

void morph::reactive::Query< A, R >::refetch ( )

inlineoverridevirtual

Re-issues the current key under a new generation, ending a debounce wait; idle stays idle. Refused, and reported, off the Runtime's owner (detail::site::kOffOwner) and inside a Computed's computation (detail::site::kIssueInComputed); nothing is issued then.

Implements morph::reactive::Refetchable.

Definition at line 268 of file control.hpp.

link()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

std::shared_ptr< InvalidationLink > morph::reactive::Query< A, R >::link ( ) const

inlinenodiscard

This query's link, for MutationOptions::invalidates.

Returns

The link; it refetches nothing once this query is destroyed.

Definition at line 286 of file control.hpp.

refreshOn()

template<typename A, typename R = typename model::ActionTraits<A>::Result>

template<typename Pub, typename M, typename S>

void morph::reactive::Query< A, R >::refreshOn ( bridge::BridgeHandler< M, S > & handler )

inline

Re-fetches whenever the bridge publishes a Pub on handler's instance.

Uses the handler's one subscription slot for Pub: two consumers of the same Pub use two handlers.

Template Parameters

Pub	The published result type to listen for.
M	The handler's model type.
S	The handler's sharing policy.

Parameters

handler

The handler whose instance publishes. Borrowed: it must outlive the query.

Definition at line 297 of file control.hpp.

---

The documentation for this class was generated from the following file:

• morph/reactive/control.hpp