What screens of one client session share (spec 5 §5, §12b): the query cache, the mounted queries, the principal's permitted actions, the formatting facts and the client's env, session and host values. More...

#include <interpreter.hpp>

Public Member Functions
	Session (reactive::Runtime &runtime, SessionOptions options={})
	An empty session.
	Session (Session const &)=delete
Session &	operator= (Session const &)=delete
	Session (Session &&)=delete
Session &	operator= (Session &&)=delete
reactive::Runtime &	runtime () const noexcept
	The runtime.
SessionOptions const &	options () const noexcept
	The options.
void	setPermitted (std::set< std::string, std::less<> > permitted)
	Sets the action ids the principal may run, as the catalog reply lists them; {"can": ...} follows them.
bool	can (std::string_view action) const
	Whether the principal may run an action, or the client can run a host command now. A tracked read.
void	setFormatting (FormatContext format)
	Replaces the formatting facts; every t and display function re-evaluates.
FormatContext const &	formatting () const
	The formatting facts. A tracked read.
void	setLocale (std::string locale)
	Changes the active locale, keeping the other formatting facts.
void	setTranslations (render::TranslationProvider translations)
	Replaces the message catalogue, keeping the other formatting facts; every t re-resolves.
void	setEnvironment (ValueRecord values)
	Sets the env values (widthClass, locale, platform, online, backend).
void	setSessionValues (ValueRecord values)
	Sets the session values (principal, userName, …).
void	setHostValues (ValueRecord values)
	Sets the host values the application registered.
void	setHostCommands (HostCommands commands)
	Sets the client's host commands: the names {"can": "host:name"} answers for, and what runs them. A session without a runner asks InterpreterHost::hostCommand.
std::function< HostCommandResult(std::string const &, Value const &)> const &	hostCommandRunner () const noexcept
	What runs host commands.
Value	client (ExprKind form, std::string_view name) const
	Reads env, session or host. A tracked read.
detail::RtScope const *	appScope () const noexcept
	The app document's scope, which {"ref": "app.name"} reads and {"set": "app.name"} writes; set by Interpreter::mountApp for as long as the AppRoot lives.
void	setAppScope (detail::RtScope const *scope) noexcept
	Installs or clears the app document's scope. Called by AppRoot, nothing else.
void	clear ()
	Drops every cache entry: signOut and a principal change (spec 5 §5, "Isolation").
void	backendChanged (std::string const &backend)
	Carries out a committed backend switch (spec 6 §9), in one batch: every mounted screen's onBackendChange runs first, then every entry is marked stale and the mounted queries refetch, and {"env": "backend"} becomes `backend`. A query on a private alias therefore never fetches before its screen has recovered from the switch.
void	attachScreen (detail::ScreenCore &screen)
	Registers a mounted screen or app document, whose onBackendChange a backend switch runs.
void	detachScreen (detail::ScreenCore &screen)
	Forgets a screen or app document.
void	prefetch (std::shared_ptr< ModelChannel > const &channel, std::string const &token, std::string const &typeId, std::string const &action, Value const &body)
	Starts a query's request before its screen mounts, so the screen mounts on a warm cache.
std::size_t	cacheSize () const noexcept
	The number of entries in the cache.
std::string	privateToken ()
	A fresh instance token for a private alias: what the cache key holds for its instance.
bool	lastWriteByUser () const noexcept
	Whether the newest write to a document source was made by a user event (spec 5 §6, source: "user").
void	noteWrite () noexcept
	Records a write to a document source.
void	asUser (std::function< void()> const &body)
	Runs `body` as a user event: what it writes counts as the user's.
std::shared_ptr< detail::CacheEntry >	acquire (std::string const &token, std::string const &typeId, std::string const &action, bool evaluate, Value const &body)
	Finds or makes an entry and counts one more user.
void	release (std::shared_ptr< detail::CacheEntry > const &entry)
	Counts one user less; an entry nobody uses is dropped after keepUnused.
void	fetch (std::shared_ptr< detail::CacheEntry > const &entry, std::shared_ptr< ModelChannel > const &channel)
	Sends an entry's request under a new generation; a reply of an older generation is dropped.
void	confirm (detail::CacheEntry &entry, Value const &confirmed)
	Writes an entry's confirmed value and re-applies its optimistic layers over it.
