act::pybindings::PyWireStream Class Reference

Detailed Description

A Python subclass of WireStream that allows for custom implementations of the stream methods in Python.

This class is intended to be used as a base class for Python implementations of WireStream. It provides default implementations that call the corresponding Python methods, allowing for easy customization. This is a so-called trampoline class in the sense implied by PyBind11.

Action Engine uses pybind11_abseil's Status bindings, so any absl::Status returned is automatically converted to a Python exception. If the Python method returns a coroutine, the best effort is made to run it in a threadsafe manner, using pybindings::RunThreadsafeIfCoroutine. However, this is not guaranteed to work in all cases, so it is recommended to take extra care when implementing the methods in Python and be aware of potential issues with coroutines.

#include <service_pybind11.h>

Inheritance diagram for act::pybindings::PyWireStream:

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

Member Function Documentation

Abort()

void act::pybindings::PyWireStream::Abort ( )

inlineoverridevirtual

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.

Implements act::WireStream.

Accept()

absl::Status act::pybindings::PyWireStream::Accept ( )

inlineoverridevirtual

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).

Implements act::WireStream.

GetId()

std::string act::pybindings::PyWireStream::GetId ( ) const

inlinenodiscardoverridevirtual

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.

Implements act::WireStream.

GetStatus()

absl::Status act::pybindings::PyWireStream::GetStatus ( ) const

inlineoverridevirtual

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.

Implements act::WireStream.

HalfClose()

void act::pybindings::PyWireStream::HalfClose ( )

inlineoverridevirtual

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.

Implements act::WireStream.

Receive()

absl::StatusOr< std::optional< WireMessage > > act::pybindings::PyWireStream::Receive ( absl::Duration timeout )

inlineoverridevirtual

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.

Implements act::WireStream.

Send()

absl::Status act::pybindings::PyWireStream::Send ( WireMessage message )

inlineoverridevirtual

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.

Implements act::WireStream.

Start()

absl::Status act::pybindings::PyWireStream::Start ( )

inlineoverridevirtual

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).

Implements act::WireStream.

---

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

• /Users/helenapankov/dev/actionengine/src/actionengine/service/service_pybind11.h