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

A command: issues a write and tracks it, then refetches what the write invalidates. More...

#include <control.hpp>

Public Types
using	Run = std::function<async::Completion<R>(A)>
	Issues one call.

Public Member Functions
	Mutation (Runtime &runtime, Run run, MutationOptions< A > options={})
	Builds a mutation over any runner — the test seam, and the interpreter's path.
template<typename M, typename S>
	Mutation (Runtime &runtime, bridge::BridgeHandler< M, S > &handler, MutationOptions< A > options={})
	Builds a mutation that executes through a bridge handler.
	Mutation (Mutation const &)=delete
Mutation &	operator= (Mutation const &)=delete
	Mutation (Mutation &&)=delete
Mutation &	operator= (Mutation &&)=delete
bool	run (A action)
	Issues, queues or refuses action, as MutationOptions::concurrency says. Refused, and reported, off the Runtime's owner (detail::site::kOffOwner) and inside a Computed's computation (detail::site::kIssueInComputed).
bool	pending () const
	Whether a run is in flight or queued. Tracked.
std::exception_ptr	error () const
	The most recent applied failure. Tracked.
std::optional< R > const &	lastResult () const
	The most recent applied result. Tracked.
std::uint64_t	successCount () const
	How many successes have been applied. Tracked; it ticks once per applied success, so an Effect can react to "it succeeded again" when the result is equal to the last one.

Detailed Description

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

A command: issues a write and tracks it, then refetches what the write invalidates.

MutationOptions::concurrency decides what a run does while another is in flight (Concurrency). pending() is true while a run is in flight or queued. An applied success records lastResult(), clears error(), ticks successCount() and refetches every live query in MutationOptions::invalidates — one batch, so one flush and one frame. An applied failure records error() and invalidates nothing. A reply Latest does not apply only stops counting as pending.

The runner runs untracked: a run() from inside an Effect does not subscribe that Effect to what the runner reads, so a change there cannot issue the write again.

A runner that throws instead of returning a Completion fails that run: the exception becomes error() at once, and nothing is left pending for it. run() off the Runtime's owner, and a delivery off it, are reported (detail::site::kOffOwner) and dropped. A dropped delivery is never counted down, so pending() stays true for good and an Exclusive mutation refuses every later run: it is a wiring error, not a state to recover from. run() inside a Computed's computation is reported (detail::site::kIssueInComputed) and refused before anything is issued.

The runner may destroy the mutation, and so may a query's fetcher during an invalidation, another handler of the reply, or an Effect the reply wakes; the mutation is not touched afterwards.

Template Parameters

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

Definition at line 494 of file control.hpp.

Member Typedef Documentation

Run

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

using morph::reactive::Mutation< A, R >::Run = std::function<async::Completion<R>(A)>

Issues one call.

Definition at line 497 of file control.hpp.

Constructor & Destructor Documentation

Mutation() [1/2]

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

morph::reactive::Mutation< A, R >::Mutation ( Runtime & runtime, Run run, MutationOptions< A > options = {} )

inline

Builds a mutation over any runner — the test seam, and the interpreter's path.

Parameters

runtime	The runtime. Borrowed: it must outlive the mutation.
run	Issues a call; its Completion must deliver on the runtime's owner.
options	Concurrency and invalidation.

Definition at line 503 of file control.hpp.

Mutation() [2/2]

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

template<typename M, typename S>

morph::reactive::Mutation< A, R >::Mutation ( Runtime & runtime, bridge::BridgeHandler< M, S > & handler, MutationOptions< A > options = {} )

inline

Builds a mutation that executes 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 mutation.
handler	Executes the calls; its callbacks must be delivered on the runtime's owner. Borrowed.
options	Concurrency and invalidation.

Definition at line 521 of file control.hpp.

Member Function Documentation

run()

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

bool morph::reactive::Mutation< A, R >::run ( A action )

inline

Issues, queues or refuses action, as MutationOptions::concurrency says. Refused, and reported, off the Runtime's owner (detail::site::kOffOwner) and inside a Computed's computation (detail::site::kIssueInComputed).

Parameters

action

The action; built by the caller per gesture, so an idempotency key minted while building it is fresh per click.

Returns

False when the run was refused: Exclusive with a run in flight, off the owner, or inside a Computed. A run that was sent or queued returns true, even when its runner threw.

Definition at line 540 of file control.hpp.

pending()

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

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

inlinenodiscard

Whether a run is in flight or queued. Tracked.

Returns

True while any is.

Definition at line 572 of file control.hpp.

error()

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

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

inlinenodiscard

The most recent applied failure. Tracked.

Returns

The exception, or null; cleared by the next applied success.

Definition at line 576 of file control.hpp.

lastResult()

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

std::optional< R > const & morph::reactive::Mutation< A, R >::lastResult ( ) const

inlinenodiscard

The most recent applied result. Tracked.

Returns

The result, or nullopt before the first success. Valid until the next applied success.

Definition at line 580 of file control.hpp.

successCount()

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

std::uint64_t morph::reactive::Mutation< A, R >::successCount ( ) const

inlinenodiscard

How many successes have been applied. Tracked; it ticks once per applied success, so an Effect can react to "it succeeded again" when the result is equal to the last one.

Returns

The count.

Definition at line 585 of file control.hpp.

---

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

• morph/reactive/control.hpp