a11::service::Session Class Reference

A connection-scoped runtime that multiplexes wire streams and runs actions. More...

#include <cpp/a11/service/session.h>

Inheritance diagram for a11::service::Session:

Classes
struct	State
struct	StreamState

Public Member Functions
virtual	~Session ()=default
absl::StatusOr< std::vector< std::pair< std::string, std::shared_ptr< net::WireStream > > > >	Streams () const
	Return the streams currently attached to the session.
absl::StatusOr< std::shared_ptr< net::WireStream > >	GetStream (std::string_view stream_id) const
	Look up an attached stream by id.
std::string	GetId () const
	Return the session's unique identifier.
std::shared_ptr< nodes::NodeMap >	GetNodeMap () const
	Return the NodeMap backing this session's node state.
absl::Status	SetNodeMap (std::shared_ptr< nodes::NodeMap > node_map)
	Replace the NodeMap backing this session's node state.
std::shared_ptr< actions::ActionRegistry >	GetActionRegistry () const
	Return the registry used to resolve incoming action messages.
absl::Status	SetActionRegistry (std::shared_ptr< actions::ActionRegistry > registry)
	Replace the registry used to resolve incoming action messages.
std::vector< std::pair< std::string, std::shared_ptr< actions::Action > > >	Actions () const
	Return the actions currently running in the session.
absl::StatusOr< std::shared_ptr< actions::Action > >	GetAction (std::string_view action_id) const
	Look up a running action by id.
absl::Status	CancelAction (std::string_view action_id)
	Request cancellation of a running action.
absl::Status	CancelAllActions ()
	Request cancellation of every running action.
a11::Task	AwaitAllActions (absl::Duration timeout=absl::InfiniteDuration())
	Wait for all in-flight actions to finish.
a11::Future< std::uint32_t >	DispatchNodeFragment (data::NodeFragment fragment)
	Dispatch a node fragment into the session's NodeMap.
a11::Task	DispatchActionMessage (data::ActionMessage message, std::shared_ptr< net::WireStream > origin_stream=nullptr)
	Resolve an action message against the registry and run it.
a11::Task	DispatchAction (std::shared_ptr< actions::Action > action)
	Run an already-constructed action within the session.
a11::Task	DispatchWireMessage (data::WireMessage message, std::shared_ptr< net::WireStream > origin_stream=nullptr)
	Route a wire message through the session as if it arrived on a stream.
bool	IsClosed () const
	Report whether the session has been closed.
bool	IsDone () const
	Report whether the session has fully finished.
a11::Task	Done () const
	Await the session's full completion.
absl::Status	GetStatus () const
	Return the session's terminal status.
absl::StatusOr< a11::Task >	AddStream (std::shared_ptr< net::WireStream > stream, StreamMode mode=StreamMode::kStart)
	Attach a wire stream and begin pumping its messages.
absl::Status	HalfClose ()
	Signal that this side will send no more messages.
virtual absl::Status	Abort (absl::Status status)
	Abort the session immediately, cancelling streams and actions.
absl::Status	Send (data::WireMessage message, std::string_view stream_id={})
	Enqueue a wire message for delivery.
absl::Time	deadline () const
	Return the absolute deadline after which the session is aborted.
absl::Status	SetDeadline (absl::Time deadline=absl::InfiniteFuture())
	Set the absolute deadline after which the session is aborted.

Static Public Member Functions
static absl::StatusOr< std::shared_ptr< Session > >	Create (std::string session_id={}, OnSessionStreamMessage on_stream_message={}, OnSessionStreamDone on_stream_done={}, data::ByteMap headers={}, SessionOptions options={}, std::shared_ptr< nodes::NodeMap > node_map=nullptr, std::shared_ptr< actions::ActionRegistry > action_registry=nullptr)
	Create a session.

Protected Member Functions
	Session ()=default
absl::Status	Initialize (const std::shared_ptr< Session > &self, std::string session_id, OnSessionStreamMessage on_stream_message, OnSessionStreamDone on_stream_done, data::ByteMap headers, SessionOptions options, std::shared_ptr< nodes::NodeMap > node_map, std::shared_ptr< actions::ActionRegistry > action_registry)

Friends
class	actions::Action

Detailed Description

A connection-scoped runtime that multiplexes wire streams and runs actions.