void	showLayers (detail::CacheEntry &entry)
	Recomputes what an entry shows from its confirmed value and its layers.
std::string	classify (std::exception_ptr const &error) const
	The error kind of a failure.
std::chrono::milliseconds	now () const
	The clock.
void	attachQuery (detail::QueryRuntime &query)
	Registers a mounted query, which a reconnect and a backend switch refetch.
void	forgetQuery (detail::QueryRuntime &query)
	Unregisters a mounted query.
void	actionSucceeded (std::string const &typeId, std::string const &actionId, Value const &reply, ReplyUse use, std::string const &instanceToken)
	A call of `actionId` on a model of `typeId` succeeded: applies the action's effects to the cache (spec 8 §9).
void	reconnected ()
	The connection to the server was made again (spec 8 §7, "Reconnect"): sends the whole watch set with replace: true, then marks every entry but an evaluate one stale. A mounted entry refetches, and one whose fetch is in flight fetches once more when that fetch settles, so a change missed while the connection was down is read again.
wire::WatchBody	watchSet () const
	The topics the cache holds now: every record an entry holds, and the keyed shared instance of every entry whose action holds no record. What reconnected sends.
void	deliverEvent (wire::EventBody const &event)
	Applies a server event to the cache (spec 8 §9).
void	applyChanges (wire::ChangesBody const &changes)
	Applies a changes event's payload to the cache, in one reactive batch.

Static Public Member Functions
static std::string	cacheKey (std::string const &token, std::string const &typeId, std::string const &action, bool evaluate, std::string const &body)
	The cache key of a query.
static void	markStale (detail::CacheEntry &entry)
	Marks an entry stale. While its fetch is in flight, the entry also refetches once that fetch settles, because the fetch may have read before the change.

Detailed Description

What screens of one client session share (spec 5 §5, §12b): the query cache, the mounted queries, the principal's permitted actions, the formatting facts and the client's env, session and host values.

It belongs to the runtime's owner, outlives every screen mounted on it, and is cleared by signOut and on a principal change.

Definition at line 888 of file interpreter.hpp.

Constructor & Destructor Documentation

◆ Session()

morph::ui::Session::Session	(	reactive::Runtime &	runtime,
		SessionOptions	options = {} )

inlineexplicit

An empty session.

Parameters

runtime	The runtime. Borrowed.
options	Timers, clock, catalog and the inline cap.

Exceptions

std::invalid_argument when maxInlineFileBytes is 0 or above kMaxInlineFileBytes.

Definition at line 894 of file interpreter.hpp.

Member Function Documentation

◆ runtime()

reactive::Runtime & morph::ui::Session::runtime ( ) const

inlinenodiscardnoexcept

The runtime.

Returns: It.

Definition at line 912 of file interpreter.hpp.

◆ options()

SessionOptions const & morph::ui::Session::options ( ) const

inlinenodiscardnoexcept

The options.

Returns: They.

Definition at line 916 of file interpreter.hpp.

◆ setPermitted()

void morph::ui::Session::setPermitted ( std::set< std::string, std::less<> > permitted )

inline

Sets the action ids the principal may run, as the catalog reply lists them; {"can": ...} follows them.

Parameters

permitted The ids.

Definition at line 920 of file interpreter.hpp.

◆ can()

bool morph::ui::Session::can ( std::string_view action ) const

inlinenodiscard

Whether the principal may run an action, or the client can run a host command now. A tracked read.

A host: name is answered from the client's own commands (setHostCommands), never from the server's permitted set: the two have different owners, and a catalog refresh must not drop the client's commands.

Parameters

action The action id, or host:<command>.

Returns: Whether it is permitted.

Definition at line 928 of file interpreter.hpp.

◆ setFormatting()

void morph::ui::Session::setFormatting ( FormatContext format )

inline

Replaces the formatting facts; every t and display function re-evaluates.

Parameters

format The facts.

Definition at line 938 of file interpreter.hpp.

◆ formatting()

FormatContext const & morph::ui::Session::formatting ( ) const

inlinenodiscard

The formatting facts. A tracked read.

Returns: They.

Definition at line 942 of file interpreter.hpp.

◆ setLocale()

void morph::ui::Session::setLocale ( std::string locale )

