NNet::NActors::TActorSystem Class Reference

Single-threaded actor runtime. More...

#include <actorsystem.hpp>

Public Member Functions
	TActorSystem (TPollerBase *poller, TNodeId nodeId=1, std::function< void(const std::string &)> logger={})
	Constructs the actor system.
TActorId	Register (IActor::TPtr actor)
	Registers an actor and returns its system-wide ID.
TActorId	RegisterWellKnown (TLocalActorId id, IActor::TPtr actor)
	Registers an actor under a fixed local id in [1, FirstDynamicActorId).
auto	Sleep (TTime until)
	Suspends the current coroutine until until. Delegates to the poller.
template<typename Rep, typename Period>
auto	Sleep (std::chrono::duration< Rep, Period > duration)
	Suspends the current coroutine for duration. Delegates to the poller.
void	Send (TActorId sender, TActorId recipient, TMessageId messageId, TBlob blob)
	Low-level send with a pre-serialized blob. Prefer the typed Send<T> overload.
template<typename T, typename... Args>
void	Send (TActorId sender, TActorId recipient, Args &&... args)
	Sends a typed message from sender to recipient (non-blocking).
TEvent	Schedule (TTime when, TActorId sender, TActorId recipient, TMessageId messageId, TBlob blob)
	Low-level schedule with a pre-serialized blob. Prefer the typed Schedule<T> overload.
template<typename T, typename... Args>
TEvent	Schedule (TTime when, TActorId sender, TActorId recipient, Args &&... args)
	Schedules a typed message to be delivered at when.
void	Cancel (TEvent event)
	Cancels a previously scheduled message.
template<typename T, typename TQuestion>
auto	Ask (TActorId recepient, TQuestion &&message)
	Sends a request and returns an awaitable for the reply of type T.
void	YieldNotify ()
	Wakes up the internal scheduler to process newly ready nodes.
size_t	ActorsSize () const
	Returns the number of currently registered (alive) actors.
void	AddNode (int id, std::unique_ptr< INode > node)
	Registers a remote node for distributed message routing.
void	Serve ()
	Starts the actor system event loop for local actors only.
template<typename TSocket, typename TEnvelopeReader = TZeroCopyEnvelopeReader>
void	Serve (TSocket socket)
	Starts the actor system with inbound and outbound network serving.

Static Public Attributes
static constexpr TLocalActorId	FirstDynamicActorId = 128
	Local ids in [1, FirstDynamicActorId) are reserved for well-known actors.
static constexpr TCookie	WellKnownCookie = 0
	Fixed cookie of well-known actors, so any node can build their TActorId.

Friends
class	TActorContext

Detailed Description

Single-threaded actor runtime.

Manages actor registration, message delivery, timers, and (optionally) distributed communication over TCP. All actors run on the single thread that drives the poller — no locking is required inside handlers.

Local-only setup:

TLoop<TDefaultPoller> loop;
TActorSystem sys(&loop.Poller(), 1);
auto id = sys.Register(std::make_unique<MyActor>());
sys.Send<StartMsg>(id, id);
sys.Serve();
loop.Loop();

Distributed setup — call AddNode for each peer, then Serve(socket):

TActorSystem sys(&loop.Poller(), 1);
sys.AddNode(2, std::make_unique<TNode<TDefaultPoller>>(loop.Poller(), TAddress{"::", 9002}));
sys.Serve(std::move(listeningSocket));  // inbound + outbound coroutines
loop.Loop();

Constructor & Destructor Documentation

TActorSystem()

NNet::NActors::TActorSystem::TActorSystem ( TPollerBase * poller, TNodeId nodeId = 1, std::function< void(const std::string &)> logger = {} )

inline

Constructs the actor system.

Parameters

poller	Poller used for timers and I/O. Must outlive this object.
nodeId	This node's identifier (default 1). Must be unique across all processes in a distributed cluster.

Member Function Documentation

AddNode()

void NNet::NActors::TActorSystem::AddNode	(	int	id,
		std::unique_ptr< INode >	node )

Registers a remote node for distributed message routing.

Messages sent to an actor whose NodeId() equals id are serialized and forwarded via this node's outbound buffer. Must be called before Serve(TSocket).