A session attaches one or more net::WireStream transports, pumps their messages, dispatches incoming action calls against its actions::ActionRegistry, and applies node fragments to its nodes::NodeMap. It tracks every stream and action so the connection can drain and close cleanly. Streams may deliver messages to the optional message/done callbacks. Instances are heap-allocated and shared via Create.

Constructor & Destructor Documentation

~Session()

virtual a11::service::Session::~Session ( )

virtualdefault

Session()

a11::service::Session::Session ( )

protecteddefault

Member Function Documentation

Abort()

absl::Status a11::service::Session::Abort ( absl::Status  status )

virtual

Abort the session immediately, cancelling streams and actions.

Parameters

status

The error to abort with.

Returns

OK, or an error status on failure.

Reimplemented in a11::service::SessionWithRecv.

Actions()

std::vector< std::pair< std::string, std::shared_ptr< actions::Action > > > a11::service::Session::Actions

(

)

const

Return the actions currently running in the session.

Returns

A point-in-time snapshot of (action_id, action) pairs of in-flight work.

AddStream()

absl::StatusOr< a11::Task > a11::service::Session::AddStream	(	std::shared_ptr< net::WireStream >	stream,
		StreamMode	mode = StreamMode::kStart
	)

Attach a wire stream and begin pumping its messages.

Parameters

stream	The transport to attach.
mode	Whether this side starts or accepts the stream.

Returns

An awaitable that resolves once the stream's startup handshake completes, or an error status on failure.

AwaitAllActions()

a11::Task a11::service::Session::AwaitAllActions

(

absl::Duration

timeout = absl::InfiniteDuration()

)

Wait for all in-flight actions to finish.

Parameters

timeout

How long to wait before giving up.

Returns

An awaitable that resolves once all actions have finished or the timeout elapses.

CancelAction()

absl::Status a11::service::Session::CancelAction

(

std::string_view

action_id

)

Request cancellation of a running action.

Parameters

action_id

The action identifier.

Returns

OK, or an error status if the action is unknown. Cancellation is cooperative and completes asynchronously.

CancelAllActions()

absl::Status a11::service::Session::CancelAllActions

(

)

Request cancellation of every running action.

Returns

OK, or an error status on failure; each action unwinds asynchronously.

Create()

absl::StatusOr< std::shared_ptr< Session > > a11::service::Session::Create ( std::string  session_id = {}, OnSessionStreamMessage  on_stream_message = {}, OnSessionStreamDone  on_stream_done = {}, data::ByteMap  headers = {}, SessionOptions  options = {}, std::shared_ptr< nodes::NodeMap >  node_map = nullptr, std::shared_ptr< actions::ActionRegistry >  action_registry = nullptr  )

static

Create a session.

Parameters

session_id	Unique identifier; generated when empty.
on_stream_message	Optional per-message callback (may be a coroutine).
on_stream_done	Optional stream-finished callback (may be a coroutine).
headers	Session-level headers.
options	Limits and timeouts governing the session.
node_map	Node registry backing this session's node state; a fresh one is created when null.
action_registry	Registry resolving incoming action messages; may be null.

Returns

The new session, or an error status on failure.

deadline()

absl::Time a11::service::Session::deadline

(

)

const

Return the absolute deadline after which the session is aborted.

Returns

The current deadline.

DispatchAction()

a11::Task a11::service::Session::DispatchAction

(

std::shared_ptr< actions::Action >

action

)

Run an already-constructed action within the session.

Parameters

action

The action to dispatch programmatically.

Returns

An awaitable that resolves once the action has been handled.

DispatchActionMessage()

a11::Task a11::service::Session::DispatchActionMessage	(	data::ActionMessage	message,
		std::shared_ptr< net::WireStream >	origin_stream = nullptr
	)

Resolve an action message against the registry and run it.

Parameters

message	The action message to dispatch.
origin_stream	Optional stream the message is attributed to.

Returns

An awaitable that resolves once the action has been handled.

DispatchNodeFragment()

a11::Future< std::uint32_t > a11::service::Session::DispatchNodeFragment

(

data::NodeFragment

fragment

)

Dispatch a node fragment into the session's NodeMap.

Parameters

fragment

The fragment to apply; fragments are applied in order.

Returns

An awaitable that resolves to the applied revision.

DispatchWireMessage()

a11::Task a11::service::Session::DispatchWireMessage	(	data::WireMessage	message,
		std::shared_ptr< net::WireStream >	origin_stream = nullptr
	)

Route a wire message through the session as if it arrived on a stream.

Parameters

message	The message to process.
origin_stream	Optional stream the message is attributed to.

Returns

An awaitable that resolves once the message has been processed.

Done()

a11::Task a11::service::Session::Done

(

)

const

Await the session's full completion.

Returns

An awaitable that resolves once every stream and action has finished.

GetAction()

absl::StatusOr< std::shared_ptr< actions::Action > > a11::service::Session::GetAction

(

std::string_view

action_id

)

const

Look up a running action by id.

Parameters

action_id

The action identifier.

Returns

The action, or an error status if none matches.

GetActionRegistry()

std::shared_ptr< actions::ActionRegistry > a11::service::Session::GetActionRegistry

(

)

const

Return the registry used to resolve incoming action messages.

Returns

The action registry (may be null).

GetId()

std::string a11::service::Session::GetId

(

)

const

Return the session's unique identifier.

Returns

The id string; use it to correlate the session with logs and traces.

GetNodeMap()

std::shared_ptr< nodes::NodeMap > a11::service::Session::GetNodeMap

(

)

const

Return the NodeMap backing this session's node state.

Returns

The node map dispatched fragments are applied to.

GetStatus()

absl::Status a11::service::Session::GetStatus

(

)

const

Return the session's terminal status.

Returns

Whether it completed successfully or was aborted.

GetStream()

absl::StatusOr< std::shared_ptr< net::WireStream > > a11::service::Session::GetStream

(

std::string_view

stream_id

)

const

Look up an attached stream by id.

Parameters

stream_id

The stream identifier.

Returns

The stream, or an error status if no such stream exists (it may have been removed since last observed).

HalfClose()

absl::Status a11::service::Session::HalfClose

(

)

Signal that this side will send no more messages.

Returns

OK, or an error status on failure. The session drains and finishes once peers do the same; inbound messages keep processing.

Initialize()

absl::Status a11::service::Session::Initialize ( const std::shared_ptr< Session > &  self, std::string  session_id, OnSessionStreamMessage  on_stream_message, OnSessionStreamDone  on_stream_done, data::ByteMap  headers, SessionOptions  options, std::shared_ptr< nodes::NodeMap >  node_map, std::shared_ptr< actions::ActionRegistry >  action_registry  )

protected

IsClosed()

bool a11::service::Session::IsClosed

(

)

const

Report whether the session has been closed.

Returns

True if it no longer accepts new streams or messages.

IsDone()

bool a11::service::Session::IsDone

(

)

const

Report whether the session has fully finished.

Returns

True once every stream and action has completed; prefer awaiting Done() over polling this.

Send()

absl::Status a11::service::Session::Send	(	data::WireMessage	message,
		std::string_view	stream_id = {}
	)

Enqueue a wire message for delivery.

Parameters

message	The message to send.
stream_id	Target stream; the default stream when empty.

Returns

OK, or an error status on failure. Delivery happens asynchronously as the stream drains.

SetActionRegistry()

absl::Status a11::service::Session::SetActionRegistry

(

std::shared_ptr< actions::ActionRegistry >

registry

)

Replace the registry used to resolve incoming action messages.

Active actions are rebound for subsequent nested-name resolution. Prefer configuring this before dispatch so one operation does not observe registrations from different registry versions.

Parameters

registry

The new registry.

Returns

OK, or an error status on failure.

SetDeadline()

absl::Status a11::service::Session::SetDeadline

(

absl::Time

deadline = absl::InfiniteFuture()

)

Set the absolute deadline after which the session is aborted.

Parameters

deadline

The new deadline; the infinite future clears it.

Returns

OK, or an error status on failure.

SetNodeMap()

absl::Status a11::service::Session::SetNodeMap

(

std::shared_ptr< nodes::NodeMap >

node_map

)

Replace the NodeMap backing this session's node state.

Active actions are rebound, but fragments already stored in the previous map are not migrated. Configure this before traffic to avoid splitting a live action's state between maps.

Parameters

node_map

The new node map.

Returns

OK, or an error status on failure.

Streams()

absl::StatusOr< std::vector< std::pair< std::string, std::shared_ptr< net::WireStream > > > > a11::service::Session::Streams

(

)

const

Return the streams currently attached to the session.

Returns

A snapshot of (stream_id, stream) pairs; streams come and go asynchronously, so treat it as point-in-time.

Friends And Related Symbol Documentation

actions::Action

friend class actions::Action

friend

---

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

• cpp/a11/service/session.h
• cpp/a11/service/session.cc