Download libcppa - boost.org
Transcript
libcppa A C++ library for actor programming User Manual libcppa version 0.9.0 PRERELEASE Dominik Charousset March 18, 2014 Contents 1 Introduction 1 1.1 Actor Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2.1 Actor Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2.2 Actor Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2.3 Untyped Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2.4 Typed Actor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2.5 Spawning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2.6 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2.7 Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 First Steps 3 2.1 Features Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Supported Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.4 Hello World Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3 Copy-On-Write Tuples 5 3.1 Dynamically Typed Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 Casting Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4 Pattern Matching 4.1 Basics 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 Reducing Redundancy with “arg match” and “on arg match” . . . . . . . . . . . . 8 4.3 Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.4 Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.5 Guards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.5.1 Placeholder Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.5.2 Examples for Guard Expressions . . . . . . . . . . . . . . . . . . . . . . . 10 4.6 Projections and Extractors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5 Actors 12 5.1 Implicit self Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.2 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6 Sending Messages 14 6.1 Replying to Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.2 Delaying Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.3 Forwarding Messages in Untyped Actors 16 . . . . . . . . . . . . . . . . . . . . . . 7 Receiving Messages 17 7.1 Class-based actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.2 Nesting Receives Using become/unbecome . . . . . . . . . . . . . . . . . . . . . 19 7.3 Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.4 Skipping Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 8 Synchronous Communication 8.1 Error Messages 22 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8.2 Receive Response Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.3 Synchronous Failures and Error Handlers . . . . . . . . . . . . . . . . . . . . . . 23 8.3.1 Continuations for Event-based Actors . . . . . . . . . . . . . . . . . . . . 24 9 Management & Error Detection 25 9.1 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 9.2 Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 9.3 Error Codes 26 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.4 Attach Cleanup Code to an Actor . . . . . . . . . . . . . . . . . . . . . . . . . . 26 10 Spawning Actors 27 11 Message Priorities 28 12 Network Transparency 29 12.1 Publishing of Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 12.2 Connecting to Remote Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 13 Group Communication 30 13.1 Anonymous Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 13.2 Local Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 13.3 Spawn Actors in Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 14 Platform-Independent Type System 14.1 User-Defined Data Types in Messages 31 . . . . . . . . . . . . . . . . . . . . . . . 15 Blocking API 31 32 15.1 Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 15.2 Receiving Synchronous Responses . . . . . . . . . . . . . . . . . . . . . . . . . 34 16 Strongly Typed Actors 16.1 Spawning Typed Actors 35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 16.2 Class-based Typed Actors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 17 Common Pitfalls 38 17.1 Event-Based API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 17.2 Synchronous Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 17.3 Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 17.4 Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 17.5 Constructors of Class-based Actors . . . . . . . . . . . . . . . . . . . . . . . . . 38 18 Appendix 39 18.1 Class option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 18.2 Using aout – A Concurrency-safe Wrapper for cout . . . . . . . . . . . . . . . 40 INTRODUCTION 1 Introduction Before diving into the API of libcppa, we would like to take the opportunity to discuss the concepts behind libcppa and to explain the terminology used in this manual. 1.1 Actor Model The actor model describes concurrent entities – actors – that do not share state and communicate only via message passing. By decoupling concurrently running software components via message passing, the actor model avoids race conditions by design. Actors can create – “spawn” – new actors and monitor each other to build fault-tolerant, hierarchical systems. Since message passing is network transparent, the actor model applies to both concurrency and distribution. When dealing with dozens of cores, mutexes, semaphores and other threading primitives are the wrong level of abstraction. Implementing applications on top of those primitives has proven challenging and error-prone. Additionally, mutex-based implementations can cause queueing and unmindful access to (even distinct) data from separate threads in parallel can lead to false sharing – both decreasing performance significantly, up to the point that an application actually runs slower when adding more cores. The actor model has gained momentum over the last decade due to its high level of abstraction and its ability to make efficient use of multicore and multiprocessor machines. However, the actor model has not yet been widely adopted in the native programming domain. With libcppa, we contribute a library for actor programming in C++ as open source software to ease native development of concurrent as well as distributed systems. In this regard, libcppa follows the C++ philosophy “building the highest abstraction possible without sacrificing performance”. 1.2 Terminology You will find that libcppa has not simply adopted exiting implementations based on the actor model such as Erlang or the Akka library. Instead, libcppa aims to provide a modern C++ API allowing for type-safe as well as dynamically typed messaging. Hence, most aspects of our system are familiar to developers having experience with other actor systems, but there are also slight differences in terminology. However, neither libcppa nor this manual require any foreknowledge. 1.2.1 Actor Address In libcppa, each actor has a (network-wide) unique logical address that can be used to identify and monitor it. However, the address can not be used to send a message to an actor. This limitation is due to the fact that the address does not contain any type information about the actor. Hence, it would not be safe to send it any message, because the actor might use a strictly typed messaging interface not accepting the given message. 1 INTRODUCTION 1.2.2 Actor Handle An actor handle contains the address of an actor along with its type information. In order to send an actor a message, one needs to have a handle to it – the address alone is not sufficient. The distinction between handles and addresses – which is unique to libcppa when comparing it to other actor systems – is a consequence of the design decision to support both untyped and typed actors. 1.2.3 Untyped Actors An untyped actor does not constrain the type of messages it receives, i.e., a handle to an untyped actor accepts any kind of message. That does of course not mean that untyped actors must handle all possible types of messages. Choosing typed vs untyped actors is mostly a matter of taste. Untyped actors allow developers to build prototypes faster, while typed actors allow the compiler to fetch more errors at compile time. 1.2.4 Typed Actor A typed actor defines its messaging interface, i.e., both input and output types, in its type. This allows the compiler to check message types statically. 1.2.5 Spawning “Spawning” an actor means to create and run a new actor. 1.2.6 Monitoring A monitored actor sends a “down message” to all actors monitoring it as part of its termination. This allows actors to supervise other actors and to take measures when one of the supervised actors failed, i.e., terminated with a non-normal exit reason. 1.2.7 Link A link is bidirectional connection between two actors. Each actor sends an “exit message” to all of its links as part of its termination. Unlike down messages (cf. 1.2.6), the default behavior for received exit messages causes the receiving actor to terminate for the same reason if the link has failed, i.e., terminated with a non-normal exit reason. This allows developers to create a set of actors with the guarantee that either all or no actors are alive. The default behavior can be overridden, i.e., exit message can be “trapped”. When trapping exit messages, they are received as any other ordinary message and can be handled by the actor. 2 FIRST STEPS 2 First Steps To compile libcppa, you will need CMake and a C++11 compiler. To get and compile the sources, open a terminal (on Linux or Mac OS X) and type: git clone git://github.com/Neverlord/libcppa.git cd libcppa ./configure make make install [as root, optional] It is recommended to run the unit tests as well: make test Please submit a bug report that includes (a) your compiler version, (b) your OS, and (c) the content of the file build/Testing/Temporary/LastTest.log if an error occurs. 2.1 • • • • • • 2.2 Features Overview Lightweight, fast and efficient actor implementations Network transparent messaging Error handling based on Erlang’s failure model Pattern matching for messages as internal DSL to ease development Thread-mapped actors for soft migration of existing applications Publish/subscribe group communication Supported Compilers • GCC ≥ 4.7 • Clang ≥ 3.2 2.3 Supported Operating Systems • Linux • Mac OS X • Note for MS Windows: libcppa relies on C++11 features such as variadic templates. We will support this platform as soon as Microsoft’s compiler implements all required C++11 features. 3 FIRST STEPS 2.4 Hello World Example #include <string> #include <iostream> #include "cppa/cppa.hpp" using namespace std; using namespace cppa; behavior mirror(event_based_actor* self) { // return the (initial) actor behavior return { // a handler for messages containing a single string // that replies with a string [=](const string& what) -> string { // prints "Hello World!" via aout // (thread-safe cout wrapper) aout(self) << what << endl; // terminates this actor // (’become’ otherwise loops forever) self->quit(); // reply "!dlroW olleH" return string(what.rbegin(), what.rend()); } }; } void hello_world(event_based_actor* self, const actor& buddy) { // send "Hello World!" to our buddy ... self->sync_send(buddy, "Hello World!").then( // ... wait for a response ... [=](const string& what) { // ... and print it aout(self) << what << endl; } ); } int main() { // create a new actor that calls ’mirror()’ auto mirror_actor = spawn(mirror); // create another actor that calls ’hello_world(mirror_actor)’; spawn(hello_world, mirror_actor); // wait until all other actors we have spawned are done await_all_actors_done(); // run cleanup code before exiting main shutdown(); } 4 COPY-ON-WRITE TUPLES 3 Copy-On-Write Tuples The message passing implementation of libcppa uses tuples with call-by-value semantic. Hence, it is not necessary to declare message types, though, libcppa allows users to use user-defined types in messages (see Section 14.1). A call-by-value semantic would cause multiple copies of a tuple if it is send to multiple actors. To avoid unnecessary copying overhead, libcppa uses a copy-on-write tuple implementation. A tuple is implicitly shared between any number of actors, as long as all actors demand only read access. Whenever an actor demands write access, it has to copy the data first if more than one reference to it exists. Thus, race conditions cannot occur and each tuple is copied only if necessary. The interface of cow_tuple strictly distinguishes between const and non-const access. The template function get returns an element as immutable value, while get_ref explicitly returns a mutable reference to the required value and detaches the tuple if needed. We do not provide a const overload for get, because this would cause to unintended, and thus unnecessary, copying overhead. auto x1 = make_cow_tuple(1, 2, 3); auto x2 = x1; assert(&get<0>(x1) == &get<0>(x2)); get_ref<0>(x1) = 10; //get<0>(x1) = 10; assert(get<0>(x1) == 10); assert(get<0>(x2) == 1); assert(&get<0>(x1) != &get<0>(x2)); 3.1 // // // // // // // // cow_tuple<int, int, int> cow_tuple<int, int, int> point to the same data detaches x1 from x2 compiler error x1 is now {10, 2, 3} x2 is still {1, 2, 3} no longer the same Dynamically Typed Tuples The class any_tuple represents a tuple without static type information. All messages send between actors use this tuple type. The type information can be either explicitly accessed for each element or the original tuple, or a subtuple of it, can be restored using tuple_cast. Users of libcppa usually do not need to know about any_tuple, since it is used “behind the scenes”. However, any_tuple can be created from a cow_tuple or by using make_any_tuple, as shown below. auto x1 = any_tuple any_tuple auto x4 = make_cow_tuple(1, 2, 3); x2 = x1; x3 = make_cow_tuple(10, 20); make_any_tuple(42); 5 // // // // cow_tuple<int, int, int> any_tuple any_tuple any_tuple COPY-ON-WRITE TUPLES 3.2 Casting Tuples The function tuple_cast restores static type information from an any_tuple object. It returns an option (see Section 18.1) for a cow_tuple of the requested types. auto x1 = make_any_tuple(1, 2, 3); auto x2_opt = tuple_cast<int, int, int>(x1); assert(x2_opt.valid()); auto x2 = *x2_opt; assert(get<0>(x2) == 1); assert(get<1>(x2) == 2); assert(get<2>(x2) == 3); The function tuple_cast can be used with wildcards (see Section 4.4) to create a view to a subset of the original data. No elements are copied, unless the tuple becomes detached. auto x1 = make_cow_tuple(1, 2, 3); any_tuple x2 = x1; auto x3_opt = tuple_cast<int, anything, int>(x2); assert(x3_opt.valid()); auto x3 = *x3_opt; assert(get<0>(x3) == 1); assert(get<1>(x3) == 3); assert(&get<0>(x3) == &get<0>(x1)); assert(&get<1>(x3) == &get<2>(x1)); 6 PATTERN MATCHING 4 Pattern Matching C++ does not provide pattern matching facilities. A general pattern matching solution for arbitrary data structures would require a language extension. Hence, we decided to restrict our implementation to tuples, to be able to use an internal domain-specific language approach. 4.1 Basics A match expression begins with a call to the function on, which returns an intermediate object providing the member function when and operator>>. The right-hand side of the operator denotes a callback, usually a lambda expression, that should be invoked if a tuple matches the types given to on, as shown in the example below. on<int>() >> [](int i) { /*...*/ } on<int, float>() >> [](int i, float f) { /*...*/ } on<int, int, int>() >> [](int a, int b, int c) { /*...*/ } The result of operator>> is a match statement. A partial function can consist of any number of match statements. At most one callback is invoked, since the evaluation stops at the first match. partial_function fun { on<int>() >> [](int i) { // case1 }, on<int>() >> [](int i) { // case2; never invoked, since case1 always matches first } }; The function “on” can be used in two ways. Either with template parameters only or with function parameters only. The latter version deduces all types from its arguments and matches for both type and value. To match for any value of a given type, “val” can be used, as shown in the following example. on(42) >> [](int i) { assert(i == 42); } on("hello world") >> [] { /* ... */ } on("print", val<std::string>) >> [](const std::string& what) { // ... } Note: The given callback can have less arguments than the pattern. But it is only allowed to skip arguments from left to right. on<int, float, double>() >> [](double) { /*...*/ } // ok on<int, float, double>() >> [](float, double) { /*...*/ } // ok on<int, float, double>() >> [](int, float, double) { /*...*/ } // ok on<int, float, double>() >> [](int i) { /*...*/ } // compiler error 7 PATTERN MATCHING 4.2 Reducing Redundancy with “arg_match” and “on_arg_match” Our previous examples always used the most verbose form, which is quite redundant, since you have to type the types twice – as template parameter and as argument type for the lambda. To avoid such redundancy, arg_match can be used as last argument to the function on. This causes the compiler to deduce all further types from the signature of the given callback. on<int, int>() >> [](int a, int b) { /*...*/ } // is equal to: on(arg_match) >> [](int a, int b) { /*...*/ } Note that the second version does call on without template parameters. Furthermore, arg_match must be passed as last parameter. If all types should be deduced from the callback signature, on_arg_match can be used. It is equal to on(arg_match). However, when using a pattern to initialize the behavior of an actor, on_arg_match is used implicitly whenever a functor is passed without preceding it with an on clause. on_arg_match >> [](const std::string& str) { /*...*/ } 4.3 Atoms Assume an actor provides a mathematical service for integers. It takes two arguments, performs a predefined operation and returns the result. It cannot determine an operation, such as multiply or add, by receiving two operands. Thus, the operation must be encoded into the message. The Erlang programming language introduced an approach to use non-numerical constants, so-called atoms, which have an unambiguous, special-purpose type and do not have the runtime overhead of string constants. Atoms are mapped to integer values at compile time in libcppa. This mapping is guaranteed to be collision-free and invertible, but limits atom literals to ten characters and prohibits special characters. Legal characters are “_0-9A-Za-z” and the whitespace character. Atoms are created using the constexpr function atom, as the following example illustrates. on(atom("add"), arg_match) >> [](int a, int b) { /*...*/ }, on(atom("multiply"), arg_match) >> [](int a, int b) { /*...*/ }, // ... Note: The compiler cannot enforce the restrictions at compile time, except for a length check. The assertion atom("!?") != atom("?!") is not true, because each invalid character is mapped to the whitespace character. 8 PATTERN MATCHING 4.4 Wildcards The type anything can be used as wildcard to match any number of any types. A pattern created by on<anything>() or its alias others() is useful to define a default case. For patterns defined without template parameters, the constexpr value any_vals can be used as function argument. The constant any_vals is of type anything and is nothing but syntactic sugar for defining patterns. on<int, anything>() >> [](int i) { // tuple with int as first element }, on(any_vals, arg_match) >> [](int i) { // tuple with int as last element // "on(any_vals, arg_match)" is equal to "on(anything{}, arg_match)" }, others() >> [] { // everything else (default handler) // "others()" is equal to "on<anything>()" and "on(any_vals)" } 4.5 Guards Guards can be used to constrain a given match statement by using placeholders, as the following example illustrates. using namespace cppa::placeholders; // contains _x1 - _x9 on<int>().when(_x1 % 2 == 0) >> [] { // int is even }, on<int>() >> [] { // int is odd } Guard expressions are a lazy evaluation technique. The placeholder _x1 is substituted with the first value of a given tuple. All binary comparison and arithmetic operators are supported, as well as && and ||. In addition, there are three functions designed to be used in guard expressions: gref (“guard reference”), gval (“guard value”), and gcall (“guard function call”). The function gref creates a reference wrapper, while gval encloses a value. It is similar to std::ref but it is always const and “lazy”. A few examples to illustrate some pitfalls: int val = 42; on<int>().when(_x1 == val) on<int>().when(_x1 == gref(val)) on<int>().when(_x1 == std::ref(val)) others().when(gref(val) == 42) others().when(std::ref(val) == 42) 9 // // // // // // (1) (2) (3) (4) matches if _x1 == 42 matches if _x1 == val ok, because of placeholder matches everything as long as val == 42 (5) compiler error PATTERN MATCHING Statement (5) is evaluated immediately and returns a boolean, whereas statement (4) creates a valid guard expression. Thus, you should always use gref instead of std::ref to avoid errors. The second function, gcall, encapsulates a function call. Its usage is similar to std::bind, but there is also a short version for unary functions: gcall(fun, _x1) is equal to _x1(fun). auto vec_sorted = [](const std::vector<int>& vec) { return std::is_sorted(vec.begin(), vec.end()); }; on<std::vector<int>>().when(gcall(vec_sorted, _x1)) // is equal to: on<std::vector<int>>().when(_x1(vec_sorted))) 4.5.1 Placeholder Interface template<int X> struct guard_placeholder; Member functions (x represents the value at runtime, y represents an iterable container) size() empty() not_empty() front() in(y) not_in(y) 4.5.2 Returns x.size() Returns x.empty() Returns !x.empty() Returns an option (see Section 18.1) to x.front() Returns true if y contains x, false otherwise Returns !in(y) Examples for Guard Expressions using namespace std; typedef vector<int> ivec; vector<string> strings{"abc", "def"}; on_arg_match.when(_x1.front() == 0) >> [](const ivec& v) { // note: we don’t have to check whether _x1 is empty in our guard, // because ’_x1.front()’ returns an option for a // reference to the first element assert(v.size() >= 1); assert(v.front() == 0); }, on<int>().when(_x1.in({10, 20, 30})) >> [](int i) { assert(i == 10 || i == 20 || i == 30); }, on<string>().when(_x1.not_in(strings)) >> [](const string& str) { assert(str != "abc" && str != "def"); }, on<string>().when(_x1.size() == 10) >> [](const string& str) { // ... } 10 PATTERN MATCHING 4.6 Projections and Extractors Projections perform type conversions or extract data from a given input. If a callback expects an integer but the received message contains a string, a projection can be used to perform a type conversion on-the-fly. This conversion should be free of side-effects and, in particular, shall not throw exceptions, because a failed projection is not an error. A pattern simply does not match if a projection failed. Let us have a look at a simple example. auto intproj = [](const string& str) -> option<int> { char* endptr = nullptr; int result = static_cast<int>(strtol(str.c_str(), &endptr, 10)); if (endptr != nullptr && *endptr == ’\0’) return result; return {}; }; partial_function fun { on(intproj) >> [](int i) { // case 1: successfully converted a string }, on_arg_match >> [](const string& str) { // case 2: str is not an integer } }; The lambda intproj is a string ⇒ int projection, but note that it does not return an integer. It returns option<int>, because the projection is not guaranteed to always succeed. An empty option indicates, that a value does not have a valid mapping to an integer. A pattern does not match if a projection failed. Note: Functors used as projection must take exactly one argument and must return a value. The types for the pattern are deduced from the functor’s signature. If the functor returns an option<T>, then T is deduced. 11 ACTORS 5 Actors libcppa provides several actor implementations, each covering a particular use case. The class local_actor is the base class for all implementations, except for (remote) proxy actors. Hence, local_actor provides a common interface for actor operations like trapping exit messages or finishing execution. The default actor implementation in libcppa is event-based. Event-based actors have a very small memory footprint and are thus very lightweight and scalable. Contextswitching actors are used for actors that make use of the blocking API (see Section 15), but do not need to run in a separate thread. Context-switching and event-based actors are scheduled cooperatively in a thread pool. Thread-mapped actors can be used to opt-out of this cooperative scheduling. 5.1 Implicit self Pointer When using a function or functor to implement an actor, the first argument can be used to capture a pointer to the actor itself. The type of this pointer is event_based_actor* per default and blocking_actor* when using the blocking_api flag. When dealing with typed actors, the types are typed_event_based_actor<...>* and typed_blocking_actor<...>*. 12 ACTORS 5.2 Interface class local_actor; Member functions quit(uint32_t reason = normal) Finishes execution of this actor Observers bool trap_exit() any_tuple last_dequeued() actor_addr last_sender() vector<group> joined_groups() Checks whether this actor traps exit messages Returns the last message that was dequeued from the actor’s mailbox Note: Only set during callback invocation Returns the sender of the last dequeued message Note: Only set during callback invocation Returns all subscribed groups Modifiers void trap_exit(bool enabled) void join(const group& g) void leave(const group& g) void on_sync_failure(auto fun) void on_sync_timeout(auto fun) void monitor(actor_ptr whom) void demonitor(actor_ptr whom) bool has_sync_failure_handler() Enables or disables trapping of exit messages Subscribes to group g Unsubscribes group g Sets a handler, i.e., a functor taking no arguments, for unexpected synchronous response messages (default action is to kill the actor for reason unhandled_sync_failure) Sets a handler, i.e., a functor taking no arguments, for timed_sync_send timeout messages (default action is to kill the actor for reason unhandled_sync_timeout) Adds a unidirectional monitor to whom (see Section 9.2) Removes a monitor from whom Checks wheter this actor has a user-defined sync failure handler 13 SENDING MESSAGES 6 Sending Messages Messages can be sent by using the member function send or send_tuple. The variadic template function send has the following signature. template<typename... Args> void send(actor whom, Args&&... what); The variadic template pack what... is converted to a dynamically typed tuple (see Section 3.1) and then enqueued to the mailbox of whom. Using the function send is more compact, but does not have any other benefit. However, note that you should not use send if you already have an instance of any_tuple, because it creates a new tuple containing the old one. void some_fun(event_based_actor* self) { actor other = spawn(...); auto msg = make_any_tuple(1, 2, 3); self->send(other, msg); // oops, creates a new tuple containing msg self->send_tuple(other, msg); // ok } 14 SENDING MESSAGES 6.1 Replying to Messages The return value of a message handler is used as response message. Actors can also use the result of a sync_send to answer to a request, as shown below. void client(event_based_actor* self, const actor& master) { become ( on("foo", arg_match) >> [=](const string& request) -> string { return self->sync_send(master, atom("bar"), request).then( on_arg_match >> [=](const std::string& response) { return response; } ); } ); }; 6.2 Delaying Messages Messages can be delayed, e.g., to implement time-based polling strategies, by using one of delayed_send, delayed_send_tuple, delayed_reply, or delayed_reply_tuple. The following example illustrates a polling strategy using delayed_send. behavior poller(event_based_actor* self) { self->delayed_send(self, std::chrono::seconds(1), atom("poll")); return { on(atom("poll")) >> [] { // poll a resource // ... // schedule next polling self->delayed_send(self, std::chrono::seconds(1), atom("poll")); } }; } 15 SENDING MESSAGES 6.3 Forwarding Messages in Untyped Actors The member function forward_to forwards the last dequeued message to an other actor. Forwarding a synchronous message will also transfer responsibility for the request, i.e., the receiver of the forwarded message can reply as usual and the original sender of the message will receive the response. The following diagram illustrates forwarding of a synchronous message from actor B to actor C. A B | | | --(sync_send)--> | | | --(forward_to)-> | X | | | | <-------------(reply)-------------| |---\ | | handle | | response |<--/ | X C | | | |---\ | | compute | | result |<--/ | X The forwarding is completely transparent to actor C, since it will see actor A as sender of the message. However, actor A will see actor C as sender of the response message instead of actor B and thus could recognize the forwarding by evaluating self->last_sender(). 16 RECEIVING MESSAGES 7 Receiving Messages The current behavior of an actor is its response to the next incoming message and includes (a) sending messages to other actors, (b) creation of more actors, and (c) setting a new behavior. An event-based actor, i.e., the default implementation in libcppa, uses become to set its behavior. The given behavior is then executed until it is replaced by another call to become or the actor finishes execution. 7.1 Class-based actors A class-based actor is a subtype of event_based_actor and must implement the pure virtual member function make_behavior returning the initial behavior. class printer : public event_based_actor { behavior make_behavior() override { return { others() >> [] { cout << to_string(last_received()) << endl; } }; } }; Another way to implement class-based actors is provided by the class sb_actor (“State-Based Actor”). This base class simply returns init_state (defined in the subclass) from its implementation for make_behavior. struct printer : sb_actor<printer> { behavior init_state { others() >> [] { cout << to_string(self->last_received()) << endl; } }; }; Note that sb_actor uses the Curiously Recurring Template Pattern. Thus, the derived class must be given as template parameter. This technique allows sb_actor to access the init_state member of a derived class. The following example illustrates a more advanced state-based actor that implements a stack with a fixed maximum number of elements. 17 RECEIVING MESSAGES class fixed_stack : public sb_actor<fixed_stack> { friend class sb_actor<fixed_stack>; size_t max_size; vector<int> data; behavior full; behavior filled; behavior empty; behavior& init_state = empty; public: fixed_stack(size_t max) : max_size(max) { full = ( on(atom("push"), arg_match) >> [=](int) { /* discard */ }, on(atom("pop")) >> [=]() -> cow_tuple<atom_value, int> { auto result = data.back(); data.pop_back(); become(filled); return {atom("ok"), result}; } ); filled = ( on(atom("push"), arg_match) >> [=](int what) { data.push_back(what); if (data.size() == max_size) become(full); }, on(atom("pop")) >> [=]() -> cow_tuple<atom_value, int> { auto result = data.back(); data.pop_back(); if (data.empty()) become(empty); return {atom("ok"), result}; } ); empty = ( on(atom("push"), arg_match) >> [=](int what) { data.push_back(what); become(filled); }, on(atom("pop")) >> [=] { return atom("failure"); } ); } }; 18 RECEIVING MESSAGES 7.2 Nesting Receives Using become/unbecome Since become does not block, an actor has to manipulate its behavior stack to achieve nested receive operations. An actor can set a new behavior by calling become with the keep_behavior policy to be able to return to its previous behavior later on by calling unbecome, as shown in the example below. // receives {int, float} sequences behavior testee(event_based_actor* self) { return { [=](int value1) { self->become ( // the keep_behavior policy stores the current behavior // on the behavior stack to be able to return to this // behavior later on by calling unbecome() keep_behavior, [=](float value2) { cout << value1 << " => " << value2 << endl; // restore previous behavior self->unbecome(); } ); } }; } An event-based actor finishes execution with normal exit reason if the behavior stack is empty after calling unbecome. The default policy of become is discard_behavior that causes an actor to override its current behavior. The policy flag must be the first argument of become. Note: the message handling in libcppa is consistent among all actor implementations: unmatched messages are never implicitly discarded if no suitable handler was found. Hence, the order of arrival is not important in the example above. This is unlike other event-based implementations of the actor model such as Akka for instance. 19 RECEIVING MESSAGES 7.3 Timeouts A behavior set by become is invoked whenever a new messages arrives. If no message ever arrives, the actor would wait forever. This might be desirable if the actor only provides a service and should not do anything else. But often, we need to be able to recover if an expected messages does not arrive within a certain time period. The following examples illustrates the usage of after to define a timeout. #include <chrono> #include <iostream> #include "cppa/cppa.hpp" using std::endl; behavior eager_actor(event_based_actor* self) { return { [](int i) { /* ... */ }, [](float i) { /* ... */ }, others() >> [] { /* ... */ }, after(std::chrono::seconds(10)) >> [] { aout(self) << "received nothing within 10 seconds..." << endl; // ... } }; } Callbacks given as timeout handler must have zero arguments. Any number of patterns can precede the timeout definition, but “after” must always be the final statement. Using a zero-duration timeout causes the actor to scan its mailbox once and then invoke the timeout immediately if no matching message was found. libcppa supports timeouts using minutes, seconds, milliseconds and microseconds. However, note that the precision depends on the operating system and your local work load. Thus, you should not depend on a certain clock resolution. 20 RECEIVING MESSAGES 7.4 Skipping Messages Unmatched messages are skipped automatically by libcppa’s runtime system. This is true for all actor implementations. To allow actors to skip messages manually, skip_message can be used. This is in particular useful whenever an actor switches between behaviors, but wants to use a default rule created by others() to filter messages that are not handled by any of its behaviors. The following example illustrates a simple server actor that dispatches requests to workers. After receiving an ’idle’ message, it awaits a request that is then forwarded to the idle worker. Afterwards, the server returns to its initial behavior, i.e., awaits the next ’idle’ message. The server actor will exit for reason user_defined whenever it receives a message that is neither a request, nor an idle message. behavior server(event_based_actor* self) { auto die = [=] { self->quit(exit_reason::user_defined); }; return { on(atom("idle")) >> [=] { auto worker = last_sender(); self->become ( keep_behavior, on(atom("request")) >> [=] { // forward request to idle worker self->forward_to(worker); // await next idle message self->unbecome(); }, on(atom("idle")) >> skip_message, others() >> die ); }, on(atom("request")) >> skip_message, others() >> die }; } 21 SYNCHRONOUS COMMUNICATION 8 Synchronous Communication libcppa supports both asynchronous and synchronous communication. The member functions sync_send and sync_send_tuple send synchronous request messages. template<typename... Args> __unspecified__ sync_send(actor_ptr whom, Args&&... what); __unspecified__ sync_send_tuple(actor_ptr whom, any_tuple what); template<typename Duration, typename... Args> __unspecified__ timed_sync_send(actor_ptr whom, Duration timeout, Args&&... what); template<typename Duration, typename... Args> __unspecified__ timed_sync_send_tuple(actor_ptr whom, Duration timeout, any_tuple what); A synchronous message is sent to the receiving actor’s mailbox like any other asynchronous message. The response message, on the other hand, is treated separately. The difference between sync_send and timed_sync_send is how timeouts are handled. The behavior of sync_send is analogous to send, i.e., timeouts are specified by using after(...) statements (see 7.3). When using timed_sync_send function, after(...) statements are ignored and the actor will receive a sync_timeout_msg after the given duration instead. 8.1 Error Messages When using synchronous messaging, libcppa’s runtime environment will send ... • if the receiver is not alive: sync_exited_msg { actor_addr source; std::uint32_t reason; }; • if a message send by timed_sync_send timed out: sync_timeout_msg 22 SYNCHRONOUS COMMUNICATION 8.2 Receive Response Messages When sending a synchronous message, the response handler can be passed by either using then (event-based actors) or await (blocking actors). void foo(event_based_actor* self, actor testee) { // testee replies with a string to ’get’ self->sync_send(testee, atom("get")).then( on_arg_match >> [=](const std::string& str) { // handle str }, after(std::chrono::seconds(30)) >> [=]() { // handle error } ); ); Similar to become, the then function modifies an actor’s behavior stack. However, it is used as “one-shot handler” and automatically returns to the previous behavior afterwards. 8.3 Synchronous Failures and Error Handlers An unexpected response message, i.e., a message that is not handled by given behavior, will invoke the actor’s on_sync_failure handler. The default handler kills the actor by calling self->quit(exit_reason::unhandled_sync_failure). The handler can be overridden by calling self->on_sync_failure(/*...*/). Unhandled timeout messages trigger the on_sync_timeout handler. The default handler kills the actor for reason exit_reason::unhandled_sync_failure. It is possible set both error handlers by calling self->on_sync_timeout_or_failure(/*...*). void foo(event_based_actor* self, actor testee) { // testee replies with a string to ’get’ // set handler for unexpected messages self->on_sync_failure = [] { aout << "received: " << to_string(self->last_dequeued()) << endl; }; // set handler for timeouts self->on_sync_timeout = [] { aout << "timeout occured" << endl; }; // set response handler by using "then" timed_sync_send(testee, std::chrono::seconds(30), atom("get")).then( [=](const std::string& str) { /* handle str */ } ); 23 SYNCHRONOUS COMMUNICATION 8.3.1 Continuations for Event-based Actors libcppa supports continuations to enable chaining of send/receive statements. The functions then returns a helper object offering the member function continue_with, which takes a functor f without arguments. After receiving a message, f is invoked if and only if the received messages was handled successfully, i.e., neither sync_failure nor sync_timeout occurred. void foo(event_based_actor* self) { actor d_or_s = ...; // replies with either a double or a string sync_send(d_or_s, atom("get")).then( [=](double value) { /* functor f1 */ }, [=](const string& value) { /* functor f2*/ } ).continue_with([=] { // this continuation is invoked in both cases // *after* f1 or f2 is done, but *not* in case // of sync_failure or sync_timeout }); 24 MANAGEMENT & ERROR DETECTION 9 Management & Error Detection libcppa adapts Erlang’s well-established fault propagation model. It allows to build actor subsystem in which either all actors are alive or have collectively failed. 9.1 Links Linked actors monitor each other. An actor sends an exit message to all of its links as part of its termination. The default behavior for actors receiving such an exit message is to die for the same reason, if the exit reason is non-normal. Actors can trap exit messages to handle them manually. actor worker = ...; // receive exit messages as regular messages self->trap_exit(true); // monitor spawned actor self->link_to(worker); // wait until worker exited self->become ( [](const exit_msg& e) >> [=] { if (e.reason == exit_reason::normal) { // worker finished computation else { // worker died unexpectedly } } ); 9.2 Monitors A monitor observes the lifetime of an actor. Monitored actors send a down message to all observers as part of their termination. Unlike exit messages, down messages are always treated like any other ordinary message. An actor will receive one down message for each time it called self->monitor(...), even if it adds a monitor to the same actor multiple times. actor worker = ...; // monitor spawned actor self->monitor(worker); // wait until worker exited self->become ( on(const down_msg& d) >> [] { if (d.reason == exit_reason::normal) { // worker finished computation } else { // worker died unexpectedly } } ); 25 MANAGEMENT & ERROR DETECTION 9.3 Error Codes All error codes are defined in the namespace cppa::exit_reason. To obtain a string representation of an error code, use cppa::exit_reason::as_string(uint32_t). normal unhandled_exception 1 2 unallowed_function_call 3 unhandled_sync_failure 4 unhandled_sync_timeout 5 user_shutdown 16 remote_link_unreachable 257 user_defined 65536 9.4 Actor finished execution without error Actor was killed due to an unhandled exception Indicates that an event-based actor tried to use blocking receive calls Actor was killed due to an unexpected synchronous response message Actor was killed, because no timeout handler was set and a synchronous message timed out Actor was killed by a user-generated event Indicates that a remote actor became unreachable, e.g., due to connection error Minimum value for user-defined exit codes Attach Cleanup Code to an Actor Actors can attach cleanup code to other actors. This code is executed immediately if the actor has already exited. Keep in mind that self refers to the currently running actor. Thus, self refers to the terminating actor and not to the actor that attached a functor to it. auto worker = spawn(...); actor observer = self; // "monitor" spawned actor worker->attach_functor([observer](std::uint32_t reason) { // this callback is invoked from worker anon_send(observer, atom("DONE")); }); // wait until worker exited self->become ( on(atom("DONE")) >> [] { // worker terminated } ); Note: It is possible to attach code to remote actors, but the cleanup code will run on the local machine. 26 SPAWNING ACTORS 10 Spawning Actors Actors are created using the function spawn. The easiest way to implement actors is to use functors, e.g., a free function or lambda expression. The arguments to the functor are passed to spawn as additional arguments. The function spawn also takes optional flags as template parameter. The flag detached causes spawn to create a thread-mapped actor (opt-out of the cooperative scheduling), the flag linked links the newly created actor to its parent – not available on top-level spawn – and the flag monitored automatically adds a monitor to the new actor. Actors that make use of the blocking API (see Section 15) must be spawned using the flag blocking_api. Flags are concatenated using the operator +, as shown in the examples below. #include "cppa/cppa.hpp" using namespace cppa; void my_actor1(); void my_actor2(event_based_actor*, int arg1, const std::string& arg2); void ugly_duckling(); class my_actor3 : public event_based_actor { /* ... */ }; class my_actor4 : public sb_actor<my_actor4> { public: my_actor4(int some_value) { /* ... */ } /* ... */ }; // whenever we want to link to or monitor a spawned actor, // we have to spawn it using the self pointer, otherwise // we can use the free function ’spawn’ (top-level spawn) void server(event_based_actor* self) { // spawn function-based actors auto a0 = spawn(my_actor1); auto a1 = self->spawn<linked>(my_actor2, 42, "hello actor"); auto a2 = self->spawn<monitored>([] { /* ... */ }); auto a3 = spawn([](int) { /* ... */ }, 42); // spawn thread-mapped actors auto a4 = spawn<detached>(my_actor1); auto a5 = self->spawn<detached + linked>([] { /* ... */ }); auto a6 = spawn<detached>(my_actor2, 0, "zero"); // spawn class-based actors auto a7 = spawn<my_actor3>(); auto a8 = self->spawn<my_actor4, monitored>(42); // spawn thread-mapped actors using a class auto a9 = spawn<my_actor4, detached>(42); // spawn actors that need access to the blocking API auto aa = self->spawn<blocking_api>(ugly_duckling); // compiler error: my_actor2 captures the implicit // self pointer as event_based_actor* and thus cannot // be spawned using blocking_api flag /*-auto ab = self->spawn<blocking_api>(my_actor2);-*/ } 27 MESSAGE PRIORITIES 11 Message Priorities By default, all messages have the same priority and actors ignore priority flags. Actors that should evaluate priorities must be spawned using the priority_aware flag. This flag causes the actor to use a priority-aware mailbox implementation. It is not possible to change this implementation dynamically at runtime. behavior testee(event_based_actor* self) { // send ’b’ with normal priority self->send(self, atom("b")); // send ’a’ with high priority self->send(message_priority::high, self, atom("a")); // terminate after receiving a ’b’ return { on(atom("b")) >> [=] { aout(self) << "received ’b’ => quit" << endl; self->quit(); }, on(atom("a")) >> [=] { aout(self) << "received ’a’" << endl; }, }; } int main() { // will print "received ’b’ => quit" spawn(testee); await_all_actors_done(); // will print "received ’a’" and then "received ’b’ => quit" spawn<priority_aware>(testee); await_all_actors_done(); shutdown(); } 28 NETWORK TRANSPARENCY 12 Network Transparency All actor operations as well as sending messages are network transparent. Remote actors are represented by actor proxies that forward all messages. 12.1 Publishing of Actors void publish(actor whom, std::uint16_t port, const char* addr = 0) The function publish binds an actor to a given port. It throws network_error if socket related errors occur or bind_failure if the specified port is already in use. The optional addr parameter can be used to listen only to the given IP address. Otherwise, the actor accepts all incoming connections (INADDR_ANY). publish(self, 4242); self->become ( on(atom("ping"), arg_match) >> [](int i) { return make_cow_tuple(atom("pong"), i); } ); 12.2 Connecting to Remote Actors actor remote_actor(const char* host, std::uint16_t port) The function remote_actor connects to the actor at given host and port. A network_error is thrown if the connection failed. auto pong = remote_actor("localhost", 4242); self->send(pong, atom("ping"), 0); self->become ( on(atom("pong"), 10) >> [=] { self->quit(); }, on(atom("pong"), arg_match) >> [=](int i) { return make_cow_tuple(atom("ping"), i+1); } ); 29 GROUP COMMUNICATION 13 Group Communication libcppa supports publish/subscribe-based group communication. Actors can join and leave groups and send messages to groups. std::string group_module = ...; std::string group_id = ...; auto grp = group::get(group_module, group_id); self->join(grp); self->send(grp, atom("test")); self->leave(grp); 13.1 Anonymous Groups Groups created on-the-fly with group::anonymous() can be used to coordinate a set of workers. Each call to group::anonymous() returns a new, unique group instance. 13.2 Local Groups The "local" group module creates groups for in-process communication. For example, a group for GUI related events could be identified by group::get("local", "GUI events"). The group ID "GUI events" uniquely identifies a singleton group instance of the module "local". 13.3 Spawn Actors in Groups The function spawn_in_group can be used to create actors as members of a group. The function causes the newly created actors to call self->join(...) immediately and before spawn_in_group returns. The usage of spawn_in_group is equal to spawn, except for an additional group argument. The group handle is always the first argument, as shown in the examples below. void fun1(); void fun2(int, float); class my_actor1 : event_based_actor { /* ... */ }; class my_actor2 : event_based_actor { // ... my_actor2(const std::string& str) { /* ... */ } }; // ... auto grp = group::get(...); auto a1 = spawn_in_group(grp, fun1); auto a2 = spawn_in_group(grp, fun2, 1, 2.0f); auto a3 = spawn_in_group<my_actor1>(grp); auto a4 = spawn_in_group<my_actor2>(grp, "hello my_actor2!"); 30 PLATFORM-INDEPENDENT TYPE SYSTEM 14 Platform-Independent Type System libcppa provides a fully network transparent communication between actors. Thus, libcppa needs to serialize and deserialize messages. Unfortunately, this is not possible using the RTTI system of C++. libcppa uses its own RTTI based on the class uniform_type_info, since it is not possible to extend std::type_info. Unlike std::type_info::name(), uniform_type_info::name() is guaranteed to return the same name on all supported platforms. Furthermore, it allows to create an instance of a type by name. // creates a signed, 32 bit integer cppa::object i = cppa::uniform_typeid<int>()->create(); However, you should rarely if ever need to use object or uniform_type_info. 14.1 User-Defined Data Types in Messages All user-defined types must be explicitly “announced” so that libcppa can (de)serialize them correctly, as shown in the example below. #include "cppa/cppa.hpp" using namespace cppa; struct foo { int a; int b; }; int main() { announce<foo>(&foo::a, &foo::b); // ... foo can now safely be used in messages ... } Without the announce function call, the example program would terminate with an exception, because libcppa rejects all types without available runtime type information. announce() takes the class as template parameter and pointers to all members (or getter/setter pairs) as arguments. This works for all primitive data types and STL compliant containers. See the announce examples 1 – 4 of the standard distribution for more details. Obviously, there are limitations. You have to implement serialize/deserialize by yourself if your class does implement an unsupported data structure. See announce_example_5.cpp in the examples folder. 31 BLOCKING API 15 Blocking API Besides event-based actors (the default implementation), libcppa also provides context-switching and thread-mapped actors that can make use of the blocking API. Those actor implementations are intended to ease migration of existing applications or to implement actors that need to have access to blocking receive primitives for other reasons. Event-based actors differ in receiving messages from context-switching and thread-mapped actors: the former define their behavior as a message handler that is invoked whenever a new messages arrives in the actor’s mailbox (by using become), whereas the latter use an explicit, blocking receive function. 15.1 Receiving Messages The function receive sequentially iterates over all elements in the mailbox beginning with the first. It takes a partial function that is applied to the elements in the mailbox until an element was matched by the partial function. An actor calling receive is blocked until it successfully dequeued a message from its mailbox or an optional timeout occurs. self->receive ( on<int>().when(_x1 > 0) >> // ... ); The code snippet above illustrates the use of receive. Note that the partial function passed to receive is a temporary object at runtime. Hence, using receive inside a loop would cause creation of a new partial function on each iteration. libcppa provides three predefined receive loops to provide a more efficient but yet convenient way of defining receive loops. 32 BLOCKING API // DON’T // DO for (;;) { receive ( // ... ); } receive_loop ( // ... ); std::vector<int> results; for (size_t i = 0; i < 10; ++i) { receive ( on<int>() >> [&](int value) { results.push_back(value); } ); } std::vector<int> results; size_t i = 0; receive_for(i, 10) ( on<int>() >> [&](int value) { results.push_back(value); } ); size_t received = 0; do { receive ( others() >> [&]() { ++received; } ); } while (received < 10); size_t received = 0; do_receive ( others() >> [&]() { ++received; } ).until(gref(received) >= 10); The examples above illustrate the correct usage of the three loops receive_loop, receive_for and do_receive(...).until. It is possible to nest receives and receive loops. self->receive_loop ( on<int>() >> [&](int value1) { self->receive ( on<float>() >> [&](float value2) { cout << value1 << " => " << value2 << endl; } ); } ); 33 BLOCKING API 15.2 Receiving Synchronous Responses Analogous to sync_send(...).then(...) for event-based actors, blocking actors can use sync_send(...).await(...). void foo(blocking_actor* self, actor testee) { // testee replies with a string to ’get’ self->sync_send(testee, atom("get")).await( [&](const std::string& str) { // handle str }, after(std::chrono::seconds(30)) >> [&]() { // handle error } ); } 34 STRONGLY TYPED ACTORS 16 Strongly Typed Actors Strongly typed actors provide a convenient way of defining type-safe messaging interfaces. Unlike untyped actorsd, typed actors are not allowed to use guard expressions. When calling become in a strongly typed actor, all message handlers from the typed interface must be set. Typed actors use handles of type typed_actor<...> rather than actor, whereas the template parameters hold the messaging interface. For example, an actor responding to two integers with a dobule would use the type typed_actor<replies_to<int, int>::with<double>>. All functions for message passing, linking and monitoring are overloaded to accept both types of actors. 16.1 Spawning Typed Actors Typed actors are spawned using the function spawn_typed. The argument to this function call must be a match expression as shown in the example below, because the runtime of libcppa needs to evaluate the signature of each message handler. auto p0 = spawn_typed( on_arg_match >> [](int a, int b) { return static_cast<double>(a) * b; }, on_arg_match >> [](double a, double b) { return make_cow_tuple(a * b, a / b); } ); // assign to identical type using full_type = typed_actor_ptr< replies_to<int, int>::with<double>, replies_to<double, double>::with<double, double> >; full_type p1 = p0; // assign to subtype using subtype1 = typed_actor_ptr< replies_to<int, int>::with<double> >; subtype1 p2 = p0; // assign to another subtype using subtype2 = typed_actor_ptr< replies_to<double, double>::with<double, double> >; subtype2 p3 = p0; 35 STRONGLY TYPED ACTORS 16.2 Class-based Typed Actors Typed actors are spawned using the function spawn_typed and define their message passing interface as list of replies_to<...>::with<...> statements. This interface is used in (1) typed_event_based_actor<...>, which is the base class for typed actors, (2) the handle type typed_actor<...>, and (3) typed_behavior<...>, i.e., the behavior definition for typed actors. Since this is rather redundant, the actor handle provides definitions for the behavior as well as the base class, as shown in the example below. It is worth mentioning that all typed actors always use the event-based implementation, i.e., there is no typed actor implementation providing a blocking API. struct shutdown_request { }; struct plus_request { int a; int b; }; struct minus_request { int a; int b; }; typedef typed_actor<replies_to<plus_request>::with<int>, replies_to<minus_request>::with<int>, replies_to<shutdown_request>::with<void>> calculator_type; calculator_type::behavior_type typed_calculator(calculator_type::pointer self) { return { [](const plus_request& pr) { return pr.a + pr.b; }, [](const minus_request& pr) { return pr.a - pr.b; }, [=](const shutdown_request&) { self->quit(); } }; } class typed_calculator_class : public calculator_type::base { protected: behavior_type make_behavior() override { return { [](const plus_request& pr) { return pr.a + pr.b; }, [](const minus_request& pr) { return pr.a - pr.b; }, [=](const shutdown_request&) { quit(); } }; } }; 36 STRONGLY TYPED ACTORS void tester(event_based_actor* self, const calculator_type& testee) { self->link_to(testee); // will be invoked if we receive an unexpected response message self->on_sync_failure([=] { aout(self) << "AUT (actor under test) failed" << endl; self->quit(exit_reason::user_shutdown); }); // first test: 2 + 1 = 3 self->sync_send(testee, plus_request{2, 1}).then( [=](int r1) { assert(r1 == 3); // second test: 2 - 1 = 1 self->sync_send(testee, minus_request{2, 1}).then( [=](int r2) { assert(r2 == 1); // both tests succeeded aout(self) << "AUT (actor under test) " << "seems to be ok" << endl; self->send(testee, shutdown_request{}); } ); } ); } int main() { // announce custom message types announce<shutdown_request>(); announce<plus_request>(&plus_request::a, &plus_request::b); announce<minus_request>(&minus_request::a, &minus_request::b); // test function-based impl spawn(tester, spawn_typed(typed_calculator)); await_all_actors_done(); // test class-based impl spawn(tester, spawn_typed<typed_calculator_class>()); await_all_actors_done(); // done shutdown(); return 0; } 37 COMMON PITFALLS 17 Common Pitfalls 17.1 Event-Based API • The functions become and handle_response do not block, i.e., always return immediately. Thus, one should always capture by value in lambda expressions, because all references on the stack will cause undefined behavior if the lambda expression is executed. 17.2 Synchronous Messages • A handle returned by sync_send represents exactly one response message. Therefore, it is not possible to receive more than one response message. • The handle returned by sync_send is bound to the calling actor. It is not possible to transfer a handle to a response to another actor. 17.3 Sending Messages • send(whom, ...) is defined as send_tuple(whom, make_any_tuple(...)). Hence, a message sent via send(whom, self->last_dequeued()) will not yield the expected result, since it wraps self->last_dequeued() into another any_tuple instance. The correct way of forwarding messages is self->forward_to(whom). 17.4 Sharing • It is strongly recommended to not share states between actors. In particular, no actor shall ever access member variables or member functions of another actor. Accessing shared memory segments concurrently can cause undefined behavior that is incredibly hard to find and debug. However, sharing data between actors is fine, as long as the data is immutable and its lifetime is guaranteed to outlive all actors. The simplest way to meet the lifetime guarantee is by storing the data in smart pointers such as std::shared_ptr. Nevertheless, the recommended way of sharing informations is message passing. Sending data to multiple actors does not necessarily result in copying the data several times. Read Section 3 to learn more about libcppa’s copy-on-write optimization for tuples. 17.5 Constructors of Class-based Actors • You should not try to send or receive messages in a constructor or destructor, because the actor is not fully initialized at this point. 38 APPENDIX 18 18.1 Appendix Class option Defined in header "cppa/option.hpp". template<typename T> class option; Represents an optional value. Member types Member type Definition type T Member functions Constructs an empty option Initializes this with value option() option(T value) option(const option&) option(option&&) option& operator=(const option&) option& operator=(option&&) Copy/move construction Copy/move assignment Observers bool valid() explicit operator bool() bool empty() bool operator!() const T& get() const T& operator*() const T& get_or_else(const T& x) Returns true if this has a value Returns true if this does not has a value Access stored value Returns get() if valid, x otherwise Modifiers T& get() T& operator*() Access stored value 39 APPENDIX 18.2 Using aout – A Concurrency-safe Wrapper for cout When using cout from multiple actors, output often appears interleaved. Moreover, using cout from multiple actors – and thus from multiple threads – in parallel should be avoided regardless, since the standard does not guarantee a thread-safe implementation. By replacing std::cout with cppa::aout, actors can achieve a concurrency-safe text output. The header cppa/cppa.hpp also defines overloads for std::endl and std::flush for aout, but does not support the full range of ostream operations (yet). Each write operation to aout sends a message to a ‘hidden’ actor (keep in mind, sending messages from actor constructors is not safe). This actor only prints lines, unless output is forced using flush. The example below illustrates printing of lines of text from multiple actors (in random order). #include #include #include #include <chrono> <cstdlib> <iostream> "cppa/cppa.hpp" using namespace cppa; using std::endl; int main() { std::srand(std::time(0)); for (int i = 1; i <= 50; ++i) { spawn<blocking_api>([i](blocking_actor* self) { aout(self) << "Hi there! This is actor nr. " << i << "!" << endl; std::chrono::milliseconds tout{std::rand() % 1000}; self->delayed_send(self, tout, atom("done")); self->receive(others() >> [i, self] { aout(self) << "Actor nr. " << i << " says goodbye!" << endl; }); }); } // wait until all other actors we’ve spawned are done await_all_actors_done(); // done shutdown(); return 0; } 40