inline

Changes the active locale, keeping the other formatting facts.

Parameters

locale The BCP 47 locale.

Definition at line 946 of file interpreter.hpp.

◆ setTranslations()

void morph::ui::Session::setTranslations ( render::TranslationProvider translations )

inline

Replaces the message catalogue, keeping the other formatting facts; every t re-resolves.

Parameters

translations The provider, such as MessageCatalogues::provider(); empty shows every fallback.

Definition at line 954 of file interpreter.hpp.

◆ setEnvironment()

void morph::ui::Session::setEnvironment ( ValueRecord values )

inline

Sets the env values (widthClass, locale, platform, online, backend).

Parameters

values The values.

Definition at line 962 of file interpreter.hpp.

◆ setSessionValues()

void morph::ui::Session::setSessionValues ( ValueRecord values )

inline

Sets the session values (principal, userName, …).

Parameters

values The values.

Definition at line 966 of file interpreter.hpp.

◆ setHostValues()

void morph::ui::Session::setHostValues ( ValueRecord values )

inline

Sets the host values the application registered.

Parameters

values The values.

Definition at line 970 of file interpreter.hpp.

◆ setHostCommands()

void morph::ui::Session::setHostCommands ( HostCommands commands )

inline

Sets the client's host commands: the names {"can": "host:name"} answers for, and what runs them. A session without a runner asks InterpreterHost::hostCommand.

Parameters

commands The names and the runner.

Definition at line 975 of file interpreter.hpp.

◆ hostCommandRunner()

std::function< HostCommandResult(std::string const &, Value const &)> const & morph::ui::Session::hostCommandRunner ( ) const

inlinenodiscardnoexcept

What runs host commands.

Returns: It; empty when the application set none.

Definition at line 982 of file interpreter.hpp.

◆ client()

Value morph::ui::Session::client	(	ExprKind	form,
		std::string_view	name ) const

inlinenodiscard

Reads env, session or host. A tracked read.

Parameters

form	Env, Session or Host.
name	The name.

Returns: The value, or null.

Definition at line 991 of file interpreter.hpp.

◆ appScope()

detail::RtScope const * morph::ui::Session::appScope ( ) const

inlinenodiscardnoexcept

The app document's scope, which {"ref": "app.name"} reads and {"set": "app.name"} writes; set by Interpreter::mountApp for as long as the AppRoot lives.

Returns: It, or nullptr when no app document is mounted.

Definition at line 1005 of file interpreter.hpp.

◆ setAppScope()

void morph::ui::Session::setAppScope ( detail::RtScope const * scope )

inlinenoexcept

Installs or clears the app document's scope. Called by AppRoot, nothing else.

Parameters

scope The scope, or nullptr.

Definition at line 1009 of file interpreter.hpp.

◆ clear()

void morph::ui::Session::clear ( )

inline

Drops every cache entry: signOut and a principal change (spec 5 §5, "Isolation").

Definition at line 1012 of file interpreter.hpp.

◆ backendChanged()

void morph::ui::Session::backendChanged ( std::string const & backend )

inline

Carries out a committed backend switch (spec 6 §9), in one batch: every mounted screen's onBackendChange runs first, then every entry is marked stale and the mounted queries refetch, and {"env": "backend"} becomes backend. A query on a private alias therefore never fetches before its screen has recovered from the switch.

Parameters

backend The backend now in use.

Definition at line 3046 of file interpreter.hpp.

◆ attachScreen()

void morph::ui::Session::attachScreen ( detail::ScreenCore & screen )

inline

Registers a mounted screen or app document, whose onBackendChange a backend switch runs.

Parameters

screen It. Borrowed until detachScreen.

Definition at line 1036 of file interpreter.hpp.

◆ detachScreen()

void morph::ui::Session::detachScreen ( detail::ScreenCore & screen )

inline

Forgets a screen or app document.

Parameters

screen It.

Definition at line 1040 of file interpreter.hpp.

◆ prefetch()

void morph::ui::Session::prefetch	(	std::shared_ptr< ModelChannel > const &	channel,
		std::string const &	token,
		std::string const &	typeId,
		std::string const &	action,
		Value const &	body )

inline

Starts a query's request before its screen mounts, so the screen mounts on a warm cache.

Parameters

