Commit 0016f8b5 authored by Micha Müller's avatar Micha Müller

Improve documentation: sort sources into doxygen modules

parent 14d632a5
......@@ -24,6 +24,12 @@
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//================================================================================
/**
* @defgroup analytics Analytics Framework
*
* @brief Framework for data analytics at various points within DCDB.
*/
#ifndef PROJECT_ANALYTICSMANAGER_H
#define PROJECT_ANALYTICSMANAGER_H
......@@ -44,7 +50,11 @@
using namespace std;
// Struct of values required to load analyzer dynamic libraries.
/**
* Struct of values required to load analyzer dynamic libraries.
*
* @ingroup analytics
*/
typedef struct {
std::string id;
void* DL;
......@@ -56,9 +66,12 @@ typedef struct {
typedef std::vector<an_dl_t> an_pluginVector_t;
/**
* Management class for the entire data analytics framework
* @brief Management class for the entire data analytics framework
*
* @details Allows to load, configure, start and generally manage plugins
* developed with the data analytics framework.
*
* Allows to load, configure, start and generally manage plugins developed with the data analytics framework.
* @ingroup analytics
*/
class AnalyticsManager {
......
......@@ -32,6 +32,11 @@
#include <math.h>
#include <algorithm>
/**
* @brief Aggregator analyzer plugin.
*
* @ingroup aggregator
*/
class AggregatorAnalyzer : virtual public AnalyzerTemplate<AggregatorSensorBase> {
public:
......
......@@ -30,6 +30,11 @@
#include "../../includes/AnalyzerConfiguratorTemplate.h"
#include "AggregatorAnalyzer.h"
/**
* @brief Configurator for the aggregator plugin.
*
* @ingroup aggregator
*/
class AggregatorConfigurator : virtual public AnalyzerConfiguratorTemplate<AggregatorAnalyzer, AggregatorSensorBase> {
public:
......
......@@ -24,11 +24,23 @@
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//================================================================================
/**
* @defgroup aggregator Aggregator analyzer plugin.
* @ingroup analyzer
*
* @brief Aggregator analyzer plugin.
*/
#ifndef PROJECT_AGGREGATORSENSORBASE_H
#define PROJECT_AGGREGATORSENSORBASE_H
#include "sensorbase.h"
/**
* @brief Sensor base for aggregator plugin
*
* @ingroup aggregator
*/
class AggregatorSensorBase : public SensorBase {
public:
......
......@@ -30,6 +30,11 @@
#include "AggregatorAnalyzer.h"
#include "../../includes/JobAnalyzerTemplate.h"
/**
* @brief Aggregator for job data.
*
* @ingroup aggregator
*/
class JobAggregatorAnalyzer : public AggregatorAnalyzer, public JobAnalyzerTemplate<AggregatorSensorBase> {
public:
......
......@@ -30,6 +30,11 @@
#include "JobAggregatorAnalyzer.h"
#include "../../includes/JobAnalyzerConfiguratorTemplate.h"
/**
* @brief Configurator for job aggregator plugin.
*
* @ingroup aggregator
*/
class JobAggregatorConfigurator : public JobAnalyzerConfiguratorTemplate<JobAggregatorAnalyzer, AggregatorSensorBase> {
public:
......
......@@ -35,11 +35,14 @@
#include "globalconfiguration.h"
/**
* Interface to configurators for data analyzer plugins
* @brief Interface to configurators for data analyzer plugins
*
* This interface is the one exposed outside of the .dll library containing a plugin. Classes implementing this
* interface must perform configuration and instantiation of Analyzers objects, which are made accessible externally.
* @details This interface is the one exposed outside of the .dll library
* containing a plugin. Classes implementing this interface must
* perform configuration and instantiation of Analyzers objects, which
* are made accessible externally.
*
* @ingroup analyzer
*/
class AnalyzerConfiguratorInterface {
......
......@@ -45,10 +45,12 @@
#define CFG_VAL boost::property_tree::iptree&
/**
* Template that implements a standard AnalyzerConfiguratorInterface.
* @brief Template that implements a standard AnalyzerConfiguratorInterface.
*
* Users should employ this template whenever possible, and create their own configurators only when strictly
* necessary.
* @details Users should employ this template whenever possible, and create
* their own configurators only when strictly necessary.
*
* @ingroup analyzer
*/
template <class Analyzer, class SBase = SensorBase>
class AnalyzerConfiguratorTemplate : public AnalyzerConfiguratorInterface {
......
......@@ -24,6 +24,12 @@
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//================================================================================
/**
* @defgroup analyzer Analyzer Plugins
* @ingroup analytics
*
* @brief Analyzer for the analytics plugin.
*/
#ifndef PROJECT_ANALYZERINTERFACE_H
#define PROJECT_ANALYZERINTERFACE_H
......@@ -46,14 +52,19 @@ typedef struct {
} restResponse_t;
/**
* Interface to data analyzers
* @brief Interface to data analyzers
*
* @details This interface supplies methods to instantiate, start and retrieve
* data from analyzers, which are "modules" that* implement data
* analytics models and are loaded by DCDB data analytics plugins. For
* it to be used in the DCDB data analytics framework, the analyzer
* must comply to this interface.
*
* This interface supplies methods to instantiate, start and retrieve data from analyzers, which are "modules" that
* implement data analytics models and are loaded by DCDB data analytics plugins. For it to be used in the DCDB
* data analytics framework, the analyzer must comply to this interface.
* An analyzer acts on "units", which are logical entities represented
* by certain inputs and outputs. An unit can be, for example, a node,
* a CPU or a rack in a HPC system.
*
* An analyzer acts on "units", which are logical entities represented by certain inputs and outputs. An unit can be,
* for example, a node, a CPU or a rack in a HPC system.
* @ingroup analyzer
*/
class AnalyzerInterface {
public:
......
......@@ -40,11 +40,15 @@
using namespace std;
/**
* Template that implements features needed by Analyzers and complying to AnalyzerInterface.
* @brief Template that implements features needed by Analyzers and complying
* to AnalyzerInterface.
*
* The template accepts any class derived from SensorBase, allowing users to add their own attributes to input and output
* sensors. This template also employs UnitTemplates, which are instantiated according to the input sensor type.
* @details The template accepts any class derived from SensorBase, allowing
* users to add their own attributes to input and output sensors. This
* template also employs UnitTemplates, which are instantiated
* according to the input sensor type.
*
* @ingroup analyzer
*/
template <typename S>
class AnalyzerTemplate : public AnalyzerInterface {
......
......@@ -31,10 +31,13 @@
#include "JobAnalyzerTemplate.h"
/**
* Template that implements a configurator for Job analyzer plugins.
* @brief Template that implements a configurator for Job analyzer plugins.
*
* This template expands the standard AnalyzerConfiguratorTemplate, with very few changes to accomodate the different
* design of job analyzers.
* @details This template expands the standard AnalyzerConfiguratorTemplate,
* with very few changes to accomodate the different design of job
* analyzers.
*
* @ingroup analyzer
*/
template <class Analyzer, class SBase = SensorBase>
class JobAnalyzerConfiguratorTemplate : virtual public AnalyzerConfiguratorTemplate<Analyzer, SBase> {
......
......@@ -30,10 +30,13 @@
#include "AnalyzerTemplate.h"
/**
* Template that implements features needed by Job Analyzers and complying to AnalyzerInterface.
* @brief Template that implements features needed by Job Analyzers and
* complying to AnalyzerInterface.
*
* This template is derived from AnalyzerTemplate, and is adjusted to simplify job-related computations.
* @details This template is derived from AnalyzerTemplate, and is adjusted to
* simplify job-related computations.
*
* @ingroup analyzer
*/
template <typename S>
class JobAnalyzerTemplate : virtual public AnalyzerTemplate<S> {
......
......@@ -47,11 +47,14 @@ typedef vector<reading_t>* (*QueryEngineCallback)(const string&, const uint64_t,
typedef vector<qeJobData>* (*QueryEngineJobCallback)(const uint32_t, const uint64_t, const uint64_t, vector<qeJobData>*, const bool, const bool);
/**
* Class that grants query access to local and remote sensors
* @brief Class that grants query access to local and remote sensors
*
* This class provides an abstraction layer to where the data analytics framework is executed: access interface to
* sensor data is the same on dcdbpusher and collectagent.
* This class is implemented according to the Singleton design pattern.
* @details This class provides an abstraction layer to where the data analytics
* framework is executed: access interface to sensor data is the same
* on dcdbpusher and collectagent.
* This class is implemented according to the Singleton design pattern.
*
* @ingroup analytics
*/
class QueryEngine {
......
......@@ -37,11 +37,13 @@
using namespace std;
/**
* Helper template to generate Analyzer Units
* @brief Helper template to generate Analyzer Units
*
* This template decouples the unit-related configuration logic from AnalyerConfiguratorTemplate, so that users can
* override such template without losing access to the unit system.
* @details This template decouples the unit-related configuration logic from
* AnalyerConfiguratorTemplate, so that users can override such
* template without losing access to the unit system.
*
* @ingroup analyzer
*/
template <class SBase=SensorBase>
class UnitGenerator {
......
......@@ -34,9 +34,12 @@
typedef enum inputMode_t { SELECTIVE = 1, ALL = 2, ALL_RECURSIVE = 3 } inputMode_t;
/**
* Interface for Units used by Analyzers to perform data analytics.
* @brief Interface for Units used by Analyzers to perform data analytics.
*
* An Unit represents a logical entity on which an Analyzer operates, and is identified by its name, inputs and outputs.
* @details An Unit represents a logical entity on which an Analyzer operates,
* and is identified by its name, inputs and outputs.
*
* @ingroup analyzer
*/
class UnitInterface {
......
......@@ -30,11 +30,14 @@
#include "UnitInterface.h"
/**
* Template that implements features needed to use Units in Analyzers.
* @brief Template that implements features needed to use Units in Analyzers.
*
* The template accepts any class derived from SensorBase, allowing users to add their own attributes to input and output
* sensors. Users should employ this template in their plugins if possible, and change it only if absolutely necessary.
* @details The template accepts any class derived from SensorBase, allowing
* users to add their own attributes to input and output sensors. Users
* should employ this template in their plugins if possible, and change
* it only if absolutely necessary.
*
* @ingroup analyzer
*/
template <class S=SensorBase>
class UnitTemplate : public UnitInterface {
......
......@@ -32,6 +32,11 @@
#include "analyticscontroller.h"
#include "mqttchecker.h"
/**
* @brief Class providing a RESTful API to collect agent via network (HTTPs only).
*
* @ingroup ca
*/
class CARestAPI : public RESTHttpsServer {
public:
CARestAPI(serverSettings_t settings,
......
......@@ -42,12 +42,16 @@
using namespace std;
/**
* Class implementing a wrapper around the AnalyticsManager
* @brief Class implementing a wrapper around the AnalyticsManager
*
* This class provides a wrapper around many features required for the instantiation of the Analytics Manager - namely
* the instantiation of a SensorNavigator, the creation of a dedicated thread pool, and the insertion of generated
* sensor values into the Cassandra datastore. Most of these features were already available in DCDBPusher to handle
* regular sensors, but they had to be ported over to the CollectAgent.
* @details This class provides a wrapper around many features required for the
* instantiation of the Analytics Manager - namely the instantiation of
* a SensorNavigator, the creation of a dedicated thread pool, and the
* insertion of generated sensor values into the Cassandra datastore.
* Most of these features were already available in DCDBPusher to handle
* regular sensors, but they had to be ported over to the CollectAgent.
*
* @ingroup ca
*/
class AnalyticsController {
......
......@@ -24,6 +24,25 @@
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//================================================================================
/**
* @defgroup ca Collect Agent
*
* @brief MQTT message broker in between pusher and storage backend.
*
* @details Collect Agent is a intermediary between one or multiple Pusher
* instances and one storage backend. It runs a reduced custom MQTT
* message server. Collect Agent receives data from Pusher
* via MQTT messages and stores them in the storage via libdcdb.
*/
/**
* @file collectagent.cpp
*
* @brief Main function for the DCDB Collect Agent.
*
* @ingroup ca
*/
#include <cstdlib>
#include <signal.h>
#include <unistd.h>
......
......@@ -42,7 +42,11 @@
using namespace std;
// Wrapper class for Cassandra-specific settings
/**
* Wrapper class for Cassandra-specific settings
*
* @ingroup ca
*/
class cassandra_t {
public:
cassandra_t() {}
......@@ -58,7 +62,9 @@ public:
};
/**
* Class responsible of reading the collectagent global configuration.
* @brief Class responsible for reading collect agent specific configuration.
*
* @ingroup ca
*/
class Configuration : public GlobalConfiguration {
......
......@@ -36,6 +36,11 @@ using namespace DCDB;
typedef std::map<SensorId, CacheEntry> sensorCache_t;
/**
* @brief
*
* @ingroup ca
*/
class SensorCache {
public:
SensorCache(uint64_t maxHistory=60000000000);
......@@ -90,7 +95,7 @@ public:
/**
* @brief Removes all obsolete entries from the cache
*
* All entries in the cache whose latest sensor reading is older than "now" - t nanoseconds are
* @details entries in the cache whose latest sensor reading is older than "now" - t nanoseconds are
* removed.
*
* @param t The threshold in nanoseconds for entries that must be removed
......
......@@ -24,6 +24,13 @@
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//================================================================================
/**
* @defgroup mqttserver Simple MQTT server
* @ingroup ca
*
* @brief Simplified custom MQTT message server.
*/
#include <stdint.h>
#include <pthread.h>
#include <sys/types.h>
......@@ -49,12 +56,19 @@
//#define SimpleMQTTVerbose 100
/**
* Define the MQTT connection queue length
*
* @ingroup mqttserver
*/
#ifndef SimpleMQTTConnectionsQueueLength
#define SimpleMQTTConnectionsQueueLength 4
#endif
/*
* Define the maximum backlog size for listen().
*
* @ingroup mqttserver
*/
#ifndef SimpleMQTTBacklog
#define SimpleMQTTMaxBacklog 100
......@@ -62,6 +76,8 @@
/*
* Define the standard wait time for poll() calls.
*
* @ingroup mqttserver
*/
#ifndef SimpleMQTTPollTimeout
#define SimpleMQTTPollTimeout 100
......@@ -69,6 +85,8 @@
/*
* Define the standard size for the buffer used in read() calls.
*
* @ingroup mqttserver
*/
#ifndef SimpleMQTTReadBufferSize
#define SimpleMQTTReadBufferSize 1024
......@@ -76,6 +94,7 @@
/*
* Enable verbose output of the MQTT server.
*
*/
//#define SimpleMQTTVerbose
......@@ -83,11 +102,11 @@
typedef int (*SimpleMQTTMessageCallback)(SimpleMQTTMessage*);
#include "simplemqttserverthread.h"
/*
* SimpleMQTTServer Class Definition
*
* Usage:
/**
* @brief %SimpleMQTTServer Class Definition
*
* @details Usage:
* @code
* // Create a simple MQTT server instance listening on localhost, port 1883 (default):
* SimpleMQTTServer s();
*
......@@ -96,7 +115,9 @@ typedef int (*SimpleMQTTMessageCallback)(SimpleMQTTMessage*);
*
* s.start(); // Start server
* s.stop(); // Stop server
* @endcode
*
* @ingroup mqttserver
*/
class SimpleMQTTServer
{
......
......@@ -24,6 +24,13 @@
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//================================================================================
/**
* @file simplemqttservermessage.h
*
* @brief Class for receiving a simple MQTT message.
*
* @ingroup mqttserver
*/
#ifndef SIMPLEMQTTMESSAGE_H_
#define SIMPLEMQTTMESSAGE_H_
......
......@@ -30,6 +30,11 @@
#include "logging.h"
#include <vector>
/**
* @brief Simple MQTT server thread.
*
* @ingroup mqttserver
*/
class SimpleMQTTServerThread
{
protected:
......@@ -50,6 +55,11 @@ public:
~SimpleMQTTServerThread();
};
/**
* @brief Simple MQTT server message thread.
*
* @ingroup mqttserver
*/
class SimpleMQTTServerMessageThread : SimpleMQTTServerThread
{
protected:
......@@ -77,6 +87,11 @@ public:
~SimpleMQTTServerMessageThread();
};
/**
* @brief Simple MQTT server accept thread.
*
* @ingroup mqttserver
*/
class SimpleMQTTServerAcceptThread : SimpleMQTTServerThread
{
protected:
......
......@@ -25,50 +25,14 @@
//================================================================================
/**
* General RESTful API https server leveraging Boost::Beast to provide common
* functionality for different REST API servers. Intended as parent class for
* concrete REST API implementations.
*
* Code partially copied from the boost beast synchronous https server example:
* https://www.boost.org/doc/libs/develop/libs/beast/example/http/server/sync-ssl/http_server_sync_ssl.cpp
*/
/**
* Example/Howto set up an endpoint in a derived class:
*
* 1. Implement a handler function that obeys the required handler signature:
* <code>
* void handle_get_example(http::response<http::string_body>& res, \
* queries_t& queries) {
* //Implement here the logic for the endpoint taking into account the
* //queries as required.
* //TODO
* std::string result;
* if(queries.at("number") == "true") {
* result = "a number string\n";
* } else {
* result = "a string string\n";
* }
* //Set the response accordingly at the end. Result must have string
* //format!
* res.body() = res;
* res.result(http::status::ok);
* }
* </code>
*
* 2. Add a new endpoint by specifying its path, supported REST method and
* corresponding handler function:
* <code>
* addEndpoint("/endpoints/example", {http::verb::get, \
* std::bind(handle_get_example, \
* std::placeholders::_1, \
* std::placeholders::_2)});
* </code>
* @defgroup server Https Server
* @ingroup common
*
* 3. Document your endpoints (expected queries etc.) somewhere.
*
* 4. Enjoy.
* @brief Definitions for a common HttpsServer base class.
*/
#ifndef COMMON_INCLUDE_RESTHTTPSSERVER_H_
#define COMMON_INCLUDE_RESTHTTPSSERVER_H_
......@@ -91,7 +55,9 @@
/******************************************************************************/
/**
* Enum to distinguish different permissions
* @brief Enum to distinguish different permissions
*
* @ingroup server
*/
enum permission {
GET = 0, /**< Permission to make GET requests */
......@@ -105,6 +71,9 @@ namespace http = boost::beast::http;
namespace ssl = boost::asio::ssl;
using tcp = boost::asio::ip::tcp;
/**
* TODO how to document using directives to get them recognized by doxygen?
*/
using userAttributes_t = std::pair<std::string, std::bitset<NUM_PERMISSIONS>>;
using userBase_t = std::unordered_map<std::string, userAttributes_t>;
......@@ -115,6 +84,8 @@ using apiEndpoint_t = std::pair<http::verb, apiEndpointHandler_t>;
using apiEndpoints_t = std::unordered_map<std::string, apiEndpoint_t>;
/**
* @ingroup server
*
* @brief Utility method for RestAPI implementations: retrieve the value
* for a key from queries.
*
......@@ -134,6 +105,8 @@ inline std::string getQuery(const std::string& key, queries_t& queries) {
}
/**
* @ingroup server
*
* @brief Utility method for RestAPI implementations: test if a plugin query
* was given. Prepares the response accordingly to continue execution on
* success or immediately return on failure.
......@@ -157,6 +130,47 @@ inline bool hasPlugin(const std::string& plugin, http::response<http::string_bod