zmqpp::actor Class Reference

An actor is a thread with a pair socket connected to its parent. More...

#include <actor.hpp>

Collaboration diagram for zmqpp::actor:

Public Types
typedef std::function< bool(socket *pipe) >	ActorStartRoutine
	The user defined function type. More...

Public Member Functions
	actor (ActorStartRoutine routine)
	Create a new actor. More...
	actor (const actor &)=delete
	actor (actor &&o)
	Move constructor. More...
actor &	operator= (actor &&o)
	Move-assignment operator. More...
virtual	~actor ()
socket *	pipe ()
const socket *	pipe () const
bool	stop (bool block=false)
	Sends signal::stop to the actor thread. More...

Private Member Functions
void	start_routine (socket *child, ActorStartRoutine routine)
	Call a user defined function and performs cleanup once it returns. More...
std::string	bind_parent ()
	Bind the parent socket and return the endpoint used. More...

Private Attributes
socket *	parent_pipe_
	The parent thread socket. More...
socket *	child_pipe_
	The child end of the pipe. More...
bool	stopped_
	Keeps track of the status of the actor thread. More...
bool	retval_

Static Private Attributes
static context	actor_pipe_ctx_
	This static, per process zmqpp::context, is used to connect PAIR socket between Actor and their parent thread. More...

Detailed Description

An actor is a thread with a pair socket connected to its parent.

It aims to be similar to CMZQ's zactor.

From the parent thread, instancing an actor will spawn a new thread, and install a pipe between those two threads.

1. The parent's end of the pipe can be retrieved by calling pipe() on the actor.
2. The child's end is passed as a parameter to the routine executed in the child's thread.

You don't have to manage the 2 PAIR sockets. The parent's one will be destroyed when the actor dies, and the child's end is taken care of when the user routine ends.

Note

About user-supplied routine return value:

1. If the supplied routine returns true, signal::ok will be send to the parent.
2. If it returns false, signal::ko is send instead.

There is a simple protocol between actor and parent to avoid synchronization problem:

1. The actor constructor expect to receive either signal::ok or signal::ko before it returns.
2. When sending signal::stop (actor destruction or by calling stop()), we expect a response: (either signal::ko or signal::ok). This response is used to determine if stop() will return true or false when in blocking mode.

Member Typedef Documentation

typedef std::function<bool (socket *pipe) > zmqpp::actor::ActorStartRoutine

The user defined function type.

Constructor & Destructor Documentation

zmqpp::actor::actor

(

ActorStartRoutine

routine

)

Create a new actor.

This will effectively create a new thread and runs the user supplied routine. The constructor expect a signal from the routine before returning.

Expect to receive either signal::ko or signal::ok before returning. If it receives signal::ko, it will throw.

Parameters

routine

to be executed.

zmqpp::actor::actor ( const actor &  )

delete

zmqpp::actor::actor

(

actor &&

o

)

Move constructor.

The other actor will not be usable anymore. Its pipe() method shall return null, and stop() will do nothing.

zmqpp::actor::~actor ( )

virtual

Member Function Documentation

std::string zmqpp::actor::bind_parent ( )

private

Bind the parent socket and return the endpoint used.

Since endpoint are generated and have to be tested for availability this method is reponsible for finding a valid endpoint to bind to.

actor & zmqpp::actor::operator=

(

actor &&

o

)

Move-assignment operator.

See also

move constructor.

socket * zmqpp::actor::pipe

(

)

Returns

pointer to the parent's end of the pipe

const socket * zmqpp::actor::pipe

(

)

const

Returns

const pointer to the parent's end of the pipe

void zmqpp::actor::start_routine ( socket *  child, ActorStartRoutine  routine  )

private

Call a user defined function and performs cleanup once it returns.

We use a copy of child_pipe_ here; this is to avoid a race condition where the destructor would be called before start_routine finishes but after it sent signal::ok / signal::ko. The actor object would be invalid (because already destroyed).

Parameters

child	a copy of child_pipe_.
routine	user routine that will be called

bool zmqpp::actor::stop

(

bool

block = false

)

Sends signal::stop to the actor thread.

The actor thread shall stop as soon as possible. The return value is only relevant when block is true. If block is false (the default), this method will return true.

It is safe to call stop() multiple time (to ask the actor to shutdown, and then a bit later call stop(true) to make sure it is really stopped)

Note

calling this method on an "empty" actor (after it was moved) will return false and nothing will happen.

Parameters

block

whether or not we wait until the actor thread stops.

Returns

a boolean indicating whether or not the actor successfully shutdown.

Member Data Documentation

zmqpp::context zmqpp::actor::actor_pipe_ctx_

staticprivate

This static, per process zmqpp::context, is used to connect PAIR socket between Actor and their parent thread.

socket* zmqpp::actor::child_pipe_

private

The child end of the pipe.

It is closed and freed when the routine ran by the actor ends.

socket* zmqpp::actor::parent_pipe_

private

The parent thread socket.

This socket will be closed and freed by the actor destructor.

bool zmqpp::actor::retval_

private

bool zmqpp::actor::stopped_

private

Keeps track of the status of the actor thread.

---

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

• src/zmqpp/actor.hpp
• src/zmqpp/actor.cpp