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);
\clearpage
\subsection{Broker Interface}
\label{Sec::NetworkIO::BrokerInterface}
\begin{lstlisting}
class broker;
......@@ -49,36 +50,26 @@ class broker;
{\small
\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}} \\
\\
\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 \\
\hline
\lstinline^void write(connection_handle hdl,^ \lstinline^size_t num_bytes,^ \lstinline^const void* buf)^ & Sends data \\
\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^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
\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
\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
\lstinline^size_t num_connections()^ & Returns the number of open connections \\
\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
\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
\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
\lstinline^accept_handle add_acceptor(^ \lstinline^acceptor_uptr ptr)^ & Adds a new acceptor \\
\hline
\lstinline^accept_handle add_tcp_acceptor(^ \lstinline^native_socket_type tcp_sockfd)^ & Adds a new acceptor from a native TCP socket descriptor \\
\lstinline^void close(accept_handle hdl)^ & Closes an acceptor \\
\hline
\end{tabular*}
}
......@@ -86,44 +77,41 @@ class broker;
\clearpage
\subsection{Broker-related Message Types}
Brokers, just like any other dynamically typed actor, can receive messages of any type.
However, it also receives system messages from the middleman:
Brokers receive system messages directly from the middleman whenever an event on one of it handles occurs.
\begin{lstlisting}
struct new_connection_msg {
accept_handle source;
connection_handle handle;
accept_handle source;
connection_handle handle;
};
\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}
struct new_data_msg {
connection_handle handle;
util::buffer buf;
connection_handle handle;
std::vector<char> buf;
};
\end{lstlisting}
A \lstinline^new_data_msg^ is received whenever data on a connection is ready.
The data can be accessed as buffer object (see \ref{Appendix::Buffer}).
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}).
New incoming data is transmitted to the broker using messages of type \lstinline^new_data_msg^.
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 controlled using \lstinline^configure_read^ (see \ref{Sec::NetworkIO::BrokerInterface}).
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.
\begin{lstlisting}
struct connection_closed_msg {
connection_handle handle;
connection_handle handle;
};
\end{lstlisting}
A \lstinline^connection_closed_msg^ informs the broker that one of its connections has been closed.
\begin{lstlisting}
struct acceptor_closed_msg {
accept_handle handle;
accept_handle handle;
};
\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