Commit afb81c15 authored by Dominik Charousset's avatar Dominik Charousset

Updated manual entry for brokers

parent 1e8692e9
...@@ -42,6 +42,7 @@ actor spawn_io_server(F fun, uint16_t port, Ts&&... args); ...@@ -42,6 +42,7 @@ actor spawn_io_server(F fun, uint16_t port, Ts&&... args);
\clearpage \clearpage
\subsection{Broker Interface} \subsection{Broker Interface}
\label{Sec::NetworkIO::BrokerInterface}
\begin{lstlisting} \begin{lstlisting}
class broker; class broker;
...@@ -49,36 +50,26 @@ class broker; ...@@ -49,36 +50,26 @@ class broker;
{\small {\small
\begin{tabular*}{\textwidth}{m{0.51\textwidth}m{0.44\textwidth}} \begin{tabular*}{\textwidth}{m{0.51\textwidth}m{0.44\textwidth}}
\multicolumn{2}{m{\linewidth}}{\large{\textbf{Data Types}}\vspace{3pt}} \\
\\
\hline
\multicolumn{2}{m{\linewidth}}{\texttt{enum policy\_flag \{ at\_least, at\_most, exactly \}}} \\
\hline
\\
\multicolumn{2}{m{\linewidth}}{\large{\textbf{Member Functions}}\vspace{3pt}} \\ \multicolumn{2}{m{\linewidth}}{\large{\textbf{Member Functions}}\vspace{3pt}} \\
\\ \\
\hline \hline
\lstinline^void receive_policy(^ \lstinline^connection_handle hdl,^ \lstinline^policy_flag policy,^ \lstinline^size_t buffer_size)^ & Modifies the receive policy for the connection identified by \lstinline^hdl^. This will cause the middleman to enqueue the next \lstinline^new_data_msg^ after \emph{at least}, \emph{at most}, or \emph{exactly} \lstinline^buffer_size^ bytes have been read \\ \lstinline^void configure_read(^ \lstinline^connection_handle hdl,^ \lstinline^receive_policy::config config)^ & Modifies the receive policy for the connection identified by \lstinline^hdl^. This will cause the middleman to enqueue the next \lstinline^new_data_msg^ according to the given \lstinline^config^ created by \lstinline^receive_policy::exactly(x)^, \lstinline^receive_policy::at_most(x)^, or \lstinline^receive_policy::at_least(x)^ (with \lstinline^x^ denoting the number of bytes) \\
\hline
\lstinline^void write(connection_handle hdl,^ \lstinline^size_t num_bytes,^ \lstinline^const void* buf)^ & Sends data \\
\hline \hline
\lstinline^void write(connection_handle hdl,^ \lstinline^const util::buffer& buf)^ & Sends data \\ \lstinline^void write(connection_handle hdl,^ \lstinline^size_t num_bytes,^ \lstinline^const void* buf)^ & Writes data to the output buffer \\
\hline \hline
\lstinline^void write(connection_handle hdl,^ \lstinline^util::buffer&& buf)^ & Sends data \\ \lstinline^void flush(connection_handle hdl)^ & Sends the data from the output buffer \\
\hline \hline
\lstinline^template<typename F, typename... Ts>^ \lstinline^actor fork(F fun,^ \lstinline^connection_handle hdl, Ts&&... args)^ & Spawns a new broker that takes ownership of given connection \\ \lstinline^template <class F, class... Ts>^ \lstinline^actor fork(F fun,^ \lstinline^connection_handle hdl, Ts&&... args)^ & Spawns a new broker that takes ownership of given connection \\
\hline \hline
\lstinline^size_t num_connections()^ & Returns the number of open connections \\ \lstinline^size_t num_connections()^ & Returns the number of open connections \\
\hline \hline
\lstinline^connection_handle add_connection(^ \lstinline^input_stream_ptr in,^ \lstinline^output_stream_ptr out)^ & Adds a new connection from input and output stream \\ \lstinline^template <class Socket>^ \lstinline^connection_handle^ \lstinline^add_connection(Socket)^ & Adds a new connection using given socket \\
\hline \hline
\lstinline^connection_handle add_connection(^ \lstinline^stream_ptr sptr)^ & Adds a new connection from an IO stream \\ \lstinline^template <class Socket>^ \lstinline^accept_handle^ \lstinline^add_acceptor(Socket)^ & Adds a new acceptor using given socket acceptor \\
\hline \hline
\lstinline^connection_handle add_tcp_connection(^ \lstinline^native_socket_type tcp_sockfd)^ & Adds a new connection from a native TCP socket descriptor \\ \lstinline^void close(connection_handle hdl)^ & Closes a connection \\
\hline \hline
\lstinline^accept_handle add_acceptor(^ \lstinline^acceptor_uptr ptr)^ & Adds a new acceptor \\ \lstinline^void close(accept_handle hdl)^ & Closes an acceptor \\
\hline
\lstinline^accept_handle add_tcp_acceptor(^ \lstinline^native_socket_type tcp_sockfd)^ & Adds a new acceptor from a native TCP socket descriptor \\
\hline \hline
\end{tabular*} \end{tabular*}
} }
...@@ -86,44 +77,41 @@ class broker; ...@@ -86,44 +77,41 @@ class broker;
\clearpage \clearpage
\subsection{Broker-related Message Types} \subsection{Broker-related Message Types}
Brokers, just like any other dynamically typed actor, can receive messages of any type. Brokers receive system messages directly from the middleman whenever an event on one of it handles occurs.
However, it also receives system messages from the middleman:
\begin{lstlisting} \begin{lstlisting}
struct new_connection_msg { struct new_connection_msg {
accept_handle source; accept_handle source;
connection_handle handle; connection_handle handle;
}; };
\end{lstlisting} \end{lstlisting}
A \lstinline^new_connection_msg^ is received whenever a new incoming connection (identified by the \lstinline^handle^ field) has been accepted for one of the broker's accept handles (identified by the \lstinline^source^ field). Whenever a new incoming connection (identified by the \lstinline^handle^ field) has been accepted for one of the broker's accept handles, it will receive a \lstinline^new_connection_msg^.
\begin{lstlisting} \begin{lstlisting}
struct new_data_msg { struct new_data_msg {
connection_handle handle; connection_handle handle;
util::buffer buf; std::vector<char> buf;
}; };
\end{lstlisting} \end{lstlisting}
A \lstinline^new_data_msg^ is received whenever data on a connection is ready. New incoming data is transmitted to the broker using messages of type \lstinline^new_data_msg^.
The data can be accessed as buffer object (see \ref{Appendix::Buffer}). The raw bytes can be accessed as buffer object of type \lstinline^std::vector<char>^.
The amount of data, i.e., how often this message is received, can be configured using the brokers receive policy (see \ref{Sec::NetworkIO::ReceivePolicy}). The amount of data, i.e., how often this message is received, can be controlled using \lstinline^configure_read^ (see \ref{Sec::NetworkIO::BrokerInterface}).
It is worth mentioning that the buffer is re-used whenever possible. It is worth mentioning that the buffer is re-used whenever possible.
This means, as long as the broker does not create any new references to the message by copying it, the middleman will always use only a single buffer per connection. This means, as long as the broker does not create any new references to the message by copying it, the middleman will always use only a single buffer per connection.
\begin{lstlisting} \begin{lstlisting}
struct connection_closed_msg { struct connection_closed_msg {
connection_handle handle; connection_handle handle;
}; };
\end{lstlisting} \end{lstlisting}
A \lstinline^connection_closed_msg^ informs the broker that one of its connections has been closed.
\begin{lstlisting} \begin{lstlisting}
struct acceptor_closed_msg { struct acceptor_closed_msg {
accept_handle handle; accept_handle handle;
}; };
\end{lstlisting} \end{lstlisting}
A \lstinline^ acceptor_closed_msg^ informs the broker that of its acceptors has been closed.
A \lstinline^connection_closed_msg^ or \lstinline^ acceptor_closed_msg^ informs the broker that one of it handles is no longer valid.
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