We have moved our Developer Blog!

As the last step of our project restructuring, we have moved our Blog to http://blog.actor-framework.org/. Please feel free to send us feedback on the new layout and read more in our new GitHub-hosted Dev Blog.

Version 0.11 released!

Version 0.11 of CAF has just been released. The core components mainly received optimizations and bugfixes this time around. However, CAF now includes the first alpha versions of a runtime inspection & debugging toolkit. Read more on GitHub.

Version 0.10 released!

Version 0.10 of CAF: C++ Actor Framework has just been released. Wait, what? For those of you that aren't subscribed to the mailing list, here is the Mail I've posted earlier this day:

libcppa started in 2011 and it has been in constant development ever since. I think we can call this a success on its own and we see more and more applications using libcppa. We will announce the most exciting partners on our website soon, by the way.

To be quite frank, I did not expect the library to evolve that fast and with the recent additions to our team, I think it is a safe bet to say that the development will not slow down in the future. We are working on scaling the library down for embedded HW platforms and we are working on tools that make debugging and fine-tuning your applications easier. The project is about to become something bigger than "just" an actor library. Hence, we have decided to revamp libcppa and call the project:

CAF: C++ Actor Framework

We will move the GitHub repository to https://github.com/actor-framework/actor-framework and restructure it. This mailing list will be renamed to actor-framework@googlegroups.com and we will launch a new website. We have synchronized the release of the new repository with the release of version 0.10 of *libcaf*. The library has been modularized and you'll find libcaf_core and libcaf_io in the initial release of CAF. You can use libcaf_core if all you need is the concurrency abstraction of the library. The networking parts have been moved to libcaf_io. You will find "remote_actor" and "publish" there. The OpenCL part will be available as submodule soon. We go into more detail in a blog post covering the changes and you will find a migration guide in the manual.

Version 0.10, the new GitHub URL, and the new Google Group Name will go live *today*. 0.10 will have breaking changes. We tried to make migration less painful by still shipping the old cppa/cppa.hpp header, but there are breaking changes nonetheless. I am sorry that we break existing code again: twice in a row to be correct (0.9 had breaking changes, too). On the other hand, I think it really is worth it and we could get rid of some legacy code and inconsistencies that we don not want to maintain in the long run.

We sincerely hope that we can get a smooth transition. You *should* be forwarded to the repository URL automatically and still have it starred/watched/forked. The mailing list *should* keep you as member. However, please feel free to drop me a mail if something isn't working for you.

So, here it is, the first official release under the new name CAF. Once you've checked out the new release, you'll probably notice that things have changed quite a bit. The first thing you should do is to open the manual under manual/manual.pdf and scroll right to the end. You will find a migration guide from 0.9 to 0.10 on the last two pages.

To use the library, you can use the new CMake script under cmake/FindLibcaf.cmake. Usually, you want to have the two components "core" and "io": find_package(Libcaf COMPONENTS core io REQUIRED). These two libraries offer you the functionality you're used to from libcppa. Please note that the OpenCL component is not ready quite yet. Upon success, the script will set the two variables ${LIBCAF_LIBRARIES} and ${LIBCAF_INCLUDE_DIRS}.

By the way, CAF is released under both the BSD 3-Clause and the Boost License. You can use it under the terms of either of those licenses (your choice!).

From now on, you can visit us at:
GitHub: https://github.com/actor-framework/actor-framework
GoogleGroups: https://groups.google.com/d/forum/actor-framework
... or go to our new project website: http://www.actor-framework.org.

As always, please don't hesitate to get in touch if you have any question.

Version 0.9.3 released ... under the Boost Software License!

Version 0.9.3 of libcppa has just been released. The biggest change this time around is the switch from LGPL to the Boost Software License 1.0. If you are working in one of those companies that prohibit LGPL-licensed code, you are finally able to use actors in your day-to-day programming.

Due to the everlasting problems with the Boost.Context-based context-switching actor implementation, this features is now turned off by default. To re-enable it, use the --enable-context-switching option of the configure script. Since this feature is of limited use anyways, we consider removing it completely in a future version. We don't think it is worth the maintenance effort in the long run.

Issues with Boost on Ubuntu

As reported by users of libcppa, the library fails to compile - or rather: to link - on the latest Ubuntu release with Boost. To get a running version of libcppa, please configure it using ./configure --standalone-build. This will disable the context-switching feature of libcppa. Context-switching is only relevant in case you want to have cooperative scheduling of blocking actors. When disabling this feature, all blocking actors are implicitly detached.

Since Boost only enables context-switching, we are considering to turn this feature into an opt-in rather than an opt-out at compile time. In case your system is lacking Boost, you won't get the context-switching actors anyways (and will not be affected by this error). Other parts of the library do not depend on Boost, so there is no degradation of performance or functionality.

If you run into a similar error on a different Linux distribution, please let me know.

Version 0.9 released!

Version 0.9 of libcppa has just been released. It features an all-new work-stealing scheduler. Expect new benchmark results in the near future as the last evaluation is heavily outdated by now.

Aside from performance performance tweaks, version 0.9 also features an improved broker interface covered in a new manual section as well as a new example.

Prerelease of Version 0.9

Version 0.9 of libcppa is just around the corner – and it's not simply an incremental update but a redesign of many (in fact: most) parts of libcppa. Since we don't plan to make any more changes to the API, we've decided to do a prerelease. This gives us the opportunity to get feedback from the community while polishing the remaining parts of the library and it also gives you the opportunity to start porting your code to 0.9 early.

The most important changes:

• self has been removed
  This is the biggest change and in fact did cause a lot of redesign and implementation work. The major problem with this keyword-like identifier is that it must have a single type, because it's implemented as a thread-local variable. Since there are so many different kinds of actors (event-based or blocking, untyped or typed), self simply isn't useful anymore. It could only point to the address (see below) of an actor, but this isn't useful at all, because we cannot get the type information we need. Instead of a thread-local pointer, you can now use the first argument in functor-based actors to "catch" the self pointer – with proper type information.
• actor_ptr has been removed/replaced
  The name actor_ptr bothered me for long time now, because it's misleading. The fact that libcppa uses pointers behind the scenes to keep things fast should not be exposed in the API. However, that was not the reason for the change. libcppa now distinguishes between handles to actors, i.e., typed_actor<...> or actor, and addresses of actors, i.e., actor_addr. The reason for this change is that each actor has a logical, (network-wide) unique address, which is used by the networking layer of libcppa. Furthermore, for monitoring or linking, the address is all you need. However, the address is not sufficient for sending messages, because it doesn't have any type information. The function last_sender() now returns the address of the sender, meaning that send(last_sender(), ...) will cause a compiler error.
• The API for typed actors is now similar to the API for untyped actors
  Although there are some minor differences (typed actors cannot use guard expressions for instance), the APIs are quite similar. You can use function-based or class-based actors, you can "catch" the self pointer in the same way, and you can change the behavior by calling become(...).

