Commit bb3d7991 authored by Dominik Charousset's avatar Dominik Charousset

manual update for upcoming version 0.8

parent 637d7d9a
...@@ -8,3 +8,6 @@ build-gcc/* ...@@ -8,3 +8,6 @@ build-gcc/*
Makefile Makefile
bin/* bin/*
lib/* lib/*
manual/manual.pdf
manual/build-pdf/*
manual/build-html/*
No preview for this file type
...@@ -50,7 +50,7 @@ class local_actor; ...@@ -50,7 +50,7 @@ class local_actor;
\hline \hline
\lstinline^any_tuple last_dequeued()^ & Returns the last message that was dequeued from the actor's mailbox\newline\textbf{Note}: Only set during callback invocation \\ \lstinline^any_tuple last_dequeued()^ & Returns the last message that was dequeued from the actor's mailbox\newline\textbf{Note}: Only set during callback invocation \\
\hline \hline
\lstinline^actor_ptr last_sender()^ & Returns the sender of the last dequeued message\newline\textbf{Note$_{1}$}: Only set during callback invocation\newline\textbf{Note$_{2}$}: Used by the function \lstinline^reply^ (see Section \ref{Sec::Send::Reply}) \\ \lstinline^actor_ptr last_sender()^ & Returns the sender of the last dequeued message\newline\textbf{Note$_{1}$}: Only set during callback invocation\newline\textbf{Note$_{2}$}: Used implicitly to send response messages (see Section \ref{Sec::Send::Reply}) \\
\hline \hline
\lstinline^vector<group_ptr> joined_groups()^ & Returns all subscribed groups \\ \lstinline^vector<group_ptr> joined_groups()^ & Returns all subscribed groups \\
\hline \hline
......
...@@ -25,13 +25,12 @@ Related functions, e.g., \lstinline^sync_send(...).then(...)^, behave the same, ...@@ -25,13 +25,12 @@ Related functions, e.g., \lstinline^sync_send(...).then(...)^, behave the same,
\begin{itemize} \begin{itemize}
\item \item
\lstinline^send(self->last_sender(), ...)^ is \textbf{not} equal to \lstinline^reply(...)^. \lstinline^send(self->last_sender(), ...)^ does \textbf{not} send a response message.
The two functions \lstinline^receive_response^ and \lstinline^handle_response^ will only recognize messages send via either \lstinline^reply^ or \lstinline^reply_tuple^.
\item \item
A handle returned by \lstinline^sync_send^ represents \emph{exactly one} response message. A handle returned by \lstinline^sync_send^ represents \emph{exactly one} response message.
Therefore, it is not possible to receive more than one response message. Therefore, it is not possible to receive more than one response message.
Calling \lstinline^reply^ more than once will result in lost messages and calling \lstinline^handle_response^ or \lstinline^receive_response^ more than once on a future will throw an exception. %Calling \lstinline^reply^ more than once will result in lost messages and calling \lstinline^handle_response^ or \lstinline^receive_response^ more than once on a future will throw an exception.
\item \item
The future returned by \lstinline^sync_send^ is bound to the calling actor. The future returned by \lstinline^sync_send^ is bound to the calling actor.
......
...@@ -66,13 +66,14 @@ void mirror() { ...@@ -66,13 +66,14 @@ void mirror() {
// wait for messages // wait for messages
become ( become (
// invoke this lambda expression if we receive a string // invoke this lambda expression if we receive a string
on_arg_match >> [](const string& what) { on_arg_match >> [](const string& what) -> string {
// prints "Hello World!" via aout (thread-safe cout wrapper) // prints "Hello World!" via aout (thread-safe cout wrapper)
aout << what << endl; aout << what << endl;
// replies "!dlroW olleH" // terminates this actor afterwards;
reply(string(what.rbegin(), what.rend())); // 'become' otherwise loops forever
// terminates this actor ('become' otherwise loops forever)
self->quit(); self->quit();
// replies "!dlroW olleH"
return string(what.rbegin(), what.rend());
} }
); );
} }
......
...@@ -18,7 +18,7 @@ Otherwise, the actor accepts all incoming connections (\lstinline^INADDR_ANY^). ...@@ -18,7 +18,7 @@ Otherwise, the actor accepts all incoming connections (\lstinline^INADDR_ANY^).
publish(self, 4242); publish(self, 4242);
become ( become (
on(atom("ping"), arg_match) >> [](int i) { on(atom("ping"), arg_match) >> [](int i) {
reply(atom("pong"), i); return make_cow_tuple(atom("pong"), i);
} }
); );
\end{lstlisting} \end{lstlisting}
...@@ -40,7 +40,7 @@ become ( ...@@ -40,7 +40,7 @@ become (
self->quit(); self->quit();
}, },
on(atom("pong"), arg_match) >> [](int i) { on(atom("pong"), arg_match) >> [](int i) {
reply(atom("ping"), i+1); return make_cow_tuple(atom("ping"), i+1);
} }
); );
\end{lstlisting} \end{lstlisting}
...@@ -39,55 +39,59 @@ struct printer : sb_actor<printer> { ...@@ -39,55 +39,59 @@ struct printer : sb_actor<printer> {
Note that \lstinline^sb_actor^ uses the Curiously Recurring Template Pattern. Thus, the derived class must be given as template parameter. Note that \lstinline^sb_actor^ uses the Curiously Recurring Template Pattern. Thus, the derived class must be given as template parameter.
This technique allows \lstinline^sb_actor^ to access the \lstinline^init_state^ member of a derived class. This technique allows \lstinline^sb_actor^ to access the \lstinline^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. The following example illustrates a more advanced state-based actor that implements a stack with a fixed maximum number of elements.
Note that this example uses non-static member initialization and thus might not compile with some compilers.
\clearpage \clearpage
\begin{lstlisting} \begin{lstlisting}
class fixed_stack : public sb_actor<fixed_stack> { class fixed_stack : public sb_actor<fixed_stack> {
// grant access to the private init_state member
friend class sb_actor<fixed_stack>; friend class sb_actor<fixed_stack>;
static constexpr size_t max_size = 10; size_t max_size = 10;
std::vector<int> data; vector<int> data;
behavior empty = ( behavior full;
on(atom("push"), arg_match) >> [=](int what) { behavior filled;
data.push_back(what); 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); become(filled);
}, return {atom("ok"), result};
on(atom("pop")) >> [=]() {
reply(atom("failure"));
} }
); );
filled = (
behavior filled = (
on(atom("push"), arg_match) >> [=](int what) { on(atom("push"), arg_match) >> [=](int what) {
data.push_back(what); data.push_back(what);
if (data.size() == max_size) if (data.size() == max_size) become(full);
become(full);
}, },
on(atom("pop")) >> [=]() { on(atom("pop")) >> [=]() -> cow_tuple<atom_value, int> {
reply(atom("ok"), data.back()); auto result = data.back();
data.pop_back(); data.pop_back();
if (data.empty()) if (data.empty()) become(empty);
become(empty); return {atom("ok"), result};
} }
); );
empty = (
behavior full = ( on(atom("push"), arg_match) >> [=](int what) {
on(atom("push"), arg_match) >> [=](int) { }, data.push_back(what);
on(atom("pop")) >> [=]() {
reply(atom("ok"), data.back());
data.pop_back();
become(filled); become(filled);
},
on(atom("pop")) >> [=] {
return atom("failure");
} }
); );
behavior& init_state = empty; }
}; };
\end{lstlisting} \end{lstlisting}
......
...@@ -35,24 +35,18 @@ Choosing one or the other is merely a matter of personal preferences. ...@@ -35,24 +35,18 @@ Choosing one or the other is merely a matter of personal preferences.
\subsection{Replying to Messages} \subsection{Replying to Messages}
\label{Sec::Send::Reply} \label{Sec::Send::Reply}
The return value of a message handler is used as response message.
During callback invokation, \lstinline^self->last_sender()^ is set. During callback invokation, \lstinline^self->last_sender()^ is set.
This identifies the sender of the received message and is used implicitly by the functions \lstinline^reply^ and \lstinline^reply_tuple^. This identifies the sender of the received message and is used implicitly to reply to the correct sender.
However, using \lstinline^send(self->last_sender(), ...)^ does \emph{not} reply to the message, i.e., synchronous messages will not recognize the message as response.
Using \lstinline^reply(...)^ is \textbf{not} equal to \lstinline^send(self->last_sender(), ...)^.
The function \lstinline^send^ always uses asynchronous message passing, whereas \lstinline^reply^ will send a synchronous response message if the received message was a synchronous request (see Section \ref{Sec::Sync}).
%Note that you cannot reply more than once.
To delay a response, i.e., reply to a message after receiving another message, actors can use \lstinline^self->make_response_handle()^.
The functions \lstinline^reply_to^ and \lstinline^reply_tuple_to^ then can be used to reply the the original request, as shown in the example below.
\begin{lstlisting} \begin{lstlisting}
void broker(const actor_ptr& master) { void client(const actor_ptr& master) {
become ( become (
on("foo", arg_match) >> [=](const std::string& request) { on("foo", arg_match) >> [=](const string& request) -> string {
auto hdl = make_response_handle(); return sync_send(master, atom("bar"), request).then(
sync_send(master, atom("bar"), request).then(
on_arg_match >> [=](const std::string& response) { on_arg_match >> [=](const std::string& response) {
reply_to(hdl, response); return response;
} }
); );
} }
...@@ -60,9 +54,6 @@ void broker(const actor_ptr& master) { ...@@ -60,9 +54,6 @@ void broker(const actor_ptr& master) {
}; };
\end{lstlisting} \end{lstlisting}
In any case, do never reply than more than once.
Additional (synchronous) response message will be ignored by the receiver.
\clearpage \clearpage
\subsection{Chaining} \subsection{Chaining}
\label{Sec::Send::ChainedSend} \label{Sec::Send::ChainedSend}
......
\section{Strongly Typed Actors} \section{Strongly Typed Actors}
Strongly typed actors provide a convenient way of defining type-safe messaging interfaces.
Unlike ``dynamic actors'', typed actors are not allowed to change their behavior at runtime, neither are typed actors allowed to use guard expressions.
When calling \lstinline^become^ in a strongly typed actor, the actor will be killed with exit reason \lstinline^unallowed_function_call^.
Typed actors use \lstinline^typed_actor_ptr<...>^ instead of \lstinline^actor_ptr^, whereas the template parameters hold the messaging interface.
For example, an actor responding to two integers with a dobule would use the type \lstinline^typed_actor_ptr<replies_to<int, int>::with<double>>^.
\subsection{Spawning Typed Actors}
\label{sec:strong:spawn}
Actors are spawned using the function \lstinline^spawn_typed^.
The argument to this function call \emph{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.
\begin{lstlisting}
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>
>;
subtype1 p3 = p0;
\end{lstlisting}
All functions for message passing, linking and monitoring are overloaded to accept both types of actors.
As of version 0.8, strongly typed actors cannot be published (this is a planned feature for future releases).
\ No newline at end of file
...@@ -35,7 +35,7 @@ When using synchronous messaging, \libcppa's runtime environment will send ... ...@@ -35,7 +35,7 @@ When using synchronous messaging, \libcppa's runtime environment will send ...
\begin{itemize} \begin{itemize}
\item \lstinline^{'EXITED', uint32_t exit_reason}^ if the receiver is not alive \item \lstinline^{'EXITED', uint32_t exit_reason}^ if the receiver is not alive
\item \lstinline^{'VOID'}^ if the receiver handled the message but did not call \lstinline^reply^ \item \lstinline^{'VOID'}^ if the receiver handled the message but did not respond to it
\item \lstinline^{'TIMEOUT'}^ if a message send by \lstinline^timed_sync_send^ timed out \item \lstinline^{'TIMEOUT'}^ if a message send by \lstinline^timed_sync_send^ timed out
\end{itemize} \end{itemize}
...@@ -120,10 +120,11 @@ sync_send(testee, atom("get")).then( ...@@ -120,10 +120,11 @@ sync_send(testee, atom("get")).then(
); );
\end{lstlisting} \end{lstlisting}
\clearpage
\subsubsection{Continuations for Event-based Actors} \subsubsection{Continuations for Event-based Actors}
\libcppa supports continuations to enable chaining of send/receive statements. \libcppa supports continuations to enable chaining of send/receive statements.
The functions \lstinline^handle_response^ and \lstinline^message_future::then^ both return a helper object offering \lstinline^continue_with^, which takes a functor $f$ without arguments. The functions \lstinline^handle_response^ and \lstinline^message_future::then^ both return a helper object offering the member function \lstinline^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 \lstinline^sync_failure^ nor \lstinline^sync_timeout^ occurred. After receiving a message, $f$ is invoked if and only if the received messages was handled successfully, i.e., neither \lstinline^sync_failure^ nor \lstinline^sync_timeout^ occurred.
\begin{lstlisting} \begin{lstlisting}
......
...@@ -4,52 +4,27 @@ ...@@ -4,52 +4,27 @@
12pt,% % 12pt Schriftgröße 12pt,% % 12pt Schriftgröße
]{article} ]{article}
%\usepackage{ifpdf}
%\usepackage[english]{babel}
% UTF8 input
\usepackage[utf8]{inputenc} \usepackage[utf8]{inputenc}
% grafics % include required packages
%\usepackage{graphicx}
%\usepackage{picinpar}
% others
%\usepackage{parcolumns}
%\usepackage[font=footnotesize,format=plain,labelfont=bf]{caption}
%\usepackage{paralist}
\usepackage{url} \usepackage{url}
\usepackage{array} \usepackage{array}
%\usepackage{tocloft}
\usepackage{color} \usepackage{color}
\usepackage{listings} \usepackage{listings}
\usepackage{xspace} \usepackage{xspace}
\usepackage{tabularx} \usepackage{tabularx}
\usepackage{hyperref} \usepackage{hyperref}
\usepackage{fancyhdr} \usepackage{fancyhdr}
\usepackage{multicol} \usepackage{multicol}
% HTML compilation
\usepackage{hevea} \usepackage{hevea}
% font setup
\usepackage{cmbright} \usepackage{cmbright}
\usepackage{txfonts} \usepackage{txfonts}
\usepackage[scaled=.90]{helvet} \usepackage[scaled=.90]{helvet}
\usepackage{courier} \usepackage{courier}
%\usepackage{natbib}
%\usepackage{lmodern}
%\usepackage{newcent}
%\renewcommand{\ttdefault}{lmtt}
%\usepackage{fontspec}
%\defaultfontfeatures{Mapping=tex-text} % For archaic input (e.g. convert -- to en-dash)
%\setmainfont{Times New Roman} % Computer Modern Unicode font
%\setmonofont{Anonymous Pro}
%\setsansfont{Times New Roman}
% par. settings % par. settings
\parindent 0pt \parindent 0pt
...@@ -77,17 +52,16 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill} ...@@ -77,17 +52,16 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill}
\date{\today} \date{\today}
% page setup % page setup
\setlength{\voffset}{-0.5in} \setlength{\voffset}{-0.5in}
\setlength{\hoffset}{-0.5in} \setlength{\hoffset}{-0.5in}
\addtolength{\textwidth}{1in} \addtolength{\textwidth}{1in}
\addtolength{\textheight}{1.5in} \addtolength{\textheight}{1.5in}
\setlength{\headheight}{15pt} \setlength{\headheight}{15pt}
% some HEVEA / HTML style sheets % some HEVEA / HTML style sheets
\newstyle{body}{width:600px;margin:auto;padding-top:20px;text-align: justify;} \newstyle{body}{width:600px;margin:auto;padding-top:20px;text-align: justify;}
% more compact itemize
\newenvironment{itemize*}% \newenvironment{itemize*}%
{\begin{itemize}% {\begin{itemize}%
\setlength{\itemsep}{0pt}% \setlength{\itemsep}{0pt}%
...@@ -95,8 +69,8 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill} ...@@ -95,8 +69,8 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill}
{\end{itemize}} {\end{itemize}}
\begin{document} \begin{document}
%\fontfamily{ptm}\selectfont
% fancy header setup
%BEGIN LATEX %BEGIN LATEX
\fancypagestyle{plain}{% \fancypagestyle{plain}{%
\fancyhf{} % clear all header and footer fields \fancyhf{} % clear all header and footer fields
...@@ -104,12 +78,14 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill} ...@@ -104,12 +78,14 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill}
\renewcommand{\footrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt}
} }
%END LATEX %END LATEX
\maketitle \maketitle
\clearpage \clearpage
\pagestyle{empty} \pagestyle{empty}
\tableofcontents \tableofcontents
\clearpage \clearpage
% fancy header setup for page 1
%BEGIN LATEX %BEGIN LATEX
\setcounter{page}{1} \setcounter{page}{1}
\pagenumbering{arabic} \pagenumbering{arabic}
...@@ -121,9 +97,7 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill} ...@@ -121,9 +97,7 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill}
} }
%END LATEX %END LATEX
%{\parskip=0mm \tableofcontents} % code listings setup
% basic setup for listings
\lstset{% \lstset{%
language=C++,% language=C++,%
morekeywords={constexpr,nullptr,size_t,uint32_t,assert},% morekeywords={constexpr,nullptr,size_t,uint32_t,assert},%
...@@ -137,6 +111,7 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill} ...@@ -137,6 +111,7 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill}
numberstyle=\footnotesize% numberstyle=\footnotesize%
} }
% content
\include{FirstSteps} \include{FirstSteps}
\include{CopyOnWriteTuples} \include{CopyOnWriteTuples}
\include{PatternMatching} \include{PatternMatching}
...@@ -147,21 +122,13 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill} ...@@ -147,21 +122,13 @@ User Manual\\\normalsize{\texttt{libcppa} version 0.8}\vfill}
\include{ActorManagement} \include{ActorManagement}
\include{SpawningActors} \include{SpawningActors}
\include{MessagePriorities} \include{MessagePriorities}
\include{StronglyTypedActors}
\include{NetworkTransparency} \include{NetworkTransparency}
\include{GroupCommunication} \include{GroupCommunication}
\include{ActorCompanions} \include{ActorCompanions}
\include{TypeSystem} \include{TypeSystem}
\include{BlockingAPI} \include{BlockingAPI}
%\include{OpenCL} \include{StronglyTypedActors}
\include{CommonPitfalls} \include{CommonPitfalls}
\include{Appendix} \include{Appendix}
%\clearpage
%\bibliographystyle{dinat}
%\bibliographystyle{apalike}
%\bibliography{/bib/programming,/bib/rfcs}
%\clearpage
%{\parskip=0mm \listoffigures}
%\clearpage
\end{document} \end{document}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment