Commit 1acbb5c6 authored by Dominik Charousset's avatar Dominik Charousset

Merge branch 'topic/integrate-manual'

parents 5042ac89 f0de546e
...@@ -597,78 +597,60 @@ if(NOT CAF_NO_UNIT_TESTS) ...@@ -597,78 +597,60 @@ if(NOT CAF_NO_UNIT_TESTS)
endif() endif()
################################################################################ # -- Fetch branch name and SHA if available ------------------------------------
# Doxygen setup #
################################################################################
# check for doxygen and add custom "doc" target to Makefile
find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/doc/Doxyfile.in"
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile"
@ONLY)
add_custom_target(doc "${DOXYGEN_EXECUTABLE}"
"${CMAKE_HOME_DIRECTORY}/Doxyfile"
WORKING_DIRECTORY "${CMAKE_HOME_DIRECTORY}"
COMMENT "Generating API documentation with Doxygen"
VERBATIM)
endif(DOXYGEN_FOUND)
################################################################################ if(EXISTS "release.txt")
# Manual setup # file(READ "release.txt" CAF_VESION)
################################################################################ else()
set(CAF_RELEASE "${CAF_VERSION}")
set(MANUAL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/manual") find_package(Git QUIET)
if(EXISTS "${MANUAL_DIR}" if(GIT_FOUND)
AND EXISTS "${MANUAL_DIR}/variables.tex.in" # retrieve current branch name for CAF
AND EXISTS "${MANUAL_DIR}/conf.py.in") execute_process(COMMAND ${GIT_EXECUTABLE} rev-parse --abbrev-ref HEAD
# retrieve current branch name for CAF
execute_process(COMMAND git rev-parse --abbrev-ref HEAD
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE GIT_BRANCH
OUTPUT_STRIP_TRAILING_WHITESPACE)
# retrieve current SHA1 hash for CAF
execute_process(COMMAND git log --pretty=format:%h -n 1
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE CAF_SHA
OUTPUT_STRIP_TRAILING_WHITESPACE)
# retrieve current SHA1 hash for the Manual
execute_process(COMMAND git log --pretty=format:%h -n 1
WORKING_DIRECTORY ${MANUAL_DIR}
OUTPUT_VARIABLE CAF_MANUAL_SHA
OUTPUT_STRIP_TRAILING_WHITESPACE)
if(${GIT_BRANCH} STREQUAL "master")
# retrieve current tag name for CAF
execute_process(COMMAND git describe --tags --contains ${CAF_SHA}
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
RESULT_VARIABLE GIT_TAG_RES RESULT_VARIABLE gitBranchResult
OUTPUT_VARIABLE GIT_TAG OUTPUT_VARIABLE gitBranch
ERROR_QUIET ERROR_QUIET
OUTPUT_STRIP_TRAILING_WHITESPACE) OUTPUT_STRIP_TRAILING_WHITESPACE)
# prefer tag name over auto-generated version # retrieve current SHA1 hash for CAF
if(GIT_TAG_RES STREQUAL "0") execute_process(COMMAND ${GIT_EXECUTABLE} log --pretty=format:%h -n 1
set(CAF_RELEASE "${GIT_TAG}") WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
else() RESULT_VARIABLE gitShaResult
set(CAF_RELEASE "${CAF_VERSION}") OUTPUT_VARIABLE gitSha
ERROR_QUIET
OUTPUT_STRIP_TRAILING_WHITESPACE)
if(gitBranchResult EQUAL 0 AND gitShaResult EQUAL 0)
# generate semantic CAF version for manual
set(CAF_RELEASE "${CAF_VERSION}+exp.sha.${gitSha}")
# check whether we're building the manual for a stable release
if(gitBranch STREQUAL "master")
# retrieve current tag name for CAF
execute_process(COMMAND ${GIT_EXECUTABLE} describe --tags --contains ${gitSha}
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
RESULT_VARIABLE gitTagResult
OUTPUT_VARIABLE gitTag
ERROR_QUIET
OUTPUT_STRIP_TRAILING_WHITESPACE)
# tags indicate stable releases -> use tag name as release version
if(gitTagResult EQUAL 0)
set(CAF_RELEASE "${gitTag}")
endif()
endif()
endif() endif()
else()
set(CAF_RELEASE "${CAF_VERSION}+exp.sha.${CAF_SHA}")
endif() endif()
MESSAGE(STATUS "Set manual version to ${CAF_RELEASE}")
configure_file("${MANUAL_DIR}/variables.tex.in"
"${MANUAL_DIR}/variables.tex"
IMMEDIATE @ONLY)
configure_file("${MANUAL_DIR}/conf.py.in"
"${MANUAL_DIR}/conf.py"
IMMEDIATE @ONLY)
configure_file("${MANUAL_DIR}/index_header.rst.in"
"${MANUAL_DIR}/index_header.rst"
IMMEDIATE @ONLY)
configure_file("${MANUAL_DIR}/index_footer.rst.in"
"${MANUAL_DIR}/index_footer.rst"
IMMEDIATE @ONLY)
endif() endif()
message(STATUS "Set release version for all documentation to ${CAF_RELEASE}.")
# -- Setup for building manual and API documentation ---------------------------
# we need the examples and some headers relative to the build/doc/tex directory
file(COPY examples/ DESTINATION examples)
file(COPY libcaf_core/caf/exit_reason.hpp DESTINATION libcaf_core/caf/)
file(COPY libcaf_core/caf/sec.hpp DESTINATION libcaf_core/caf/)
add_subdirectory(doc)
################################################################################ ################################################################################
# Add additional project files to GUI # # Add additional project files to GUI #
################################################################################ ################################################################################
......
...@@ -198,11 +198,12 @@ pipeline { ...@@ -198,11 +198,12 @@ pipeline {
deleteDir() deleteDir()
dir('caf-sources') { dir('caf-sources') {
checkout scm checkout scm
sh './scripts/get-release-version.sh'
} }
stash includes: 'caf-sources/**', name: 'caf-sources' stash includes: 'caf-sources/**', name: 'caf-sources'
} }
} }
// Start builds. /*
stage('Builds') { stage('Builds') {
steps { steps {
script { script {
...@@ -222,6 +223,54 @@ pipeline { ...@@ -222,6 +223,54 @@ pipeline {
} }
} }
} }
*/
stage('Documentation') {
agent { label 'pandoc' }
steps {
deleteDir()
unstash('caf-sources')
dir('caf-sources') {
// Configure and build.
cmakeBuild([
buildDir: 'build',
installation: 'cmake in search path',
sourceDir: '.',
steps: [[
args: '--target doc',
withCmake: true,
]],
])
sshagent(['84d71a75-cbb6-489a-8f4c-d0e2793201e9']) {
sh '''
if [ "$(cat branch.txt)" = "master" ]; then
rsync -e "ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" -r -z --delete build/doc/html/ www.inet.haw-hamburg.de:/users/www/www.actor-framework.org/html/doc
scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null build/doc/manual.pdf www.inet.haw-hamburg.de:/users/www/www.actor-framework.org/html/pdf/manual.pdf
fi
'''
}
}
dir('read-the-docs') {
git([
credentialsId: '9b054212-9bb4-41fd-ad8e-b7d47495303f',
url: 'git@github.com:actor-framework/read-the-docs.git',
])
sh '''
if [ "$(cat ../caf-sources/branch.txt)" = "master" ]; then
cp ../caf-sources/build/doc/rst/* .
if [ -n "$(git status --porcelain)" ]; then
git add .
git commit -m "Update Manual"
git push --set-upstream origin master
if [ -z "$(grep 'exp.sha' ../caf-sources/release.txt)" ] ; then
git tag $(cat ../caf-sources/release.txt)
git push origin $(cat ../caf-sources/release.txt)
fi
fi
fi
'''
}
}
}
} }
post { post {
success { success {
......
...@@ -119,6 +119,12 @@ A SNocs workspace is provided by GitHub user ...@@ -119,6 +119,12 @@ A SNocs workspace is provided by GitHub user
* FreeBSD 10 * FreeBSD 10
* Windows >= 7 (currently static builds only) * Windows >= 7 (currently static builds only)
## Optional Dependencies
* Doxygen (for the `doxygen` target)
* LaTeX (for the `manual` target)
* Pandoc and Python with pandocfilters (for the `rst` target)
## Scientific Use ## Scientific Use
If you use CAF in a scientific context, please use one of the following citations: If you use CAF in a scientific context, please use one of the following citations:
......
cmake_minimum_required(VERSION 3.10)
project(doc NONE)
add_custom_target(doc)
# -- list all .tex source files ------------------------------------------------
set(sources
tex/Actors.tex
tex/Brokers.tex
tex/CommonPitfalls.tex
tex/ConfiguringActorApplications.tex
tex/Error.tex
tex/FAQ.tex
tex/FirstSteps.tex
tex/GroupCommunication.tex
tex/Introduction.tex
tex/ManagingGroupsOfWorkers.tex
tex/MessageHandlers.tex
tex/MessagePassing.tex
tex/Messages.tex
tex/MigrationGuides.tex
tex/NetworkTransparency.tex
tex/OpenCL.tex
tex/ReferenceCounting.tex
tex/Registry.tex
tex/RemoteSpawn.tex
tex/Scheduler.tex
tex/Streaming.tex
tex/TypeInspection.tex
tex/UsingAout.tex
tex/Utility.tex
)
# -- process .in files -----------------------------------------------------
configure_file("cmake/Doxyfile.in"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
@ONLY)
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/tex")
configure_file("cmake/variables.tex.in"
"${CMAKE_CURRENT_BINARY_DIR}/tex/variables.tex"
@ONLY)
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/rst")
configure_file("cmake/conf.py.in"
"${CMAKE_CURRENT_BINARY_DIR}/rst/conf.py"
@ONLY)
configure_file("cmake/index_footer.rst.in"
"${CMAKE_CURRENT_BINARY_DIR}/rst/index_footer.rst"
@ONLY)
configure_file("cmake/index_header.rst.in"
"${CMAKE_CURRENT_BINARY_DIR}/rst/index_header.rst"
@ONLY)
# -- Doxygen setup -------------------------------------------------------------
find_package(Doxygen)
if(NOT DOXYGEN_FOUND)
message(STATUS "Doxygen not found, skip building API documentation.")
else()
message(STATUS "Add optional target: doxygen.")
add_custom_target(doxygen "${DOXYGEN_EXECUTABLE}"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
COMMENT "Generating API documentation with Doxygen"
VERBATIM)
add_dependencies(doc doxygen)
endif()
# -- Pandoc utility macro ------------------------------------------------------
macro(generate_rst texfile)
get_filename_component(rstfile_we "${texfile}" NAME_WE)
set(rstfile "${rstfile_we}.rst")
set(bin_texfile "${CMAKE_CURRENT_BINARY_DIR}/${texfile}")
add_custom_target("${rstfile}"
DEPENDS "${bin_texfile}"
COMMAND ${PANDOC_EXECUTABLE}
"--filter=${CMAKE_SOURCE_DIR}/scripts/pandoc-filter.py"
--wrap=none -f latex
-o "${CMAKE_CURRENT_BINARY_DIR}/rst/${rstfile}"
"${bin_texfile}"
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/rst")
add_dependencies(rst "${rstfile}")
endmacro()
# -- LaTeX setup ---------------------------------------------------------------
find_package(LATEX QUIET)
if(NOT LATEX_FOUND)
message(STATUS "LaTeX not found, skip building manual.")
else()
message(STATUS "Add optional target: manual.")
include("cmake/UseLATEX.cmake")
# enable synctex for convenient editing
set(LATEX_USE_SYNCTEX yes)
# add manual.pdf as target
add_latex_document(tex/manual.tex
INPUTS ${sources} "tex/variables.tex"
IMAGE_DIRS "pdf"
FORCE_PDF
TARGET_NAME manual)
add_dependencies(doc manual)
find_program(PANDOC_EXECUTABLE pandoc)
if(NOT EXISTS ${PANDOC_EXECUTABLE})
message(STATUS "Pandoc not found, skip generating reFormattedText version of the manual.")
else()
execute_process(COMMAND "python" "-c"
"from pandocfilters import toJSONFilter; print('ok')"
RESULT_VARIABLE has_pandocfilters
OUTPUT_QUIET
ERROR_QUIET)
if(NOT ${has_pandocfilters} EQUAL 0)
message(STATUS "Python with pandocfilters not found, skip generating reFormattedText version of the manual.")
else()
message(STATUS "Add optional target: rst.")
add_custom_target(rst)
add_dependencies(doc rst)
foreach(texfile ${sources})
generate_rst(${texfile})
endforeach()
endif()
endif()
endif()
This diff is collapsed.
This diff is collapsed.
# -*- coding: utf-8 -*-
#
# CAF documentation build configuration file, created by
# sphinx-quickstart on Fri Jun 3 11:27:36 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
import sphinx_rtd_theme
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'CAF'
copyright = u'2016, Dominik Charousset'
author = u'Dominik Charousset'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'@CAF_VERSION@'
# The full version, including alpha/beta/rc tags.
release = u'@CAF_RELEASE@'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
highlight_language = 'C++'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = u'CAF v0.15'
# A shorter title for the navigation bar. Default is the same as html_title.
#
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}
# If false, no module index is generated.
#
# html_domain_indices = True
# If false, no index is generated.
#
# html_use_index = True
# If true, the index is split into individual pages for each letter.
#
# html_split_index = False
# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'CAFdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'CAF.tex', u'CAF Documentation',
u'Dominik Charousset', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#
# latex_use_parts = False
# If true, show page references after internal links.
#
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
#
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
#
# latex_appendices = []
# If false, no module index is generated.
#
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'caf', u'CAF Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'CAF', u'CAF Documentation',
author, 'CAF', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []
# If false, no module index is generated.
#
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False
Version Information
===================
This version of the Manual was automatically generated from CAF commit
`@CAF_SHA@ <https://github.com/actor-framework/actor-framework/commit/@CAF_SHA@>`_.
CAF User Manual
===============
**C++ Actor Framework** version @CAF_RELEASE@.
Contents
========
\newcommand{\cafrelease}{@CAF_RELEASE@}
\newcommand{\cafsha}{@CAF_SHA@}
This diff is collapsed.
\section{Network I/O with Brokers}
\label{broker}
When communicating to other services in the network, sometimes low-level socket
I/O is inevitable. For this reason, CAF provides \emph{brokers}. A broker is
an event-based actor running in the middleman that multiplexes socket I/O. It
can maintain any number of acceptors and connections. Since the broker runs in
the middleman, implementations should be careful to consume as little time as
possible in message handlers. Brokers should outsource any considerable amount
of work by spawning new actors or maintaining worker actors.
\textit{Note that all UDP-related functionality is still \experimental.}
\subsection{Spawning Brokers}
Brokers are implemented as functions and are spawned by calling on of the three
following member functions of the middleman.
\begin{lstlisting}
template <spawn_options Os = no_spawn_options,
class F = std::function<void(broker*)>, class... Ts>
typename infer_handle_from_fun<F>::type
spawn_broker(F fun, Ts&&... xs);
template <spawn_options Os = no_spawn_options,
class F = std::function<void(broker*)>, class... Ts>
expected<typename infer_handle_from_fun<F>::type>
spawn_client(F fun, const std::string& host, uint16_t port, Ts&&... xs);
template <spawn_options Os = no_spawn_options,
class F = std::function<void(broker*)>, class... Ts>
expected<typename infer_handle_from_fun<F>::type>
spawn_server(F fun, uint16_t port, Ts&&... xs);
\end{lstlisting}
The function \lstinline^spawn_broker^ simply spawns a broker. The convenience
function \lstinline^spawn_client^ tries to connect to given host and port over
TCP and returns a broker managing this connection on success. Finally,
\lstinline^spawn_server^ opens a local TCP port and spawns a broker managing it
on success. There are no convenience functions spawn a UDP-based client or
server.
\subsection{Class \texttt{broker}}
\label{broker-class}
\begin{lstlisting}
void configure_read(connection_handle hdl, receive_policy::config config);
\end{lstlisting}
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).
\begin{lstlisting}
void write(connection_handle hdl, size_t num_bytes, const void* buf)
void write(datagram_handle hdl, size_t num_bytes, const void* buf)
\end{lstlisting}
Writes data to the output buffer.
\begin{lstlisting}
void enqueue_datagram(datagram_handle hdl, std::vector<char> buf);
\end{lstlisting}
Enqueues a buffer to be sent as a datagram. Use of this function is encouraged
over write as it allows reuse of the buffer which can be returned to the broker
in a \lstinline^datagram_sent_msg^.
\begin{lstlisting}
void flush(connection_handle hdl);
void flush(datagram_handle hdl);
\end{lstlisting}
Sends the data from the output buffer.
\begin{lstlisting}
template <class F, class... Ts>
actor fork(F fun, connection_handle hdl, Ts&&... xs);
\end{lstlisting}
Spawns a new broker that takes ownership of a given connection.
\begin{lstlisting}
size_t num_connections();
\end{lstlisting}
Returns the number of open connections.
\begin{lstlisting}
void close(connection_handle hdl);
void close(accept_handle hdl);
void close(datagram_handle hdl);
\end{lstlisting}
Closes the endpoint related to the handle.
\begin{lstlisting}
expected<std::pair<accept_handle, uint16_t>>
add_tcp_doorman(uint16_t port = 0, const char* in = nullptr,
bool reuse_addr = false);
\end{lstlisting}
Creates new doorman that accepts incoming connections on a given port and
returns the handle to the doorman and the port in use or an error.
\begin{lstlisting}
expected<connection_handle>
add_tcp_scribe(const std::string& host, uint16_t port);
\end{lstlisting}
Creates a new scribe to connect to host:port and returns handle to it or an
error.
\begin{lstlisting}
expected<std::pair<datagram_handle, uint16_t>>
add_udp_datagram_servant(uint16_t port = 0, const char* in = nullptr,
bool reuse_addr = false);
\end{lstlisting}
Creates a datagram servant to handle incoming datagrams on a given port.
Returns the handle to the servant and the port in use or an error.
\begin{lstlisting}
expected<datagram_handle>
add_udp_datagram_servant(const std::string& host, uint16_t port);
\end{lstlisting}
Creates a datagram servant to send datagrams to host:port and returns a handle
to it or an error.
\subsection{Broker-related Message Types}
Brokers receive system messages directly from the middleman for connection and
acceptor events.
\textbf{Note:} brokers are \emph{required} to handle these messages immediately
regardless of their current state. Not handling the system messages from the
broker results in loss of data, because system messages are \emph{not}
delivered through the mailbox and thus cannot be skipped.
\begin{lstlisting}
struct new_connection_msg {
accept_handle source;
connection_handle handle;
};
\end{lstlisting}
Indicates that \lstinline^source^ accepted a new TCP connection identified by
\lstinline^handle^.
\begin{lstlisting}
struct new_data_msg {
connection_handle handle;
std::vector<char> buf;
};
\end{lstlisting}
Contains raw bytes received from \lstinline^handle^. The amount of data
received per event is controlled with \lstinline^configure_read^ (see
\ref{broker-class}). It is worth mentioning that the buffer is re-used whenever
possible.
\begin{lstlisting}
struct data_transferred_msg {
connection_handle handle;
uint64_t written;
uint64_t remaining;
};
\end{lstlisting}
This message informs the broker that the \lstinline^handle^ sent
\lstinline^written^ bytes with \lstinline^remaining^ bytes in the buffer. Note,
that these messages are not sent per default but must be explicitly enabled via
the member function \lstinline^ack_writes^.
\begin{lstlisting}
struct connection_closed_msg {
connection_handle handle;
};
struct acceptor_closed_msg {
accept_handle handle;
};
\end{lstlisting}
A \lstinline^connection_closed_msg^ or \lstinline^acceptor_closed_msg^ informs
the broker that one of its handles is no longer valid.
\begin{lstlisting}
struct connection_passivated_msg {
connection_handle handle;
};
struct acceptor_passivated_msg {
accept_handle handle;
};
\end{lstlisting}
A \lstinline^connection_passivated_msg^ or \lstinline^acceptor_passivated_msg^
informs the broker that one of its handles entered passive mode and no longer
accepts new data or connections \see{trigger}.
The following messages are related to UDP communication
(see~\sref{transport-protocols}. Since UDP is not connection oriented, there is
no equivalent to the \lstinline^new_connection_msg^ of TCP.
\begin{lstlisting}
struct new_datagram_msg {
datagram_handle handle;
network::receive_buffer buf;
};
\end{lstlisting}
Contains the raw bytes from \lstinline^handle^. The buffer always has a maximum
size of 65k to receive all regular UDP messages. The amount of bytes can be
queried via the \lstinline^.size()^ member function. Similar to TCP, the buffer
is reused when possible---please do not resize it.
\begin{lstlisting}
struct datagram_sent_msg {
datagram_handle handle;
uint64_t written;
std::vector<char> buf;
};
\end{lstlisting}
This message informs the broker that the \lstinline^handle^ sent a datagram of
\lstinline^written^ bytes. It includes the buffer that held the sent message to
allow its reuse. Note, that these messages are not sent per default but must be
explicitly enabled via the member function \lstinline^ack_writes^.
\begin{lstlisting}
struct datagram_servant_closed_msg {
std::vector<datagram_handle> handles;
};
\end{lstlisting}
A \lstinline^datagram_servant_closed_msg^ informs the broker that one of its
handles is no longer valid.
\begin{lstlisting}
struct datagram_servant_passivated_msg {
datagram_handle handle;
};
\end{lstlisting}
A \lstinline^datagram_servant_closed_msg^ informs the broker that one of its
handles entered passive mode and no longer accepts new data \see{trigger}.
\subsection{Manually Triggering Events \experimental}
\label{trigger}
Brokers receive new events as \lstinline^new_connection_msg^ and
\lstinline^new_data_msg^ as soon and as often as they occur, per default. This
means a fast peer can overwhelm a broker by sending it data faster than the
broker can process it. In particular if the broker outsources work items to
other actors, because work items can accumulate in the mailboxes of the
workers.
Calling \lstinline^self->trigger(x,y)^, where \lstinline^x^ is a connection or
acceptor handle and \lstinline^y^ is a positive integer, allows brokers to halt
activities after \lstinline^y^ additional events. Once a connection or acceptor
stops accepting new data or connections, the broker receives a
\lstinline^connection_passivated_msg^ or \lstinline^acceptor_passivated_msg^.
Brokers can stop activities unconditionally with \lstinline^self->halt(x)^ and
resume activities unconditionally with \lstinline^self->trigger(x)^.
\section{Common Pitfalls}
\label{pitfalls}
This Section highlights common mistakes or C++ subtleties that can show up when
programming in CAF.
\subsection{Defining Message Handlers}
\begin{itemize}
\item C++ evaluates comma-separated expressions from left-to-right, using only
the last element as return type of the whole expression. This means that
message handlers and behaviors must \emph{not} be initialized like this:
\begin{lstlisting}
message_handler wrong = (
[](int i) { /*...*/ },
[](float f) { /*...*/ }
);
\end{lstlisting}
The correct way to initialize message handlers and behaviors is to either
use the constructor or the member function \lstinline^assign^:
\begin{lstlisting}
message_handler ok1{
[](int i) { /*...*/ },
[](float f) { /*...*/ }
};
message_handler ok2;
// some place later
ok2.assign(
[](int i) { /*...*/ },
[](float f) { /*...*/ }
);
\end{lstlisting}
\end{itemize}
\subsection{Event-Based API}
\begin{itemize}
\item The member function \lstinline^become^ does not block, i.e., always
returns immediately. Thus, lambda expressions should \textit{always} capture
by value. Otherwise, all references on the stack will cause undefined
behavior if the lambda expression is executed.
\end{itemize}
\subsection{Requests}
\begin{itemize}
\item A handle returned by \lstinline^request^ represents \emph{exactly one}
response message. It is not possible to receive more than one response
message.
\item The handle returned by \lstinline^request^ is bound to the calling actor.
It is not possible to transfer a handle to a response to another actor.
\end{itemize}
\clearpage
\subsection{Sharing}
\begin{itemize}
\item It is strongly recommended to \textbf{not} share states between actors.
In particular, no actor shall ever access member variables or member
functions of another actor. Accessing shared memory segments concurrently
can cause undefined behavior that is incredibly hard to find and debug.
However, sharing \textit{data} between actors is fine, as long as the data
is \textit{immutable} and its lifetime is guaranteed to outlive all actors.
The simplest way to meet the lifetime guarantee is by storing the data in
smart pointers such as \lstinline^std::shared_ptr^. Nevertheless, the
recommended way of sharing informations is message passing. Sending the
same message to multiple actors does not result in copying the data several
times.
\end{itemize}
This diff is collapsed.
This diff is collapsed.
\section{Frequently Asked Questions}
\label{faq}
This Section is a compilation of the most common questions via GitHub, chat,
and mailing list.
\subsection{Can I Encrypt CAF Communication?}
Yes, by using the OpenSSL module~\see{free-remoting-functions}.
\subsection{Can I Create Messages Dynamically?}
Yes.
Usually, messages are created implicitly when sending messages but can also be
created explicitly using \lstinline^make_message^. In both cases, types and
number of elements are known at compile time. To allow for fully dynamic
message generation, CAF also offers \lstinline^message_builder^:
\begin{lstlisting}
message_builder mb;
// prefix message with some atom
mb.append(strings_atom::value);
// fill message with some strings
std::vector<std::string> strings{/*...*/};
for (auto& str : strings)
mb.append(str);
// create the message
message msg = mb.to_message();
\end{lstlisting}
\subsection{What Debugging Tools Exist?}
The \lstinline^scripts/^ and \lstinline^tools/^ directories contain some useful
tools to aid in development and debugging.
\lstinline^scripts/atom.py^ converts integer atom values back into strings.
\lstinline^scripts/demystify.py^ replaces cryptic \lstinline^typed_mpi<...>^
templates with \lstinline^replies_to<...>::with<...>^ and
\lstinline^atom_constant<...>^ with a human-readable representation of the
actual atom.
\lstinline^scripts/caf-prof^ is an R script that generates plots from CAF
profiler output.
\lstinline^caf-vec^ is a (highly) experimental tool that annotates CAF logs
with vector timestamps. It gives you happens-before relations and a nice
visualization via \href{https://bestchai.bitbucket.io/shiviz/}{ShiViz}.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
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