Mirror/FairMQ
1
0
Fork 0
mirror of https://github.com/FairRootGroup/FairMQ.git synced 2025-10-13 08:41:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
eb43855b10
FairMQ/v1.2.3/index.html
Dennis Klein d1e25efd23
Add API docs for 1.2.3
2018-05-22 16:56:41 +02:00

233 lines
15 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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
&#160;<span id="projectnumber">1.2.3</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>FairMQ</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>FairMQ is designed to help implementing large-scale data processing workflows needed in next-generation Particle Physics experiments. FairMQ 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 FairMQ 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). FairMQ 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 FairMQ provides a framework for creating "devices" - actors which are communicating through message passing. FairMQ 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 extend FairMQ by developing his own plugins to integrate his devices with external configuration and control services.</p>
<p>FairMQ 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.3"><b>1.2.3</b></a> </td><td>May 2018 </td><td><a href="https://fairrootgroup.github.io/FairMQ/v1.2.3/index.html">link</a> </td></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 FairMQ 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 &amp;&amp; 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>FairMQ 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 FairMQ 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>.</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">if(FairMQ_FOUND)</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 class="line">endif()</div></div><!-- fragment --><p>Of course, feel free to customize the above commands to your needs.</p>
<p>Optionally, you can require certain FairMQ 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">if(FairMQ_FOUND)</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 class="line">endif()</div></div><!-- fragment --><p>When building FairMQ, 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 FairMQ requires </td></tr>
<tr>
<td><code>${FairMQ_Boost_COMPONENTS}</code> </td><td>the list of Boost components FairMQ depends on </td></tr>
<tr>
<td><code>${FairMQ_FairLogger_VERSION}</code> </td><td>the minimum FairLogger version FairMQ requires </td></tr>
<tr>
<td><code>${FairMQ_PACKAGE_COMPONENTS}</code> </td><td>the list of components FairMQ 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 &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink