\section{Appendix}

\subsection{Class \texttt{option}}
\label{Appendix::Option}

Defined in header \lstinline^"caf/option.hpp"^.

\begin{lstlisting}
template<typename T>
class option;
\end{lstlisting}

Represents an optional value.

{\small
\begin{tabular*}{\textwidth}{m{0.5\linewidth}m{0.45\linewidth}}
  \multicolumn{2}{l}{\large{\textbf{Member types}}\vspace{3pt}} \\
  \hline
  \textbf{Member type} & \textbf{Definition} \\
  \hline
  \lstinline^type^ & \lstinline^T^ \\
  \hline
  \\
  \multicolumn{2}{l}{\large{\textbf{Member Functions}}\vspace{3pt}} \\
  \hline
  \lstinline^option()^ & Constructs an empty option \\
  \hline
  \lstinline^option(T value)^ & Initializes \lstinline^this^ with \lstinline^value^ \\
  \hline
  \lstinline^option(const option&)^\newline\lstinline^option(option&&)^ & Copy/move construction \\
  \hline
  \lstinline^option& operator=(const option&)^\newline\lstinline^option& operator=(option&&)^ & Copy/move assignment \\
  \hline
  \\
  \multicolumn{2}{l}{\textbf{Observers}\vspace{3pt}} \\
  \hline
  \lstinline^bool valid()^\newline\lstinline^explicit operator bool()^ & Returns \lstinline^true^ if \lstinline^this^ has a value \\
  \hline
  \lstinline^bool empty()^\newline\lstinline^bool operator!()^ & Returns \lstinline^true^ if \lstinline^this^ does \textbf{not} has a value \\
  \hline
  \lstinline^const T& get()^\newline\lstinline^const T& operator*()^ & Access stored value \\
  \hline
  \lstinline^const T& get_or_else(const T& x)^ & Returns \lstinline^get()^ if valid, \lstinline^x^ otherwise  \\
  \hline
  \\
  \multicolumn{2}{l}{\textbf{Modifiers}\vspace{3pt}} \\
  \hline
  \lstinline^T& get()^\newline\lstinline^T& operator*()^ & Access stored value \\
  \hline
\end{tabular*}
}

\clearpage
\subsection{Using \texttt{aout} -- A Concurrency-safe Wrapper for \texttt{cout}}

When using \lstinline^cout^ from multiple actors, output often appears interleaved.
Moreover, using \lstinline^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 \texttt{std::cout} with \texttt{caf::aout}, actors can achieve a concurrency-safe text output.
The header \lstinline^caf/all.hpp^ also defines overloads for \texttt{std::endl} and \texttt{std::flush} for \lstinline^aout^, but does not support the full range of ostream operations (yet).
Each write operation to \texttt{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 \lstinline^flush^.
The example below illustrates printing of lines of text from multiple actors (in random order).

\begin{lstlisting}
#include <chrono>
#include <cstdlib>
#include <iostream>

#include "caf/all.hpp"

using namespace caf;
using std::endl;

using done_atom = atom_constant<atom("done")>;

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, done_atom::value);
      self->receive(
        [i, self](done_atom) {
          aout(self) << "Actor nr. "
                     << i << " says goodbye!" << endl;
        }
      );
    });
  }
  // wait until all other actors we've spawned are done
  await_all_actors_done();
  shutdown();
}
\end{lstlisting}

\clearpage
\subsection{Migration Guides}

The guides in this section document all possibly breaking changes in the library for that last versions of \lib.

\subsubsection{0.8 $\Rightarrow$ 0.9}

Version 0.9 included a lot of changes and improvements in its implementation, but it also made breaking changes to the API.

\paragraph{\lstinline^self^ has been removed}

~

This is the biggest library change since the initial release.
The major problem with this keyword-like identifier is that it must have a single type as it's implemented as a thread-local variable.
Since there are so many different kinds of actors (event-based or blocking, untyped or typed), \lstinline^self^ needs to perform type erasure at some point, rendering it ultimately useless.
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.

\paragraph{\lstinline^actor_ptr^ has been replaced}

~

\lib now distinguishes between handles to actors, i.e., \lstinline^typed_actor<...>^ or simply \lstinline^actor^, and \emph{addresses} of actors, i.e., \lstinline^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 \lib. 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 \lstinline^last_sender()^ now returns the \emph{address} of the sender.
This means that previously valid code such as \lstinline^send(last_sender(), ...)^ will cause a compiler error.
However, the recommended way of replying to messages is to return the result from the message handler.

\paragraph{The API for typed actors is now similar to the API for untyped actors}

~

The APIs of typed and untyped actors have been harmonized.
Typed actors can now be published in the network and also use all operations untyped actors can.

\clearpage
\subsubsection{0.9 $\Rightarrow$ 0.10 (\texttt{libcppa} $\Rightarrow$ CAF)}