Issues (or: why this isn't a final release yet):

• No scheduling
  The prerelease does not include a scheduler. Instead, each actor is always mapped to a thread, whether or not you use the detach flag. So... don't expect good performance when running many actors.
• Documentation incomplete
  The manual has been revised, but doesn't include all new features. The same is true for the Doxygen-generated documentation.
• Testing
  The unit tests of libcppa cover most of the new features, but there's still work to do.

As always, please don't hesitate to get in touch if you've found a bug, miss a feature, couldn't find something in the documentation, or simply have a question.

Moving Forward: Type Safety & Actors

Type safety is a topic that comes up very frequently when talking to C++ developers about libcppa - and actors in general. Indeed, the major concern about libcppa at the C++Now 2013 conference was that it does not provide a type-safe messaging interface. I'm not going to discuss pros and cons of dynamic and static typing. Both approaches do have their benefits. In libcppa, you can use atoms to "create" new message types on the fly and then pattern match on the receiver side. In this way, it is very lightweight to introduce new message types to a system, as you don't have to maintain header files for your message types. On the flip side, "wrong" message types are detected at runtime. When sending arguments in the wrong order, your pattern on the receiver side will not match. Naturally, most C++ developers expect the compiler to detect those kind of bugs.

Version 0.8 introduced strongly-typed actors to give developers a choice. Unfortunately, libcppa is now a two-class society. Even worse, it is indeed rather easy to get an untyped reference to a strongly-typed actor. But let's step back and take a look at the issues individually.

1. Second-class Typed Actors: Typed actors are not allowed to use guard expressions. This in itself is not a problem. The problem is how libcppa signals system events. For example, when monitoring an actor, you'll receive a "down" message consisting of the atom 'DOWN' and the exit reason as uint32. Since typed actors are not allowed to use guards, the only thing they could possibly do is to define a handler for all messages with an atom as first element followed by an uint32. There are 10⁶⁴ possible atoms. As a consequence, libcppa needs to introduce message types for system messages. This will break code and I would prefer not to, but it's better to break some code that's easy to repair than to have a broken design.
2. Separated APIs: To spawn a typed actor, we use functions that return the behavior. For untyped actors, we can use void functions that call 'become' internally. Even worse, 'become' now can throw - when called from a typed actor. It's probably for the best to move 'become' from the namespace cppa to the class event_based_actor and always use function that return a behavior.
3. Type-safety Not Enforced: As you might know if you've ever used libcppa: An actor can get a handle to itself by using 'self' and a handle to any actor that sent a message to it by calling 'self->last_sender()'. This handle is of course untyped. So, not only can a typed actor get an untyped handle to itself, each actor it is communicating with has an untyped handle to it. The only way to enforce type safety is to either remove 'self' completely from the API or to change its type to something not convertible to actor_ptr, so that you can only access member functions like 'trap_exits'. The member function 'last_sender()' then also would have to go or to return only a logical address that you can use for monitoring and linking, but not for message passing.
4. Missing Features: This is not a design issue, but libcppa 0.9 will of course implement proper remote communication for typed actors.

libcppa started as a DSL for Erlang-style actor programming in C++. With version 0.9, libcppa will (hopefully) evolve into a unique actor system that supports untyped and typed actors side by side. Stay tuned. :)

Version 0.8 released!

Version 0.8 of libcppa has just been released. The biggest change for existing code: The function reply is deprecated. Actors now do automatically reply to a message by returning a value from the message handler. This change does not only make your code cleaner, but this is also the only way a new kind of actors - strongly typed actors - are allowed to reply to incoming messages. Typed actors is the most frequently requested feature for libcppa - and have finally arrived. You can create typed actors using the function spawn_typed:

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);
  }
);

As you can see, the argument to spawn_typed is a match expression rather than a function. This is because a typed actor is not allowed to change its behavior. The messaging interface is burnt into its type. In the example above, the type of p0 is typed_actor_ptr<replies_to<int, int>::with<double>,replies_to<double, double>::with<double, double>>. In this way, the compiler is now able to type-check your messages:

send(p0, 42); // <- compiler error

send(p0, 42, 24); // <- ok

sync_send(p0, 1, 2, 3).then ... // <- compiler error

sync_send(p0, 1, 2).then(
  [](float) { ... } // <- compiler error: expected double
);

sync_send(p0, 1, 2).then(
  [](double d) { ... } // <- ok
);

Typed actors are not "feature complete" yet, i.e., typed actors cannot be published and it is not possible to use priorities when sending a message to a typed actor. However, this is just a matter of time. To learn more about typed actors, visit Section 15 of the 0.8 manual.

As if typed actors were not enough, version 0.8 includes yet another new kind of actors: brokers. A broker connects your actor system to any other network protocol. The new release includes an example featuring Google Protobuf: examples/remote_actors/protobuf_broker.cpp.

A small addition that is worth mentioning is the new exit reason exit_reason::user_shutdown. This reason can be used whenever you force actors to quit as part of application shutdown or for shutting down parts of your system that are no longer necessary.

Version 0.7.1 released

Version 0.7.1 of libcppa has just been released. This release fixes some bugs and improves compatibility with GCC 4.8.

Version 0.7 released

Version 0.7 of libcppa has just been released. For the first time in an official release, this version breaks code compatibility with earlier versions (this was not an easy step and caused some discussion). When calling spawn with a function, the new default implementation is event-based. Hence, your actor should set its behavior using become and not use functions like receive. However, it is pretty easy to port your existing code. To opt-in to the "old" behavior, use spawn<blocking_api>(fun_name).

