Class Tryll::Client::AgentVariables

ClassList > Tryll > Client > AgentVariables

Client-side mirror + deferred-flush batcher for one agent's declared variables. More...

• #include <AgentVariables.h>

Classes

Type	Name
struct	PendingUpdate

Public Types

Type	Name
enum std::uint8_t	Op

Public Functions

Type	Name
void	AddToSet (std::string_view name, std::string_view element)
	AgentVariables () = default
std::optional< VariableType >	DeclaredType (std::string_view name) noexcept const
void	Flush ()
std::optional< bool >	GetBool (std::string_view name) const
std::optional< double >	GetFloat (std::string_view name) const
std::optional< std::int64_t >	GetInt (std::string_view name) const
std::optional< std::string >	GetString (std::string_view name) const
std::optional< std::vector< std::string > >	GetStringSet (std::string_view name) const
void	HandleFlushResult (const std::optional< TryllError > & error)
bool	IsDeclared (std::string_view name) noexcept const
bool	IsDirty () noexcept const True if any write is staged and not yet sent to the server.
void	MergeServerValues (const std::vector< std::pair< std::string, VariableValue > > & fetched)
void	RemoveFromSet (std::string_view name, std::string_view element)
void	Reset (std::string_view name)
void	SetBool (std::string_view name, bool value)
void	SetFloat (std::string_view name, double value)
void	SetInt (std::string_view name, std::int64_t value)
void	SetString (std::string_view name, std::string value)
void	SetStringSet (std::string_view name, std::vector< std::string > value)
std::vector< std::pair< std::string, VariableValue > >	Snapshot () const
void	SyncFromServer (std::vector< std::string > names={}, std::chrono::milliseconds timeout=std::chrono::seconds{10})

Detailed Description

Obtained via Tryll::Client::AgentProxy::Variables. Reads are synchronous, served from the local mirror — only the client writes variables in v1, so no server round-trip is needed to read one back. Writes are validated locally (unknown name / type mismatch throws Tryll::Client::TryllError immediately, no wire traffic) and staged; the proxy flushes any staged writes as one batched UpdateAgentVariablesRequest automatically, immediately before the next agent interaction (SendText / Resume / ChangeParams — not Cancel). Staged writes are coalesced per name (last value wins for scalars; a minimal add/remove delta, or a whole-set assign, whichever is smaller, for sets) so rapid repeated writes never grow the batch unboundedly.

Flushed writes are non-blocking. The batch is retained in-flight until the server acknowledges it: on a transient AgentBusy the batch is re-staged behind any newer writes and retried on the next interaction; on a hard rejection (rare, since the mirror pre-validates unknown-name/type-mismatch locally) the affected names are re-synced from the server so the mirror never stays silently diverged. Either way the error surfaces through the agent's usual Tryll::Client::AgentProxy::SetOnError callback, the same path SendText errors use.

Public Types Documentation

enum Op

enum Tryll::Client::AgentVariables::Op {
    Assign,
    AddToSet,
    RemoveFromSet,
    Reset
};

One staged mutation, in wire-op terms. Exposed (rather than kept private) only so TryllClientImpl can encode it — treat as implementation detail, not a stable public API.

---

Public Functions Documentation

function AddToSet

void Tryll::Client::AgentVariables::AddToSet (
    std::string_view name,
    std::string_view element
) 

Idempotent — no-op if element is already present.

Exception:

• TryllError If name is not declared or is not a StringSet.

---

function AgentVariables

Tryll::Client::AgentVariables::AgentVariables () = default

---

function DeclaredType

std::optional< VariableType > Tryll::Client::AgentVariables::DeclaredType (
    std::string_view name
) noexcept const

---

function Flush

void Tryll::Client::AgentVariables::Flush () 

Send any staged writes now as one batched request, instead of waiting for the next SendText/Resume/ChangeParams call. Fire-and-forget, same as the automatic flush — errors surface via the agent's OnError callback. No-op if nothing is staged.

---

function GetBool

