#include <qb/actor.h>

Inheritance diagram for qb::Actor:

Classes
class	EventBuilder
	Helper to build Events. More...

Protected Member Functions
Registered Event
void	on (KillEvent const &event)
	Receiving this event will kill the Actor. More...

Construction/Destruction
	Actor ()=default

virtual	~Actor ()=default

virtual bool	onInit ()=0
	DerivedActor should implement this method. More...

void	kill () const

Public Accessors
ActorId	id () const

uint16_t	getIndex () const

uint64_t	time () const
	Get current time. More...

bool	isAlive () const
	Check if Actor is alive. More...

Public Member Functions
This part describes how to manage Actor loop callback, events registration, several ways to send events and create referenced actors.
template<typename _Actor >
void	registerCallback (_Actor &actor) const
	Register a looped callback. More...

template<typename _Actor >
void	unregisterCallback (_Actor &actor) const
	Unregister actor callback. More...

template<typename _Event , typename _Actor >
void	registerEvent (_Actor &actor)
	Actor will listen on new _Event. More...

template<typename _Event , typename _Actor >
void	unregisterEvent (_Actor &actor)
	Actor will stop listening _Event. More...

EventBuilder	to (ActorId const dest) const
	Get EventBuilder for ActorId destination. More...

template<typename _Event , typename ... _Args>
_Event &	push (ActorId const &dest, _Args &&...args) const
	Send a new ordered event. More...

template<typename _Event , typename ... _Args>
void	send (ActorId const &dest, _Args &&...args) const
	Send a new unordered event. More...

void	reply (Event &event) const
	Reply an event. More...

void	forward (ActorId const dest, Event &event) const
	Forward an event. More...

ProxyPipe	getPipe (ActorId const dest) const
	Get access to unidirectional out events pipe. More...

template<typename _Actor , typename ... _Args>
_Actor *	addRefActor (_Args &&...args) const
	Create new referenced _Actor. More...

Detailed Description

Actor base class.

The Actor sends event messages to be received by another Actor, which is then treated by an Event handler.
All UserActors should inherit from Actor class.

Constructor & Destructor Documentation

◆ Actor()

qb::Actor::Actor ( )

protecteddefault

◆ ~Actor()

virtual qb::Actor::~Actor ( )

protectedvirtualdefault

Member Function Documentation

◆ onInit()

virtual bool qb::Actor::onInit ( )

protectedpure virtual

DerivedActor should implement this method.

Returns: true on init success then false

example:

virtual bool onInit() {
  // register events and callback here
  // can also create actors
  // ...
  return true
}

Attention: /!\ If initialization has failed DerivedActor will not be added to the engine

◆ kill()

void qb::Actor::kill ( ) const

Kill the Actor

◆ on()

void qb::Actor::on ( KillEvent const & event )

protected

Receiving this event will kill the Actor.

Parameters

event received event

This event can be overloaded by DerivedActor.
example:

// ...
registerEvent<qb::KillEvent>(*this);
// DerivedActor should also define the event callback
void on(qb::KillEvent &event) {
  // do something before killing actor
  kill();
}

Attention: /!\ Do not forget to call kill on overloaded function.

◆ id()

ActorId qb::Actor::id ( ) const

inline

Get current ActorId

Returns: ActorId

◆ getIndex()

uint16_t qb::Actor::getIndex ( ) const

Get current core index

Returns: core index

◆ time()

uint64_t qb::Actor::time ( ) const

Get current time.

Returns: nano timestamp since epoch

Note: This value is optimized and updated each VirtualCore loop.
// ...
auto t1 = time();
// ... some heavy calculation
assert(t1 == time()); // true - will not assert
To get precise time use NanoTimestamp.

◆ isAlive()

bool qb::Actor::isAlive ( ) const

Check if Actor is alive.

Returns: true if Actor is alive else false

◆ registerCallback()

template<typename _Actor >

void qb::Actor::registerCallback ( _Actor & actor ) const

Register a looped callback.

Parameters

actor reference of DerivedActor

The registered callback will be called each VirtualCore loop.
_Actor must inherit and implement ICallback interface.
example:

class MyActor
: public qb::Actor
, public qb::ICallback
{
  virtual bool onInit() {
    registerCallback(*this);
  }
// ...
  virtual void onCallback() override final {
    // do something
  }
}
// ...
}

◆ unregisterCallback()

template<typename _Actor >

void qb::Actor::unregisterCallback ( _Actor & actor ) const

Unregister actor callback.

Parameters

actor reference of DerivedActor

example:

unregisterCallback(*this);

◆ registerEvent()

template<typename _Event , typename _Actor >

void qb::Actor::registerEvent ( _Actor & actor )

Actor will listen on new _Event.

Template Parameters

_Event DerivedEvent type

Parameters

actor reference of DerivedActor

example:

virtual bool onInit() {
  registerEvent<MyEvent>(*this);
  // ...
}

Note: _Actor must define the callback event function.
void on(MyEvent &event) {
// do something
}

◆ unregisterEvent()

template<typename _Event , typename _Actor >

void qb::Actor::unregisterEvent ( _Actor & actor )

Actor will stop listening _Event.

Template Parameters

_Event DerivedEvent type

Parameters

actor reference of DerivedActor

example:

unregisterEvent<MyEvent>(*this);

◆ to()

EventBuilder qb::Actor::to ( ActorId const dest ) const

Get EventBuilder for ActorId destination.

Parameters

dest	ActorId destination

Returns: EventBuilder

A way to push chained events to destination Actor.
example:

to(destId)
.push<MyEvent1>()
.push<MyEvent2>(param1, param2)
// ...
;

Attention: auto builder1 = main.to(sameid);
auto builder2 = main.to(sameid);
// builder1 == builder2 -> true

◆ push()

template<typename _Event , typename ... _Args>

_Event& qb::Actor::push	(	ActorId const &	dest,
		_Args &&...	args
	)		const

Send a new ordered event.

Template Parameters

_Event DerivedEvent type

Parameters

dest	destination ActorId
args	arguments to forward to the constructor of the _Event

Returns: a reference to the constructed _Event to send

All events pushed to same actors id in context will be received ordered by push order.
example:

// ...
auto &e = push<MyEvent>(id_1); // (1) first push
e.some_data = 1337; // set my event data without using constructor
push<MyEvent>(id_2, param2); // (2) id_2 != id_1 /!\ possible to be received before (1)
push<MyEvent>(id_1, param3); // (3) Guaranteed to be received after (1)
// ...

Note: Pushed events are sent at the end of the core loop.

Attention: /!\ We recommend to non advanced users to use only this function to send events.

◆ send()

template<typename _Event , typename ... _Args>

void qb::Actor::send	(	ActorId const &	dest,
		_Args &&...	args
	)		const

Send a new unordered event.

Template Parameters

_Event DerivedEvent type

Parameters

dest	destination ActorId
args	arguments to forward to the constructor of the _Event

All events sent using send function are not guaranteed to be received in order.
example:

// ...
send<MyEvent>(id_1, param1); // (1)
send<MyEvent>(id_1, param2); // (2)
send<MyEvent>(id_1, param3); // (3)
// Actor with id_1 will receive events in random order
// ...

Note: send may be faster than push in some cases.

Attention: /!\ We recommend to non advanced users to not use this function to send events.

◆ reply()

void qb::Actor::reply ( Event & event ) const

Reply an event.

Parameters

event any received event

example:

// ...
void on(MyEvent &event) {
  // do something...
  reply(event);
}

Note: Replying an event is faster than pushing a new one.

◆ forward()

void qb::Actor::forward	(	ActorId const	dest,
		Event &	event
	)		const

Forward an event.

Parameters

dest	destination ActorId
event	any received event

example:

// ...
void on(MyEvent &event) {
  // do something...
  forward(id_1, event);
}

Note: Forwarding an event is faster than pushing a new one.

◆ getPipe()

ProxyPipe qb::Actor::getPipe ( ActorId const dest ) const

Get access to unidirectional out events pipe.

Parameters

dest	destination ActorId

Returns: destination ProxyPipe

If you want to send several events to same Actor or push dynamic sized events,
Actor API allows to retrieve a ProxyPipe to a desired Actor.
more details on ProxyPipe section

◆ addRefActor()

template<typename _Actor , typename ... _Args>

_Actor* qb::Actor::addRefActor ( _Args &&... args ) const

Create new referenced _Actor.

Template Parameters

_Actor DerivedActor type

Parameters

args	arguments to forward to the constructor of the _Actor

Returns: _Actor * on success or nullptr on failure

create and initialize new _Actor on same VirtualCore as the callee Actor.
example:

auto actor = addRefActor<MyActor>(param1, param2);
if (actor) {
  // actor was created and pushed to the engine
}

Note: Referenced actors can be used as a normal C++ class, the parent Actor can make direct calls to created actors "on" functions.
This is very useful to limit the number of events managed by the engine then improve global performance.

Classes

Protected Member Functions

Construction/Destruction

Public Accessors

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Actor()

◆ ~Actor()

Member Function Documentation

◆ onInit()

◆ kill()

◆ on()

◆ id()

◆ getIndex()

◆ time()

◆ isAlive()

◆ registerCallback()

◆ unregisterCallback()

◆ registerEvent()

◆ unregisterEvent()

◆ to()

◆ push()

◆ send()

◆ reply()

◆ forward()

◆ getPipe()

◆ addRefActor()