Among improvements and optimizations, this version includes a few new functions as well:

• Priority-aware messaging (opt-in feature)
• OpenCL-based actors (must be enabled using '--with-opencl')

Please note that the manual has received a huge update due to the changed default behavior of spawn and has not caught up to the new features yet.

Version 0.6 released

Version 0.6 of libcppa has just been released. This release brings several improvements to the synchronous messaging API. Please read more about features like functor-only usage and continuations in the revamped Section 7 of the manual.

Among several smaller improvements, this release also includes:

• manual skipping of messages
• Boost 1.53 support thanks to GitHub user abigagli
• a new quit_actor function to send 'EXIT' messages to actors

Actor Companions

In the previous post about actors with Qt, we have already briefly discussed the concept of actor companions, but this post presents the general approach.

What is it Good For?

libcppa automatically converts threads to actors if needed (using thread-local storage), whenever a thread uses a message passing primitive such as send(). However, sometimes this conversion is too coarse-grained. Simply put, whenever several independent entities share a thread, but should be addressed individually as actors, we need actor companions. The classical example is a widget. The thread is owned by the event loop, which manages any number of widgets, why we cannot rely on libcppa's automatic thread conversion. If you need to support a library wich internally schedules its entities (perhaps based on green threads or coroutines) - or if you just want to learn more about libcppa, this post is for you.

Background

If you want to mix libcppa with an other framework, multiple inheritance is not an option. Usually, each framework manages its entities in an incompatible way. For example, Qt uses hierarchical object ownership by default. This obviously interferes with the reference counting strategy of libcppa. Even if the framework uses reference counts, you will end up having two reference counts in your object. Instead of using multiple inheritance, we use co-existing objects (companions), which serve as gateway. The companion implements the actor interface of libcppa but does not have a mailbox. It forwards all messages it receives to its parent.

Mixing in a Solution

Actor companions are enabled by the mixin actor_companion_mixin. The mixin provides the member functions actor_ptr as_actor(), void set_message_handler(...), and void handle_message(const message_pointer&). It also has one pure virtual member function: void new_message(message_pointer). This function must be implemented in a thread-safe way. The type message_pointer is a smart pointer holding a tuple along with meta data such as sender information. There is no need to interact with a message_pointer, as the message handler does everything necessary.

A Working Example

template<typename Base, int EventId = static_cast<int>(QEvent::User + 31337)>
class actor_widget_mixin : public actor_companion_mixin<Base> {

  typedef actor_companion_mixin<Base> super;

  typedef typename super::message_pointer message_pointer;

 public:

  template<typename... Args>
  actor_widget_mixin(Args&&... args) : super(std::forward<Args>(args)...) { }

  struct event_type : public QEvent {

    message_pointer msg;

    event_type(message_pointer mptr)
    : QEvent(static_cast<QEvent::Type>(EventId)), msg(std::move(mptr)) { }

  };

  virtual bool event(QEvent* event) {
    if (event->type() == static_cast<QEvent::Type>(EventId)) {
      auto ptr = dynamic_cast<event_type*>(event);
      if (ptr) {
        this->handle_message(ptr->msg);
        return true;
      }
    }
    return super::event(event);
  }

 protected:

  virtual void new_message(message_pointer ptr) {
    qApp->postEvent(this, new event_type(std::move(ptr)));
  }

};

The code shown above is the actual code from cppa/qtsupport/actor_widget_mixin.hpp. As you can see, it is Qt specific, but straightforward. Our "derived mixin" has no constructor arguments and only forwards all arguments to the base constructor (line 11).

The crucial point of this implementation is to convert libcppa messages to Qt events in the implementation of new_message (line 35). The runtime system of Qt will then call the event member function (line 22) later on from inside the event loop. All our implementation has to do is to unwrap the message_pointer and pass it to handle_message.

Once we have called handle_message, our message handler gets invoked – with self pointing to the companion. This way, we can use send and reply as usual in the handler. Even though the code is Qt specific, it should be straightforward to implement a comparable mixin to support your framework of choice.

Version 0.5.5 released