std::optional< bool > Tryll::Client::AgentVariables::GetBool (
    std::string_view name
) const

---

function GetFloat

std::optional< double > Tryll::Client::AgentVariables::GetFloat (
    std::string_view name
) const

---

function GetInt

std::optional< std::int64_t > Tryll::Client::AgentVariables::GetInt (
    std::string_view name
) const

---

function GetString

std::optional< std::string > Tryll::Client::AgentVariables::GetString (
    std::string_view name
) const

---

function GetStringSet

std::optional< std::vector< std::string > > Tryll::Client::AgentVariables::GetStringSet (
    std::string_view name
) const

---

function HandleFlushResult

void Tryll::Client::AgentVariables::HandleFlushResult (
    const std::optional< TryllError > & error
) 

Result of a flushed batch, routed back from the reader thread via TryllClientImpl::OnVariableFlushResult. error is nullopt on success. Exposed only so TryllClientImpl can invoke it; treat as internal.

---

function IsDeclared

bool Tryll::Client::AgentVariables::IsDeclared (
    std::string_view name
) noexcept const

---

function IsDirty

True if any write is staged and not yet sent to the server.

bool Tryll::Client::AgentVariables::IsDirty () noexcept const

---

function MergeServerValues

void Tryll::Client::AgentVariables::MergeServerValues (
    const std::vector< std::pair< std::string, VariableValue > > & fetched
) 

Merge server-fetched values into the mirror, skipping any name with a locally newer (staged or in-flight) write. Exposed only for TryllClientImpl's async re-sync path; treat as internal.

---

function RemoveFromSet

void Tryll::Client::AgentVariables::RemoveFromSet (
    std::string_view name,
    std::string_view element
) 

Idempotent — no-op if element is already absent.

Exception:

• TryllError If name is not declared or is not a StringSet.

---

function Reset

void Tryll::Client::AgentVariables::Reset (
    std::string_view name
) 

Restores the CreateAgent initial value.

Exception:

• TryllError If name is not declared.

---

function SetBool

void Tryll::Client::AgentVariables::SetBool (
    std::string_view name,
    bool value
) 

Exception:

• TryllError If name is not declared, or its declared type is not Bool.

---

function SetFloat

void Tryll::Client::AgentVariables::SetFloat (
    std::string_view name,
    double value
) 

Exception:

• TryllError If name is not declared, or its declared type is not Float.

---

function SetInt

void Tryll::Client::AgentVariables::SetInt (
    std::string_view name,
    std::int64_t value
) 

Exception:

• TryllError If name is not declared, or its declared type is not Int.

---

function SetString

void Tryll::Client::AgentVariables::SetString (
    std::string_view name,
    std::string value
) 

Exception:

• TryllError If name is not declared, or its declared type is not String.

---

function SetStringSet

void Tryll::Client::AgentVariables::SetStringSet (
    std::string_view name,
    std::vector< std::string > value
) 

Exception:

• TryllError If name is not declared, or its declared type is not StringSet.

---

function Snapshot

std::vector< std::pair< std::string, VariableValue > > Tryll::Client::AgentVariables::Snapshot () const

Every declared variable and its current mirrored value, in no particular order. Mainly for diagnostics/debug UI (e.g. test-chat's /var show).

---

function SyncFromServer

void Tryll::Client::AgentVariables::SyncFromServer (
    std::vector< std::string > names={},
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
) 

Debug/verification round-trip: fetch current values from the server and merge them into the local mirror (does not touch pending/staged writes). Normal reads never need this — only the client writes variables in v1, so the mirror is authoritative; use this only to double-check server state. names empty means every declared variable. Blocks until the response arrives or timeout elapses.

Exception:

• TryllError On server error, disconnect, or timeout.

---

Friends Documentation

friend TryllClientImpl

class Tryll::Client::AgentVariables::TryllClientImpl (
    Internal::TryllClientImpl
) 

---

---

The documentation for this class was generated from the following file C:/_tryll/_monorepo3/tryll/clients/cpp/include/tryll/AgentVariables.h