Parameters

id	Node identifier matching the remote process's nodeId.
node	Transport handle (e.g. TNode<TDefaultPoller>).

Ask()

template<typename T, typename TQuestion>

auto NNet::NActors::TActorSystem::Ask ( TActorId recepient, TQuestion && message )

inline

Sends a request and returns an awaitable for the reply of type T.

Registers a temporary one-shot actor that captures the reply and self-destructs via TPoison. Must be co_await-ed inside ICoroActor::CoReceive or an async TBehavior::Receive.

Template Parameters

T	Expected reply message type.
TQuestion	Request message type.

Parameters

recepient	Actor to send the question to.
message	Request message forwarded to Send.

Returns

Awaitable that resolves to T when the reply arrives.

auto reply = co_await sys.Ask<Pong>(pingActor, Ping{});

Cancel()

void NNet::NActors::TActorSystem::Cancel

(

TEvent

event

)

Cancels a previously scheduled message.

Safe to call even if the message has already been delivered.

Parameters

event

Handle returned by Schedule().

Register()

TActorId NNet::NActors::TActorSystem::Register

(

IActor::TPtr

actor

)

Registers an actor and returns its system-wide ID.

Takes ownership of the actor. The returned TActorId is valid until TPoison is delivered or the system is destroyed. Slots are reused with a bumped cookie to prevent stale delivery.

Parameters

actor

Unique pointer to the actor (ownership transferred).

Returns

Globally unique ID for this actor.

RegisterWellKnown()

TActorId NNet::NActors::TActorSystem::RegisterWellKnown	(	TLocalActorId	id,
		IActor::TPtr	actor )

Registers an actor under a fixed local id in [1, FirstDynamicActorId).

The resulting id is TActorId{nodeId, id, WellKnownCookie}, so other nodes can address the actor without any discovery. The id must be free.

Schedule()

template<typename T, typename... Args>

TEvent NNet::NActors::TActorSystem::Schedule ( TTime when, TActorId sender, TActorId recipient, Args &&... args )

inline

Schedules a typed message to be delivered at when.

Parameters

when	Absolute time point for delivery.
sender	Actor ID for the scheduled message.
recipient	Destination actor ID.
args	Constructor arguments forwarded to T.

Returns

Event handle — pass to Cancel() to abort before delivery.

Send()

template<typename T, typename... Args>

void NNet::NActors::TActorSystem::Send ( TActorId sender, TActorId recipient, Args &&... args )

inline

Sends a typed message from sender to recipient (non-blocking).

Routes automatically: local actors receive via their mailbox; remote actors (different NodeId) are serialized and queued to the outbound node buffer. Delivery happens on the next event-loop iteration.

Template Parameters

T	Message type; must have static TMessageId MessageId. If it declares using LocalMessage = ...; it is never serialized for the wire and sending it to another node is dropped (logged).

Parameters

sender	Actor ID that appears as ctx->Sender() in the handler.
recipient	Destination actor ID.
args	Constructor arguments forwarded to T.

Serve() [1/2]

void NNet::NActors::TActorSystem::Serve

(

)

Starts the actor system event loop for local actors only.

Schedules background coroutines that call ExecuteSync and GcIterationSync on every poller tick. Use when there are no remote nodes. For distributed setups use Serve(TSocket) instead.

Serve() [2/2]

template<typename TSocket, typename TEnvelopeReader = TZeroCopyEnvelopeReader>

void NNet::NActors::TActorSystem::Serve ( TSocket socket )

inline

Starts the actor system with inbound and outbound network serving.

Calls Serve() for local processing, then launches:

• An inbound accept loop on socket for messages from remote nodes.
• One outbound coroutine per node registered via AddNode() to drain outbound message buffers.

Parameters

socket

Bound, listening socket for inbound connections.

YieldNotify()

void NNet::NActors::TActorSystem::YieldNotify

(

)

Wakes up the internal scheduler to process newly ready nodes.

Called automatically after enqueuing a message to a remote node. Not intended for direct use in application code.

---

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

• coroio/actors/actorsystem.hpp
• coroio/actors/actorsystem.cpp