Version 0.5.5 of libcppa has just been released. This release brings several bugfixes and performance improvements as well as aout – A Thread-Safe Wrapper for std::cout.

Using Actors with Qt

Actor programming is nice and makes our lives easier, but at some point, we have to display the output of our program to the user. Not everything is a command line tool. Hence, we have to use some sort of GUI library, which raises the question how we pass messages from actors - safely! - to the GUI at runtime. Well, what if we could send an ordinary message to the GUI as if it's an actor? What if the GUI can send us ordinary messages whenever the user pushes some buttons? Briefly speaking, can we treat GUI elements as actors? Luckily, the answer is yes! We have to write some gluecode, but in fact, you can treat everything as an actor with libcppa.

Getting Started

In this article, we will focus on the Qt library, as it is the open source GUI library of choice for C++ developers. In the next article, we will have a look at the general concept of actor companions. An actor companion is an actor that co-exists with another object. In our case, this object is a QWidget-base class. The companion is used to receive and send messages, but it does not have any behavior itself. All it takes to enable a class to have such a companion is to use the actor_widget_mixin.

The following class implements a simple group-based chat widget with a QTextEdit for text output and a QLineEdit for user input (chat messages). The full source code can be found in the examples folder in the Git repository.

#include <QWidget>
#include "cppa/qtsupport/actor_widget_mixin.hpp"

class ChatWidget : public cppa::actor_widget_mixin<QWidget> {

  Q_OBJECT

  typedef cppa::actor_widget_mixin<QWidget> super;

  // ...

 public:

  ChatWidget(QWidget* parent = nullptr, Qt::WindowFlags f = 0);

  // ...

 private:

  std::string m_name;
  cppa::group_ptr m_chatroom;

};

The mixin adds the following member functions to ChatWidget:

• actor_ptr as_actor()
  returns the companion of this widget
• set_message_handler
  sets the partial function for message processing

Handle Messages to the Widget

In our example, the widget should handle 'join', 'setName', and 'quit' messages as well as display chat messages (received as std::string). We encode our message handling directly into the constructor of ChatWidget:

ChatWidget::ChatWidget(QWidget* parent, Qt::WindowFlags f) : super(parent, f) {
  set_message_handler (
    on(atom("join"), arg_match) >> [=](const group_ptr& what) {
      if (m_chatroom) {
        send(m_chatroom, m_name + " has left the chatroom");
        self->leave(m_chatroom);
      }
      self->join(what);
      print(("*** joined " + to_string(what)).c_str());
      m_chatroom = what;
      send(what, m_name + " has entered the chatroom");
    },
    on(atom("setName"), arg_match) >> [=](string& name) {
      send(m_chatroom, m_name + " is now known as " + name);
      m_name = std::move(name);
      print("*** changed name to "
            + QString::fromUtf8(m_name.c_str()));
    },
    on(atom("quit")) >> [=] {
      close(); // close widget
    },
    on<string>() >> [=](const string& txt) {
      // don't print own messages
      if (self != self->last_sender()) {
        print(QString::fromUtf8(txt.c_str()));
      }
    }
  );
}

Pitfalls & Things to Know

The code is pretty straight forward if you are already familiar with libcppa, but there is one important thing to note: Unhandled messages are lost. Although the widget is able to handle libcppa messages now, it does not have a mailbox. Messages are delivered to the widget as QEvent objects that are disposed afterwards.

The second thing to note is that you should never use self outside the message handler. This includes using functions such as send, because self is internally used to determine the sender of a message. The reason to this limitation is that libcppa's self "pointer" is thread-local. Using self would therefore convert the Qt thread your widget runs in to an actor, but it wouldn't address your widget's companion.

To send a message from outside of your handler, you have to tell libcppa who is the sender of the message by hand:

send_as(as_actor(), m_chatroom, "hello world!");

Have fun!

Version 0.5 released

Version 0.5 of libcppa has just been released. This release brings Log4j-like logfiles to libcppa developers (must be enabled at compile time), support for user-defined communication protocols, and actor companions.

Each class using the actor_companion_mixin has such an actor companion, which provides an easy way for active non-actor objects, i.e., objects with an own thread or event loop, to send messages to/as actor. The default use case for this feature is to treat GUI elements - widgets - as actors. A more specific mixin for Qt widgets is on its way.

By the way, libcppa now has more than a thousand commits on GitHub! :-)

Version 0.4 released

The main feature of version 0.4 is a streamlined and bugfixed network layer. Of course, there are some new features as well:

• Support for User-Defined Network Layer
  The functions publish and remote_actor were overloaded to allow user-defined network layers such as OpenSSL; see this mailing list discussion and the doxygen documentation of util::input_stream, util::output_stream and util::acceptor for more details.
  
• Shutdown Function
  The new shutdown() function closes all network connections, stops the scheduler and deletes all of libcppa's singletons. It is strongly recommended to call this function before returning from main(), especially if you are connected to remote actors.
  
• Syntactic Sugar for Synchronous Messaging
  Synchronous message handling using futures is flexible but sometimes too verbose.

  auto future = sync_send(...);
  handle_response(future, ...);  // event-based API
  receive_response(future, ...); // blocking API

  Version 0.4 provides some syntactic sugar to make your code more compact. Whenever you send a message and immediately wait for the response, you can write the following instead.

  sync_send(...).then(...);  // event-based API
  sync_send(...).await(...); // blocking API

  Furthermore, there is a feature request for a continuation-passing style API to enable developers to easily encode "send X then receive Y then send Z" message flows (see Issue 58 on GitHub).
• Local Groups & Remote Actors
  Local groups, as returned by calling group::get("local", ...); or group::anonymous(), are now not-so-local. It is possible to send a local group to a remote actor and let the remote actor join the group. Whenever an actor sends a message to the group, the message is send back to the owning process if needed and forwarded to all subscribers from there, including remote actors. This approach certainly does not scale for largely distributed groups, since it is N-times unicast*. However, it paves to path for more use cases of "local" groups and we are working on scalable group communication as well.
  
  * The N in this case is the number of hosts and not the number of remote actors.
  

New Functions in 0.3.3

Among some bugfixes, version 0.3.3 also includes a few new functions to add 'missing' features:

• Forwarding of Messages
  libcppa lacked an easy and transparent way to forward messages. The new function forward_to finally adds this functionality. Furthermore, forwarding a synchronous messages is not possible without this function. Read more about forwarding in Section 5.4 of the manual.
• Messaging with Tuples
  Matthias Vallentin pointed out that the API was somewhat inconsistent, since it did not provide functions to use a tuple as response message. We have added the following functions in version 0.3.3 to treat tuples as first-class citizen: send_tuple, sync_send_tuple, reply_tuple, delayed_send_tuple and delayed_reply_tuple.
• Manual
  The manual is now included to the source distribution as manual.pdf and states the libcppa version.
• Doxygen
  CMake checks whether doxygen is available on your system and adds an optional "doc" target to the Makefile. You can create your own local version of the doxygen documentation by running "make doc". Open the file html/index.html afterwards.

libcppa on Mountain Lion

I have just upgraded my Mac and I have good news for all Apple users out there!

If you have switched to Mountain Lion or have plans to do so, you will find clang++ in version 4.0 after installing XCode. Hence, there is finally no need to get a recent compiler from an external source. libcppa 0.3 compiles and runs like a charm after installing CMake and Boost from MacPorts.

Version 0.3 Released

I'm glad to announce libcppa 0.3. This release has two major improvements.

Synchronous Messages

Actors can send synchronous response messages by using the function sync_send. This function returns a future to the response that can be received by using either the blocking receive_response or the event-based handle_response. Please read the section about synchronous communication in the manual for further details.

Configure Script

Thanks to Matthias Vallentin (a.k.a. mavam), libcppa has a much simpler build process now. The new configure script hides all CMake details behind a nice and clean interface.

Minor Improvements

• Context-switching can be disabled by using the --disable-context-switching configure option for platforms without Boost.Context support (Issue 24).
• The function tuple_cast does no longer require an additional header include (Issue 38).
• The new "cppa_fwd.hpp" header provides forward declarations for heavily used data structures, such as actor_ptr (Issue 36).
• become() no longer accepts pointers to avoid potential misuses and resulting memory leaks.