@@ -197,7 +197,7 @@ This feature has been removed without substitution.
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).
In case you were using the old \lstinline^cppa::options_description^ API, you can migrate to the new API for filtering command line arguments (cf. \ref{Sec::Messages::FilterCLI}).
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.
@@ -93,18 +93,19 @@ However, the classes \lstinline^message^ and \lstinline^message_builder^ allow m
}
\clearpage
\subsection{Filtering}
\label{Sec::Messages::Filter}
\subsection{Extracting}
\label{Sec::Messages::Extract}
The member function \lstinline^message::extract^ removes matched elements from a message. x
Messages are filtered by repeatedly applying a message handler to the greatest remaining slice, whereas slices are generated in the sequence \lstinline^[0, size)^, \lstinline^[0, size-1)^, \lstinline^...^, \lstinline^[1, size-1)^, \lstinline^...^, \lstinline^[size-1, size)^.
Whenever a slice matches, it is removed from the message and the next slice starts at the same index on the reduced message.
Whenever a slice is matched, it is removed from the message and the next slice starts at the same index on the reduced message.
For example:
\begin{lstlisting}
auto msg = make_message(1, 2.f, 3.f, 4);
// filter float and integer pairs
auto msg2 = msg.filter({
// remove float and integer pairs
auto msg2 = msg.extract({
[](float, float) {},
[](int, int) {}
});
...
...
@@ -123,20 +124,20 @@ Step-by-step explanation:
\item Slice 7: \lstinline^(4)^, no match
\end{itemize}
Slice 7 is \lstinline^(4)^, i.e., does not contain the first element, because the match on slice 6 occurred at index position 1. The function filter iterates a message only once, from left to right. The result of \lstinline^message::filter^ is the remainder, i.e., a message consisting of all unmatched elements.
Slice 7 is \lstinline^(4)^, i.e., does not contain the first element, because the match on slice 6 occurred at index position 1. The function \lstinline^extract^ iterates a message only once, from left to right.
The returned message contains the remaining, i.e., unmatched, elements.
\clearpage
\subsection{Filter and Command Line Arguments}
\label{Sec::Messages::FilterCLI}
\subsection{Extracting Command Line Options}
\label{Sec::Messages::ExtractOpts}
The class \lstinline^message^ also contains a convenience interface to \lstinline^filter^ for parsing command line arguments: \lstinline^filter_cli^.
This member function provides a simplistic interface for defining a command line argument parsers:
The class \lstinline^message^ also contains a convenience interface to \lstinline^extract^ for parsing command line options: the member function \lstinline^extract_opts^.
\begin{lstlisting}
int main(int argc, char** argv) {
uint16_t port;
string host = "localhost";
auto res = message_builder(argv + 1, argv + argc).filter_cli({
auto res = message_builder(argv + 1, argv + argc).extract_opts({
@@ -166,7 +166,7 @@ Thus, you should not depend on a certain clock resolution.
Unmatched messages are skipped automatically by \lib's runtime system.
This is true for \textit{all} actor implementations.
To allow actors to skip messages manually, \lstinline^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 \lstinline^others()^ to filter messages that are not handled by any of its behaviors.
This is in particular useful whenever an actor switches between behaviors, but wants to use a default rule created by \lstinline^others()^ to catch 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 \lstinline^'idle'^ message, it awaits a request that is then forwarded to the idle worker.