channel	The alias's channel.
token	The alias's instance token (Screen::instanceToken).
typeId	The model type.
action	The action.
body	The body.

Definition at line 1048 of file interpreter.hpp.

◆ cacheSize()

std::size_t morph::ui::Session::cacheSize ( ) const

inlinenodiscardnoexcept

The number of entries in the cache.

Returns: It.

Definition at line 1059 of file interpreter.hpp.

◆ privateToken()

std::string morph::ui::Session::privateToken ( )

inlinenodiscard

A fresh instance token for a private alias: what the cache key holds for its instance.

Returns: It, unique in the session.

Definition at line 1063 of file interpreter.hpp.

◆ lastWriteByUser()

bool morph::ui::Session::lastWriteByUser ( ) const

inlinenodiscardnoexcept

Whether the newest write to a document source was made by a user event (spec 5 §6, source: "user").

Returns: It.

Definition at line 1067 of file interpreter.hpp.

◆ noteWrite()

void morph::ui::Session::noteWrite ( )

inlinenoexcept

Records a write to a document source.

Definition at line 1070 of file interpreter.hpp.

◆ asUser()

void morph::ui::Session::asUser ( std::function< void()> const & body )

inline

Runs body as a user event: what it writes counts as the user's.

Parameters

body The body.

Definition at line 1074 of file interpreter.hpp.

◆ cacheKey()

std::string morph::ui::Session::cacheKey	(	std::string const &	token,
		std::string const &	typeId,
		std::string const &	action,
		bool	evaluate,
		std::string const &	body )

inlinestaticnodiscard

The cache key of a query.

Parameters

token	The alias's instance token.
typeId	The model type.
action	The action.
evaluate	Whether it is an evaluate query.
body	The canonical body.

Returns: The key.

Definition at line 1092 of file interpreter.hpp.

◆ acquire()

std::shared_ptr< detail::CacheEntry > morph::ui::Session::acquire	(	std::string const &	token,
		std::string const &	typeId,
		std::string const &	action,
		bool	evaluate,
		Value const &	body )

inline

Finds or makes an entry and counts one more user.

Parameters

token	The alias's instance token.
typeId	The model type.
action	The action.
evaluate	Whether it is an evaluate query.
body	The body.

Returns: The entry.

Definition at line 1104 of file interpreter.hpp.

◆ release()

void morph::ui::Session::release ( std::shared_ptr< detail::CacheEntry > const & entry )

inline

Counts one user less; an entry nobody uses is dropped after keepUnused.

Parameters

entry The entry.

Definition at line 1135 of file interpreter.hpp.

◆ fetch()

void morph::ui::Session::fetch	(	std::shared_ptr< detail::CacheEntry > const &	entry,
		std::shared_ptr< ModelChannel > const &	channel )

inline

Sends an entry's request under a new generation; a reply of an older generation is dropped.

Parameters

entry	The entry.
channel	The channel to send it through; nullptr fails the request at once.

Definition at line 1153 of file interpreter.hpp.

◆ confirm()

void morph::ui::Session::confirm	(	detail::CacheEntry &	entry,
		Value const &	confirmed )

inline

Writes an entry's confirmed value and re-applies its optimistic layers over it.

Parameters

entry	The entry.
confirmed	The confirmed value.

Definition at line 1188 of file interpreter.hpp.

◆ showLayers()

void morph::ui::Session::showLayers ( detail::CacheEntry & entry )

inline

Recomputes what an entry shows from its confirmed value and its layers.

Parameters

entry The entry.

Definition at line 1195 of file interpreter.hpp.

◆ classify()

std::string morph::ui::Session::classify ( std::exception_ptr const & error ) const

inlinenodiscard

The error kind of a failure.

Parameters

error The failure.

Returns: The kind.

Definition at line 1209 of file interpreter.hpp.

◆ now()

std::chrono::milliseconds morph::ui::Session::now ( ) const

inlinenodiscard

The clock.

Returns: Now.

Definition at line 1215 of file interpreter.hpp.

◆ attachQuery()

void morph::ui::Session::attachQuery ( detail::QueryRuntime & query )

inline

Registers a mounted query, which a reconnect and a backend switch refetch.

Parameters

query The query.

Definition at line 1225 of file interpreter.hpp.

◆ forgetQuery()

void morph::ui::Session::forgetQuery ( detail::QueryRuntime & query )

inline

Unregisters a mounted query.

Parameters

query The query.

Definition at line 1229 of file interpreter.hpp.

◆ actionSucceeded()

void morph::ui::Session::actionSucceeded	(	std::string const &	typeId,
		std::string const &	actionId,
		Value const &	reply,
		ReplyUse	use,
		std::string const &	instanceToken )

inline

A call of actionId on a model of typeId succeeded: applies the action's effects to the cache (spec 8 §9).

updates R merges the reply's rows of R into each entry holding R, matched by the record's key field at the entry's paths, with no fetch; an entry whose fetch is in flight also fetches once more, since that fetch may have read before the write. changes R marks each entry holding R stale. changesInstance marks each entry read through the same instance. A marked entry refetches through a mounted query that uses it. A discarded reply only marks: its updates act as changes.

Parameters

typeId	The model type.
actionId	The action.
reply	The reply's value.
use	Whether the reply was applied or discarded.
instanceToken	The instance token of the alias the call went through.

Definition at line 3320 of file interpreter.hpp.

◆ reconnected()

void morph::ui::Session::reconnected ( )

inline

The connection to the server was made again (spec 8 §7, "Reconnect"): sends the whole watch set with replace: true, then marks every entry but an evaluate one stale. A mounted entry refetches, and one whose fetch is in flight fetches once more when that fetch settles, so a change missed while the connection was down is read again.

Definition at line 3233 of file interpreter.hpp.

◆ watchSet()

wire::WatchBody morph::ui::Session::watchSet ( ) const

inlinenodiscard

The topics the cache holds now: every record an entry holds, and the keyed shared instance of every entry whose action holds no record. What reconnected sends.

Returns: The topics, records and instances each in name order; replace is false.

Definition at line 3206 of file interpreter.hpp.

◆ deliverEvent()

void morph::ui::Session::deliverEvent ( wire::EventBody const & event )

inline

Applies a server event to the cache (spec 8 §9).

A changes event marks the entries it names stale, and a resync sends the whole watch set again, as reconnected does, and marks every entry but an evaluate one; each marked entry refetches through a mounted query that uses it, and one no query uses refetches when a query mounts on it. An event of another topic, or a payload that cannot be read, is ignored.

Parameters

event The event.

Definition at line 3247 of file interpreter.hpp.

◆ applyChanges()

void morph::ui::Session::applyChanges ( wire::ChangesBody const & changes )

inline

Applies a changes event's payload to the cache, in one reactive batch.

A record change with keys marks each entry holding the record whose value has a row with one of the keys, and an entry holding it keyless; a record change without keys marks every entry holding the record. An instance change marks every entry read through that instance: the keyed shared one its primary key names, or, with no primary key, the connection's own private ones of that model type.

Parameters

changes The payload.

Definition at line 3260 of file interpreter.hpp.

◆ markStale()

void morph::ui::Session::markStale ( detail::CacheEntry & entry )

inlinestatic

Marks an entry stale. While its fetch is in flight, the entry also refetches once that fetch settles, because the fetch may have read before the change.

Parameters

entry The entry.

Definition at line 1279 of file interpreter.hpp.

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

morph/ui/interpreter.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Session()

Member Function Documentation

◆ runtime()

◆ options()

◆ setPermitted()

◆ can()

◆ setFormatting()

◆ formatting()

◆ setLocale()

◆ setTranslations()

◆ setEnvironment()

◆ setSessionValues()

◆ setHostValues()

◆ setHostCommands()

◆ hostCommandRunner()

◆ client()

◆ appScope()

◆ setAppScope()

◆ clear()

◆ backendChanged()

◆ attachScreen()

◆ detachScreen()

◆ prefetch()

◆ cacheSize()

◆ privateToken()

◆ lastWriteByUser()

◆ noteWrite()

◆ asUser()

◆ cacheKey()

◆ acquire()

◆ release()

◆ fetch()

◆ confirm()

◆ showLayers()

◆ classify()

◆ now()

◆ attachQuery()

◆ forgetQuery()

◆ actionSucceeded()

◆ reconnected()

◆ watchSet()

◆ deliverEvent()

◆ applyChanges()

◆ markStale()