The first release under the new name CAF is an overhaul of the entire library.
Some classes have been renamed or relocated, others have been removed.
The purpose of this refactoring was to make the library easier to grasp and to make its API more consistent.
All classes now live in the namespace \lstinline^caf^ and all headers have the top level folder ``caf'' instead of ``cppa''.
For example, \lstinline^#include "cppa/actor.hpp"^ becomes \lstinline^#include "caf/actor.hpp"^.
Further, the convenience header to get all parts of the user API is now \lstinline^"caf/all.hpp"^.
The networking has been separated from the core library.
To get the networking components, simply include \lstinline^"caf/io/all.hpp"^ and use the namespace \lstinline^caf::io^, e.g., \lstinline^caf::io::remote_actor^.

Version 0.10 still includes the header \lstinline^cppa/cppa.hpp^ to make the transition process for users easier and to not break existing code right away.
The header defines the namespace \lstinline^cppa^ as an alias for \lstinline^caf^.
Furthermore, it provides implementations or type aliases for renamed or removed classes such as \lstinline^cow_tuple^.
You won't get any warning about deprecated headers with 0.10.
However, we will add this warnings in the next library version and remove deprecated code eventually.

Even when using the backwards compatibility header, the new library has breaking changes.
For instance, guard expressions have been removed entirely.
The reasoning behind this decision is that we already have projections to modify the outcome of a match.
Guard expressions add little expressive power to the library but a whole lot of code that is hard to maintain in the long run due to its complexity.
Using projections to not only perform type conversions but also to restrict values is the more natural choice.

The following table summarizes the changes made to the API.

\begin{tabular*}{\textwidth}{m{0.44\textwidth}m{0.48\textwidth}}
  Change & Explanation \\
  \hline
  \lstinline^any_tuple => message^ & This type is only being used to pass a message from one actor to another. Hence, \lstinline^message^ is the logical name. \\
  \hline
  \lstinline^partial_function => ^ \lstinline^message_handler^ & Technically, it still is a partial function, but wanted to emphasize its use case in the library. \\
  \hline
  \lstinline^cow_tuple => X^ & We want to provide a streamlined, simple API. Shipping a full tuple abstraction with the library does not fit into this philosophy. The removal of \lstinline^cow_tuple^ implies the removal of related functions such as \lstinline^tuple_cast^. \\
  \hline
  \lstinline^cow_ptr => X^ & This pointer class is an implementation detail of \lstinline^message^ and should not live in the global namespace in the first place. It also had the wrong name, because it is intrusive. \\
  \hline
  \lstinline^X => message_builder^ & This new class can be used to create messages dynamically. For example, the content of a vector can be used to create a message using a series of \lstinline^append^ calls. \\
  \hline
  \lstinline^accept_handle^, \lstinline^connection_handle^, \lstinline^publish^, \lstinline^remote_actor^, \lstinline^max_msg_size^, \lstinline^typed_publish^, \lstinline^typed_remote_actor^, \lstinline^publish_local_groups^, \lstinline^new_connection_msg^, \lstinline^new_data_msg^, \lstinline^connection_closed_msg^, \lstinline^acceptor_closed_msg^ & These classes concern I/O functionality and have thus been moved to \lstinline^caf::io^. \\
  \hline
\end{tabular*}

\subsubsection{0.10 $\Rightarrow$ 0.11}

Version 0.11 introduced new, optional components.
The core library itself, however, mainly received optimizations and bugfixes with one exception: the member function \lstinline^on_exit^ is no longer virtual.
You can still provide it to define a custom exit handler, but you must not use \lstinline^override^.

\clearpage
\subsubsection{0.11 $\Rightarrow$ 0.12}

Version 0.12 removed two features:

\begin{itemize}
\item
Type names are no longer demangled automatically.
Hence, users must explicitly pass the type name as first argument when using \lstinline^announce^, i.e., \lstinline^announce<my_class>(...)^ becomes \lstinline^announce<my_class>("my_class", ...)^.

\item
Synchronous send blocks no longer support \lstinline^continue_with^.
This feature has been removed without substitution.
\end{itemize}

\subsubsection{0.12 $\Rightarrow$ 0.13}

This release removes the (since 0.9 deprecated) \lstinline^cppa^ headers and deprecates all \lstinline^*_send_tuple^ versions (simply use the function without \lstinline^_tuple^ suffix). \lstinline^local_actor::on_exit^ once again became virtual.

In case you were using the old \lstinline^cppa::options_description^ API, you can migrate to the new API based on \lstinline^extract^ (cf. \ref{Sec::Messages::ExtractOpts}).

Most importantly, version 0.13 slightly changes \lstinline^last_dequeued^ and \lstinline^last_sender^.
Both functions will now cause undefined behavior (dereferencing a \lstinline^nullptr^) instead of returning dummy values when accessed from outside a callback or after forwarding the current message.
Besides, these function names were not a good choice in the first place, since ``last'' implies accessing data received in the past.
As a result, both functions are now deprecated.
Their replacements are named \lstinline^current_message^ and \lstinline^current_sender^ (cf. Section \ref{Sec::Actors::Interfaces}).

\subsubsection{0.13 $\Rightarrow$ 0.14}

The function \lstinline^timed_sync_send^ has been removed. It offered an alternative way of defining message handlers, which is inconsistent with the rest of the API.

The policy classes \lstinline^broadcast^, \lstinline^random^, and \lstinline^round_robin^ in \lstinline^actor_pool^ were removed and replaced by factory functions using the same name.