act::WireStream Class Reference

Detailed Description

An abstract base class for an ActionEngine stream.

This class provides an interface for sending and receiving messages over a stream. It is intended to be used as a base class for specific stream implementations, such as WebSocket or gRPC streams.

#include <actionengine/net/stream.h>

Inheritance diagram for act::WireStream:

Public Member Functions
virtual auto	Send (WireMessage message) -> absl::Status=0
virtual auto	Receive (absl::Duration timeout) -> absl::StatusOr< std::optional< WireMessage > >=0
virtual auto	Accept () -> absl::Status=0
virtual auto	Start () -> absl::Status=0
virtual void	HalfClose ()=0
virtual void	Abort ()=0
virtual auto	GetStatus () const -> absl::Status=0
virtual auto	GetId () const -> std::string=0
virtual auto	GetImpl () const -> const void *
template<typename T>
auto	GetImpl () const -> T *

Member Function Documentation

Abort()

virtual void act::WireStream::Abort ( )

pure virtual

Aborts the stream.

This is used to terminate the stream immediately with an "error" state. For example, the result of Receive() following an Abort() call by either side should be an error status, indicating that the stream is no longer usable, and not an empty optional.

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

Accept()

virtual auto act::WireStream::Accept ( ) -> absl::Status

pure virtual

Accepts the stream on the server side.

Clients should not call this method. It is intended to be called by the server to accept a stream that has been initiated by a client. Implementations that differentiate between client and server streams are allowed to return an error if this method is called on a client, or even to perform a hard termination of the process, as such a call is considered a misuse of the API.

Some implementations may not require this method, in which case they can return an OK status without doing anything.

Returns

An OK status if the stream is successfully accepted, or an error status if the stream cannot be accepted (e.g., if it is already accepted, or some underlying negotiation failed).

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

GetId()

virtual auto act::WireStream::GetId ( ) const -> std::string

nodiscardpure virtual

Returns the unique (in this process) identifier of the stream.

Returns

A string representing the unique identifier of the stream. This identifier is used to distinguish between different streams in the same process, but not across a load balanced group, for example.

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

GetImpl() [1/2]

virtual auto act::WireStream::GetImpl ( ) const -> const void*

inlinenodiscardvirtual

Returns the underlying implementation of the stream.

This function is intended to be overridden by derived classes to provide access to the specific implementation of the stream, in case such access is required. The default implementation returns a null pointer.

Returns

A pointer to the underlying implementation of the stream.

Reimplemented in act::net::WebRtcWireStream, and act::net::WebsocketWireStream.

GetImpl() [2/2]

template<typename T>

auto act::WireStream::GetImpl ( ) const -> T*

inlinenodiscard

Returns the underlying implementation of the stream.

This function is a template that allows the user to specify the type of the underlying implementation. It uses static_cast to convert the void* pointer returned by GetImpl() to the specified type.

Template Parameters

T	The type of the underlying implementation.

Returns

A pointer to the underlying implementation of type T.

GetStatus()

virtual auto act::WireStream::GetStatus ( ) const -> absl::Status

pure virtual

Returns the status of the stream.

This method is used to check the current status of the stream, which is OK unless the stream has been aborted.

Returns

An absl::Status indicating the current status of the stream. If the stream is in a valid state, it returns absl::OkStatus(). If the stream is in an error state (e.g., due to an abort), it returns an appropriate error status.

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

HalfClose()

virtual void act::WireStream::HalfClose ( )

pure virtual

Communicates to the other end that no more messages will be sent over this stream.

Note

This method does not close the stream, nor does it initiate a finalisation. It simply indicates that no more messages will be sent. The stream remains open for receiving messages, and the other end can still send messages until it also calls HalfClose() or closes the stream.

Nor does this method guarantee that the other end will receive the half-close message immediately, or at all. However, if the stream is indeed broken, GetStatus() will return an error status, and Send() and Receive() will return errors as well if a stream is in a state where they cannot proceed.

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

Receive()

virtual auto act::WireStream::Receive ( absl::Duration timeout ) -> absl::StatusOr< std::optional< WireMessage > >

pure virtual

Receives an ActionEngine wire message from the stream.

Blocks to wait for a message to be received, up to the specified timeout.

Parameters

timeout

The maximum duration to wait for a message to be received. If the timeout is reached, the function will return an absl::DeadlineExceededError.

Returns

An optional WireMessage if a message is received within the specified timeout. An empty optional indicates that no message will be received.

Note

Correct implementations of this method should return an empty optional if the stream is half-closed, and no more messages can be received. If the stream is aborted (e.g., due to an error), the method should return an error status.

Implementations MUST ensure that this method reacts to an Abort() call, returning an error status and not blocking indefinitely. This is important in the inner workings of the ActionEngine, where Receive() is called in a loop, and the loop should be able to terminate gracefully when the stream is aborted.

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

Send()

virtual auto act::WireStream::Send ( WireMessage message ) -> absl::Status

pure virtual

Sends a WireMessage over the stream.

May or may not block, depending on the implementation. For example, WebsocketWireStream will block until the message is sent, while WebRtcWireStream will return immediately, allowing the message to be sent asynchronously.

With that in mind, the caller should not assume that the message has been sent immediately after this function returns, or even that it has been sent successfully. Failure modes of this method are more about the invariants of the stream itself: for example, if the stream is closed, or half-closed (no more messages can be sent), this method will return an error.

Parameters

message

The WireMessage to send, containing action calls (in the form of multiple ActionMessage) and/or node fragments.

Returns

An OK status unless the stream is in a state where it cannot send messages, such as being half-closed or closed.

Note

Implementations of WireStream should and will treat a WireMessage with no actions or node fragments as an initiation or acknowledgment of a half-close.

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

Start()

virtual auto act::WireStream::Start ( ) -> absl::Status

pure virtual

Starts the stream on the client side.

Clients should call this method to initiate the stream after it has been created. This method is intended to be called by the client to start the stream, which may involve some underlying negotiation or setup. Implementations that differentiate between client and server streams are allowed to return an error if this method is called on a server, or even to perform a hard termination of the process, as such a call is considered a misuse of the API.

Some implementations may not require this method, in which case they can return an OK status without doing anything.

Returns

An OK status if the stream is successfully started, or an error status if the stream cannot be started (e.g., if it is already started, or some underlying negotiation failed).

Implemented in act::net::WebRtcWireStream, act::net::WebsocketWireStream, and act::pybindings::PyWireStream.

---

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

• /Users/helenapankov/dev/actionengine/src/actionengine/net/stream.h