Detailed Description

An accessor class for an ActionEngine action.

This class provides an interface for creating and managing actions in the ActionEngine V2 format. It includes methods for setting up input and output nodes, calling the action, and running the action handler.

#include <actionengine/actions/action.h>

Public Member Functions
	Action (ActionSchema schema, std::string_view id="", std::vector< Port > inputs={}, std::vector< Port > outputs={})
	Constructor. Creates an action in the context given by `node_map`, `stream`, and `session`.

ActionMessage	GetActionMessage () const
	Makes an action message to be sent on a WireStream.

AsyncNode *absl_nullable	GetNode (std::string_view id)
	Gets an AsyncNode with the given `id` from the node map.

AsyncNode *absl_nullable	GetInput (std::string_view name, std::optional< bool > bind_stream=std::nullopt)
	Gets an AsyncNode input with the given name from the node map. If no input with the given name is found, returns nullptr.

AsyncNode *absl_nullable	GetOutput (std::string_view name, const std::optional< bool > bind_stream=std::nullopt)
	Gets an AsyncNode output with the given name from the node map. If no output with the given name is found, returns nullptr.

void	BindHandler (ActionHandler handler)
	Sets the action handler.

NodeMap *absl_nullable	GetNodeMap () const

void	BindStream (WireStream *absl_nullable stream)
	Binds a given stream to the action.

WireStream *absl_nullable	GetStream () const

void	BindSession (Session *absl_nullable session)
	Binds a session to the action.

Session *absl_nullable	GetSession () const

std::unique_ptr< Action >	MakeActionInSameSession (std::string_view name, std::string_view action_id="") const
	Makes a different action in the same session. Should be used to create nested actions.

ActionRegistry *absl_nullable	GetRegistry () const

std::string	GetId () const

absl::Status	Await (absl::Duration timeout=absl::InfiniteDuration())
	Block until the action has been completed, either by being run or called.

absl::Status	Call ()
	Calls the action by sending an ActionEngine action message to associated stream.

absl::Status	Run ()
	Run the action handler. Clients usually do not call this method directly.

void	ClearInputsAfterRun (bool clear=true)
	Specifies whether the action should delete its input nodes from its bound node map after it's run.

void	ClearOutputsAfterRun (bool clear=true)
	Specifies whether the action should delete its output nodes from its bound node map after it's run.

void	Cancel () const
	Cancels the action and all its inputs.

thread::Case	OnCancel () const
	Returns a thread::Case that handlers can use to synchronise with cancellation.

bool	Cancelled () const
	Returns whether the action has been cancelled.

Constructor & Destructor Documentation

◆ Action()

act::Action::Action	(	ActionSchema	schema,
		std::string_view	id = "",
		std::vector< Port >	inputs = {},
		std::vector< Port >	outputs = {} )

explicit

Constructor. Creates an action in the context given by node_map, stream, and session.

Creates an action with the given schema, handler, ID, node map, stream, and session. The ID is generated if not provided, and other parameters are nullable, and if not provided, restrictions apply, however, it makes the Action class unified for client and server-side usage.

Parameters

schema	The action schema. Required to resolve input and output node types, as well as to create the action message on call.
id	The action ID. If empty, a unique ID will be generated.
inputs	A mapping of input names to node IDs. If empty, the IDs will be generated based on the schema.
outputs	A mapping of output names to node IDs. If empty, the IDs will be generated based on the schema.

Member Function Documentation

◆ Await()

absl::Status act::Action::Await ( absl::Duration timeout = absl::InfiniteDuration() )

Block until the action has been completed, either by being run or called.

If previously Run(), this method waits on a condition variable until the action handler has completed and returns the resulting status.

If previously Call()-ed, this method waits until the status arrives to a special reserved output node named "__status__", and returns it.

Returns: The status returned by the action handler, or the error status if the handler failed.

◆ BindHandler()

void act::Action::BindHandler ( ActionHandler handler )

inline

Sets the action handler.

Parameters

handler The action handler. This function will be called when the action is run server-side or manually via Run().

◆ BindSession()

void act::Action::BindSession ( Session *absl_nullable session )

Binds a session to the action.

The session provides the action with an ActionRegistry to resolve nested actions by name, and is accessible to the action handler in case it needs to do custom logic based on the session.

Parameters

session The session to bind the action to. If nullptr, the action will not be bound to any session.

◆ BindStream()

void act::Action::BindStream ( WireStream *absl_nullable stream )

Binds a given stream to the action.

The bound stream will be used to send the action message when Call() is invoked, and attach to output nodes when Run() is invoked, so that the nodes can send their data to the stream for another connected party over the network.

Parameters

stream The stream to bind the action to. If nullptr, the action will not be bound to any stream.

◆ Call()

absl::Status act::Action::Call ( )

Calls the action by sending an ActionEngine action message to associated stream.

This method should normally be called by the client. It only creates the message and sends it to the stream. The action handler is not called by this method. It makes sure that input nodes are bound to the stream.

Returns: The status of sending the action call message.

◆ Cancel()

void act::Action::Cancel ( ) const

inline

Cancels the action and all its inputs.

This method will cancel all input nodes and notify the action handler that the action has been cancelled. It is safe to call this method multiple times, as it will only notify once.

Cancelling input nodes means stopping background prefetcher fibers and setting reader status to Cancelled. Any cached data will still be available to the action handler, but no new data will be fetched.

Any output nodes will not be cancelled, as they do not introduce blocking behavior in the action handler. It is the handler's responsibility to check for cancellation and stop processing if needed. However, if the handler terminates with an error, non-OK statuses will be sent to the output nodes.

◆ Cancelled()

bool act::Action::Cancelled ( ) const

nodiscard

Returns whether the action has been cancelled.

Returns: True if the action has been cancelled, via .Cancel(), false otherwise.

◆ GetActionMessage()

ActionMessage act::Action::GetActionMessage ( ) const

nodiscard

Makes an action message to be sent on a WireStream.

Returns: The action message.

◆ GetId()

std::string act::Action::GetId ( ) const

inlinenodiscard

Returns the action's identifier.

◆ GetInput()

AsyncNode *absl_nullable act::Action::GetInput	(	std::string_view	name,
		std::optional< bool >	bind_stream = std::nullopt )

Gets an AsyncNode input with the given name from the node map. If no input with the given name is found, returns nullptr.

Parameters

name	The name of the input to get.
bind_stream	If true, the stream will be bound to the input node. If unspecified, the stream will be bound in Call(), but not Run().

Returns: A pointer to the AsyncNode of the input with the given name, or nullptr if not on ActionSchema.

◆ GetNode()

AsyncNode *absl_nullable act::Action::GetNode ( std::string_view id )

Gets an AsyncNode with the given id from the node map.

The node does not have to be defined as an input or output of the action. If id does not exist on the action's schema, returns nullptr.

Parameters

id	The identifier of the node to get.

Returns: A pointer to the AsyncNode with the given id.

◆ GetNodeMap()

NodeMap *absl_nullable act::Action::GetNodeMap ( ) const

nodiscard

Returns the node map associated with the action.

◆ GetOutput()

AsyncNode *absl_nullable act::Action::GetOutput	(	std::string_view	name,
		const std::optional< bool >	bind_stream = std::nullopt )

inline

Gets an AsyncNode output with the given name from the node map. If no output with the given name is found, returns nullptr.

Parameters

name	The name of the output to get.
bind_stream	Whether to bind the stream to the output. If not specified, the stream will be bound in Run() but not in Call().

Returns: A pointer to the AsyncNode of the output with the given name, or nullptr if not on ActionSchema.

◆ GetRegistry()

ActionRegistry * act::Action::GetRegistry ( ) const

nodiscard

Returns the action registry from the session.

◆ GetSession()

Session *absl_nullable act::Action::GetSession ( ) const

nodiscard

Returns the session bound to the action.

◆ GetStream()

WireStream *absl_nullable act::Action::GetStream ( ) const

nodiscard

Returns the stream bound to the action.

◆ MakeActionInSameSession()

std::unique_ptr< Action > act::Action::MakeActionInSameSession	(	std::string_view	name,
		std::string_view	action_id = "" ) const

Makes a different action in the same session. Should be used to create nested actions.

An action created in this way will share the same session, node map, and stream as the current action.

Parameters

name	The name of the action to create. It must be registered in the session's action registry.
action_id	The ID of the action to create. If empty, a unique ID will be generated.

Returns: An owning pointer to the new action.

◆ OnCancel()

thread::Case act::Action::OnCancel ( ) const

inline

Returns a thread::Case that handlers can use to synchronise with cancellation.

Returns: A thread::Case that can be used to wait for cancellation in a thread::Select() or thread::SelectUntil() call.

◆ Run()

absl::Status act::Action::Run ( )

Run the action handler. Clients usually do not call this method directly.

Servers may want to call this method if they implement custom Session and/or Service logic. This method will call the action handler and make sure output nodes are bound to the stream.

Returns: The status returned by the action handler.

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

/Users/helenapankov/dev/actionengine/src/actionengine/actions/action.h
/Users/helenapankov/dev/actionengine/src/actionengine/actions/action.cc

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ Action()

Member Function Documentation

◆ Await()

◆ BindHandler()

◆ BindSession()

◆ BindStream()

◆ Call()

◆ Cancel()

◆ Cancelled()

◆ GetActionMessage()

◆ GetId()

◆ GetInput()

◆ GetNode()

◆ GetNodeMap()

◆ GetOutput()

◆ GetRegistry()

◆ GetSession()

◆ GetStream()

◆ MakeActionInSameSession()

◆ OnCancel()

◆ Run()