mirror of
https://github.com/FairRootGroup/FairMQ.git
synced 2025-10-13 00:31:14 +00:00
231 lines
16 KiB
HTML
231 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
<meta name="generator" content="Doxygen 1.8.13"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>FairMQ: Main Page</title>
|
||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="jquery.js"></script>
|
||
<script type="text/javascript" src="dynsections.js"></script>
|
||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
<script type="text/javascript" src="search/search.js"></script>
|
||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
</head>
|
||
<body>
|
||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
<div id="titlearea">
|
||
<table cellspacing="0" cellpadding="0">
|
||
<tbody>
|
||
<tr style="height: 56px;">
|
||
<td id="projectalign" style="padding-left: 0.5em;">
|
||
<div id="projectname">FairMQ
|
||
 <span id="projectnumber">1.2.1</span>
|
||
</div>
|
||
<div id="projectbrief">C++ Message Passing Framework</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.8.13 -->
|
||
<script type="text/javascript">
|
||
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
||
</script>
|
||
<script type="text/javascript" src="menudata.js"></script>
|
||
<script type="text/javascript" src="menu.js"></script>
|
||
<script type="text/javascript">
|
||
$(function() {
|
||
initMenu('',true,false,'search.php','Search');
|
||
$(document).ready(function() { init_search(); });
|
||
});
|
||
</script>
|
||
<div id="main-nav"></div>
|
||
</div><!-- top -->
|
||
<!-- window showing the filter options -->
|
||
<div id="MSearchSelectWindow"
|
||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
</div>
|
||
|
||
<!-- iframe showing the search results (closed by default) -->
|
||
<div id="MSearchResultsWindow">
|
||
<iframe src="javascript:void(0)" frameborder="0"
|
||
name="MSearchResults" id="MSearchResults">
|
||
</iframe>
|
||
</div>
|
||
|
||
<div class="header">
|
||
<div class="headertitle">
|
||
<div class="title">FairMQ Documentation</div> </div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><h1><a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a></h1>
|
||
<p>C++ Message passing framework</p>
|
||
<table class="doxtable">
|
||
<tr>
|
||
<th align="center">Branch </th><th align="left">Build Status </th></tr>
|
||
<tr>
|
||
<td align="center"><code>master</code> </td><td align="left"><div class="image">
|
||
<img src="https://alfa-ci.gsi.de/buildStatus/icon?job=FairRootGroup/FairMQ/master" alt="build status master branch"/>
|
||
</div>
|
||
</td></tr>
|
||
<tr>
|
||
<td align="center"><code>dev</code> </td><td align="left"><div class="image">
|
||
<img src="https://alfa-ci.gsi.de/buildStatus/icon?job=FairRootGroup/FairMQ/dev" alt="build status dev branch"/>
|
||
</div>
|
||
</td></tr>
|
||
</table>
|
||
<p><a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> is designed to help implementing large-scale data processing workflows needed in next-generation Particle Physics experiments. <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> is written in C++ and aims to</p><ul>
|
||
<li>provide <b>an asynchronous message passing abstraction</b> of different data transport technologies,</li>
|
||
<li>provide a reasonably <b>efficient data transport</b> service (zero-copy, high throughput),</li>
|
||
<li>be <b>data format agnostic</b>, and</li>
|
||
<li>provide <b>basic building blocks</b> that can be used to implement higher level data processing workflows.</li>
|
||
</ul>
|
||
<p>The core of <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> provides an abstract asynchronous message passing API with scalability protocols inspired by <a href="https://github.com/zeromq/libzmq">ZeroMQ</a> (e.g. PUSH/PULL, PUB/SUB). <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> provides multiple implementations for its API (so-called "transports", e.g. <code>zeromq</code>, <code>shmem</code>, <code>nanomsg</code>, and <code>ofi</code> (in development)) to cover a variety of use cases (e.g. inter-thread, inter-process, inter-node communication) and machines (e.g. Ethernet, Infiniband). In addition to this core functionality <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> provides a framework for creating "devices" - actors which are communicating through message passing. <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> does not only allow the user to use different transport but also to mix them; i.e: A Device can communicate using different transport on different channels at the same time. Device execution is modelled as a simple state machine that shapes the integration points for the user task. Devices also incorporate a plugin system for runtime configuration and control. Next to the provided devices and plugins (e.g. <a href="https://github.com/FairRootGroup/DDS">DDS</a>) the user can extened <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> by developing his own plugins to integrate his devices with external configuration and control services.</p>
|
||
<p><a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> has been developed in the context of its mother project <a href="https://github.com/FairRootGroup/FairRoot">FairRoot</a> - a simulation, reconstruction and analysis framework.</p>
|
||
<h2>Dependencies</h2>
|
||
<ul>
|
||
<li><a href="https://www.boost.org/"><b>Boost</b></a> (PUBLIC)</li>
|
||
<li><a href="https://github.com/FairRootGroup/FairLogger"><b>FairLogger</b></a> (PUBLIC)</li>
|
||
<li><a href="https://cmake.org/">CMake</a> (BUILD)</li>
|
||
<li><a href="https://github.com/google/googletest">GTest</a> (BUILD, optional, <code>tests</code>)</li>
|
||
<li><a href="http://www.doxygen.org/">Doxygen</a> (BUILD, optional, <code>docs</code>)</li>
|
||
<li><a href="http://zeromq.org/">ZeroMQ</a> (PRIVATE)</li>
|
||
<li><a href="https://msgpack.org/index.html">Msgpack</a> (PRIVATE, optional, <code>nanomsg_transport</code>)</li>
|
||
<li><a href="http://nanomsg.org/">nanomsg</a> (PRIVATE, optional, <code>nanomsg_transport</code>)</li>
|
||
<li><a href="https://ofiwg.github.io/libfabric/">OFI</a> (PRIVATE, optional, <code>ofi_transport</code>)</li>
|
||
<li><a href="https://developers.google.com/protocol-buffers/">Protobuf</a> (PRIVATE, optional, <code>ofi_transport</code>)</li>
|
||
<li><a href="http://dds.gsi.de">DDS</a> (PRIVATE, optional, <code>dds_plugin</code>)</li>
|
||
</ul>
|
||
<p>Supported platforms: Linux and MacOS.</p>
|
||
<h2>Releases</h2>
|
||
<table class="doxtable">
|
||
<tr>
|
||
<th>Stable release </th><th>Date </th><th>API Docs </th></tr>
|
||
<tr>
|
||
<td><a href="https://github.com/FairRootGroup/FairMQ/releases/tag/v1.2.1"><b>1.2.1</b></a> </td><td>May 2018 </td><td><a href="https://fairrootgroup.github.io/FairMQ/v1.2.1/index.html">link</a> </td></tr>
|
||
<tr>
|
||
<td><a href="https://github.com/FairRootGroup/FairMQ/releases/tag/v1.2.0"><b>1.2.0</b></a> </td><td>May 2018 </td><td><a href="https://fairrootgroup.github.io/FairMQ/v1.2.0/index.html">link</a> </td></tr>
|
||
</table>
|
||
<p>Find all <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> stable and development releases <a href="https://github.com/FairRootGroup/FairMQ/releases">here</a>.</p>
|
||
<h2>Installation from Source</h2>
|
||
<div class="fragment"><div class="line">git clone https://github.com/FairRootGroup/FairMQ fairmq</div><div class="line">mkdir fairmq_build && cd fairmq_build</div><div class="line">cmake -DCMAKE_INSTALL_PREFIX=./fairmq_install ../fairmq</div><div class="line">cmake --build . --target install</div></div><!-- fragment --><p>If dependencies are not installed in standard system directories, you can hint the installation location via <code>-DCMAKE_PREFIX_PATH=...</code> or per dependency via <code>-D{DEPENDENCY}_ROOT=...</code>. <code>{DEPENDENCY}</code> can be <code>GTEST</code>, <code>BOOST</code>, <code>FAIRLOGGER</code>, <code>ZEROMQ</code>, <code>MSGPACK</code>, <code>NANOMSG</code>, <code>OFI</code>, <code>PROTOBUF</code>, or <code>DDS</code> (<code>*_ROOT</code> variables can also be environment variables).</p>
|
||
<h2>Usage</h2>
|
||
<p><a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> ships as a CMake package, so in your <code>CMakeLists.txt</code> you can discover it like this:</p>
|
||
<div class="fragment"><div class="line">find_package(FairMQ)</div></div><!-- fragment --><p>If <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> is not installed in system directories, you can hint the installation:</p>
|
||
<div class="fragment"><div class="line">set(CMAKE_PREFIX_PATH /path/to/FairMQ_install_prefix ${CMAKE_PREFIX_PATH})</div><div class="line">find_package(FairMQ)</div></div><!-- fragment --><p><code>find_package(FairMQ)</code> will define an imported target <code>FairMQ::FairMQ</code> (An alias <code>FairRoot::FairMQ</code> is also defined (if you use CMake 3.11+) for backwards compatibility, but it is deprecated).</p>
|
||
<p>In order to succesfully compile and link against the <code>FairMQ::FairMQ</code> target, you need to discover its public package dependencies, too.</p>
|
||
<div class="fragment"><div class="line">find_package(FairMQ)</div><div class="line">find_package(FairLogger ${FairMQ_FairLogger_VERSION})</div><div class="line">find_package(Boost ${FairMQ_Boost_VERSION} COMPONENTS ${FairMQ_BOOST_COMPONENTS})</div></div><!-- fragment --><p>Of course, feel free to customize the above commands to your needs.</p>
|
||
<p>Optionally, you can require certain <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> package components and a minimum version:</p>
|
||
<div class="fragment"><div class="line">find_package(FairMQ 1.1.0 COMPONENTS nanomsg_transport dds_plugin)</div><div class="line">find_package(FairLogger ${FairMQ_FairLogger_VERSION})</div><div class="line">find_package(Boost ${FairMQ_Boost_VERSION} COMPONENTS ${FairMQ_BOOST_COMPONENTS})</div></div><!-- fragment --><p>When building <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a>, CMake will print a summary table of all available package components.</p>
|
||
<h2>CMake options</h2>
|
||
<p>On command line:</p>
|
||
<ul>
|
||
<li><code>-DDISABLE_COLOR=ON</code> disables coloured console output.</li>
|
||
<li><code>-DBUILD_TESTING=OFF</code> disables building of tests.</li>
|
||
<li><code>-DBUILD_EXAMPLES=OFF</code> disables building of examples.</li>
|
||
<li><code>-DBUILD_NANOMSG_TRANSPORT=ON</code> enables building of nanomsg transport.</li>
|
||
<li><code>-DBUILD_OFI_TRANSPORT=ON</code> enables building of the experimental OFI transport.</li>
|
||
<li><code>-DBUILD_DDS_PLUGIN=ON</code> enables building of the DDS plugin.</li>
|
||
<li><code>-DBUILD_DOCS=ON</code> enables building of API docs.</li>
|
||
<li>You can hint non-system installations for dependent packages, see the #Installation section above</li>
|
||
</ul>
|
||
<p>After the <code>find_package(FairMQ)</code> call the following CMake variables are defined:</p>
|
||
<table class="doxtable">
|
||
<tr>
|
||
<th>Variable </th><th>Info </th></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_PACKAGE_DEPENDENCIES}</code> </td><td>the list of public package dependencies </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_Boost_VERSION}</code> </td><td>the minimum Boost version <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> requires </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_Boost_COMPONENTS}</code> </td><td>the list of Boost components <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> depends on </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_FairLogger_VERSION}</code> </td><td>the minimum FairLogger version <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> requires </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_PACKAGE_COMPONENTS}</code> </td><td>the list of components <a class="el" href="namespaceFairMQ.html" title="TODO deprecate this namespace. ">FairMQ</a> consists of </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_::COMPONENT::_FOUND}</code> </td><td><code>TRUE</code> if this component was built </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_VERSION}</code> </td><td>the version in format <code>MAJOR.MINOR.PATCH</code> </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_GIT_VERSION}</code> </td><td>the version in the format returned by <code>git describe --tags --dirty --match "v*"</code> </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_ROOT}</code> </td><td>the actual installation prefix, notice the difference to the hint variable <code>FAIRMQ_ROOT</code> </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_BINDIR}</code> </td><td>the installation bin directory </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_INCDIR}</code> </td><td>the installation include directory </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_LIBDIR}</code> </td><td>the installation lib directory </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_DATADIR}</code> </td><td>the installation data directory (<code>../share/fairmq</code>) </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_CMAKEMODDIR}</code> </td><td>the installation directory of shipped CMake find modules </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_CXX_STANDARD_REQUIRED}</code> </td><td>the value of <code>CMAKE_CXX_STANDARD_REQUIRED</code> at built-time </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_CXX_STANDARD}</code> </td><td>the value of <code>CMAKE_CXX_STANDARD</code> at built-time </td></tr>
|
||
<tr>
|
||
<td><code>${FairMQ_CXX_EXTENSIONS}</code> </td><td>the values of <code>CMAKE_CXX_EXTENSIONS</code> at built-time </td></tr>
|
||
</table>
|
||
<h2>Documentation</h2>
|
||
<ol type="1">
|
||
<li><a href="docs/Device.md#1-device">Device</a><ol type="a">
|
||
<li><a href="docs/Device.md#11-topology">Topology</a></li>
|
||
<li><a href="docs/Device.md#12-communication-patterns">Communication Patterns</a></li>
|
||
<li><a href="docs/Device.md#13-state-machine">State Machine</a></li>
|
||
<li><a href="docs/Device.md#15-multiple-devices-in-the-same-process">Multiple devices in the same process</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Transport.md#2-transport-interface">Transport Interface</a><ol type="a">
|
||
<li><a href="docs/Transport.md#21-message">Message</a><ol type="i">
|
||
<li><a href="docs/Transport.md#211-ownership">Ownership</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Transport.md#22-channel">Channel</a></li>
|
||
<li><a href="docs/Transport.md#23-poller">Poller</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Configuration.md#3-configuration">Configuration</a><ol type="a">
|
||
<li><a href="docs/Configuration.md#31-device-configuration">Device Configuration</a></li>
|
||
<li><a href="docs/Configuration.md#32-communication-channels-configuration">Communication Channels Configuration</a><ol type="i">
|
||
<li><a href="docs/Configuration.md#321-json-parser">JSON Parser</a></li>
|
||
<li><a href="docs/Configuration.md#322-suboptparser">SuboptParser</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Configuration.md#33-introspection">Introspection</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Development.md#4-development">Development</a><ol type="a">
|
||
<li><a href="docs/Development.md#41-testing">Testing</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Logging.md#5-logging">Logging</a><ol type="a">
|
||
<li><a href="docs/Logging.md#51-log-severity">Log severity</a></li>
|
||
<li><a href="docs/Logging.md#52-log-verbosity">Log verbosity</a></li>
|
||
<li><a href="docs/Logging.md#53-color">Color for console output</a></li>
|
||
<li><a href="docs/Logging.md#54-file-output">File output</a></li>
|
||
<li><a href="docs/Logging.md#55-custom-sinks">Custom sinks</a></li>
|
||
</ol>
|
||
</li>
|
||
<li><a href="docs/Examples.md#6-examples">Examples</a></li>
|
||
</ol>
|
||
<h2>License</h2>
|
||
<p>GNU Lesser General Public Licence (LGPL) version 3, see [LICENSE](LICENSE).</p>
|
||
<p>Copyright (C) 2013-2018 GSI Helmholtzzentrum fuer Schwerionenforschung GmbH </p>
|
||
</div></div><!-- contents -->
|
||
<!-- start footer part -->
|
||
<hr class="footer"/><address class="footer"><small>
|
||
Generated by  <a href="http://www.doxygen.org/index.html">
|
||
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
||
</a> 1.8.13
|
||
</small></address>
|
||
</body>
|
||
</html>
|