zmqpp  4.1.2
C++ bindings for 0mq (libzmq)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Public Types | Public Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
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:
Collaboration graph
[legend]

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...
 
actoroperator= (actor &&o)
 Move-assignment operator. More...
 
virtual ~actor ()
 
socketpipe ()
 
const socketpipe () 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

socketparent_pipe_
 The parent thread socket. More...
 
socketchild_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
routineto 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
childa copy of child_pipe_.
routineuser 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
blockwhether 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: