Commit 7c1ea7d4 authored by Axel Auweter's avatar Axel Auweter
Browse files

Some initial attempt to document the DCDBLib source code with Doxygen. WIP.

parent d483370b
This diff is collapsed.
......@@ -84,13 +84,22 @@ cassandra/Cassandra.h:
@cat cassandra/cassandra_constants.h_newline | tr $$ '\n' > cassandra/cassandra_constants.h
@rm cassandra/cassandra_constants.h_newline
# Build the documentation
docs:
@echo "Creating documentation..."
doxygen
# Clean everything
clean: clean-cassandra-headers
clean: clean-cassandra-headers clean-docs
rm -f $(OBJS) $(TARGET)
# Clean the Cassandra headers only
clean-cassandra-headers:
rm -rf cassandra
# Clean the documentation
clean-docs:
rm -rf docs
# Install to deploy path
install: $(TARGET) check-thrift-env
......
......@@ -5,14 +5,37 @@
* Author: Axel Auweter
*/
/**
* @file
* @brief This file contains the public API for the DCDBLib library.
* It contains the class definition of the library's main class
* SensorDataStore as well as the helper struct typedefs SensorId,
* DeviceLocation, and DeviceSensorId.
*/
#include <stdint.h>
#include <string>
#ifndef SENSORDATASTORE_H_
#define SENSORDATASTORE_H_
/* Ensure that the unions and structs are created without padding */
#pragma pack(push,1)
/**
* @brief The DeviceLocation type describes the location of a sensor.
* In the current implementation, DeviceLocation consists of 64 bits
* which can either be accessed trough the raw member or through the
* DEEP project specific members:
* - datacenter_id
* - cluster_id
* - rack_id_msb
* - rack_id_lsb
* - chassis_id
* - bic_id
* - bnc_id
* - knc_id
*/
typedef union {
uint64_t raw;
struct {
......@@ -27,11 +50,32 @@ typedef union {
};
} DeviceLocation;
/**
* @brief The DeviceSensorId type describes the tuple of the sensor
* number and a unique (location-independent) device id.
* In combination with a location specified by the DeviceLocation type,
* the sensor_number defines a sensor by location.
*
* The device_id member is - in return - used to uniquely identify
* certain components, even when their location changes. A suitable
* approach is, for example, to use MAC addresses as the device_id.
*/
typedef struct {
uint64_t sensor_id : 16;
uint64_t device_id : 48;
uint64_t sensor_number : 16;
uint64_t device_id : 48;
} DeviceSensorId;
/**
* @brief The SensorId type packs the DeviceLocation and DeviceSensorId
* types into a single object.
* In DCDB, a sensor is described by it's location, a sensor number at
* this location, and a unique part number identifier. This information
* is packed into a 128 bit wide bitfield.
*
* Access to this bitfield can be done through the raw member of through
* the two variables dl and dsid of the helper types DeviceLocation and
* DeviceSensorId.
*/
typedef union {
uint64_t raw[2];
struct {
......@@ -46,8 +90,8 @@ typedef union {
class SensorDataStoreImpl;
class CassandraBackend;
/*
* SensorDataStore
/**
* @brief SensorDataStore is the "main" class of the DCDBLib library.
*
* Use this class to initialize, write, and read sensor data.
*/
......@@ -58,12 +102,50 @@ private:
CassandraBackend* csBackend;
public:
/**
* @brief This function initializes the SensorDataStore object,
* sets the connection parameters and established a
* connection to the database.
* @param hostname The hostname or IP address of the database node to connect to.
* @param port The port on which the database node is listening.
*/
void init(std::string hostname, int port);
/**
* @brief This function populates a preallocated SensorId object
* from a MQTT topic string.
* @param sid A pre-allocated SensorId object.
* @param topic The string from which the SensorId object will be populated.
* @return Returns true if the topic string was valid and the SensorId object was populated.
*/
bool topicToSid(SensorId* sid, std::string topic);
/**
* @brief This function inserts a single sensor reading into
* the database.
* @param sid A SensorId object (typically the result of calling topicToSid()).
* @param ts The timestamp of the sensor reading.
* @param value The value of the sensor reading.
*/
void insert(SensorId* sid, uint64_t ts, uint64_t value);
/**
* @brief A shortcut constructor for a SensorDataStore object
* that automatically initializes with default parameters
* for hostname and port.
*/
SensorDataStore();
/**
* @brief The standard constructor for a SensorDataStore object.
* @param hostname A string containing the hostname or IP address of the database server.
* @param port A integer containing the port number on which the database server is listening.
*/
SensorDataStore(std::string hostname, int port);
/**
* @brief The standard destructor for a SensorDatStore object.
*/
virtual ~SensorDataStore();
};
......
......@@ -5,6 +5,30 @@
* Author: Axel Auweter
*/
/**
* @mainpage
* The DCDBLib library is a dynamic runtime library providing
* functions to initialize and access the DCDB data store. It
* is being used by the CollectAgent to handle insertion of
* data and can be used by tools responsible for data analysis.
*
* Its main class is the SensorDataStore class which provides
* functions to connect to the data store, initialize an empty
* data base and to (TODO) retrieve data.
*
* For its internal handling, SensorDataStore relies on the
* SensorDataStoreImpl class (which hides all private member
* functions belonging to the SensorDataStore class from the
* header that is used by programmers who link against this
* library). Raw database functionality is abstracted into the
* CassandraBackend class (to easy switching to other
* key-value style databases in the future).
*
* To use the library in your client application, simnply
* include the sensordatastore.h header file and initialize
* an object of the SensorDataStore class.
*/
#include "sensordatastore_internal.h"
string SensorDataStoreImpl::sidConvert(SensorId *sid)
......@@ -96,6 +120,13 @@ SensorDataStoreImpl::~SensorDataStoreImpl()
{
}
/**
* @details
* The main task of this function is to ensure that the
* SensorDataStore object owns an instance of SensorDataStoreImpl.
* Once this is ensured, the actual initialization work is
* performed by the init function of SensorDataStoreImpl.
*/
void SensorDataStore::init(string hostname, int port)
{
/* Allocate new SensorDataStoreImpl Object if necessary */
......@@ -103,20 +134,38 @@ void SensorDataStore::init(string hostname, int port)
impl = new SensorDataStoreImpl(csBackend);
}
/* Call the Imlp class init function */
/* Call the Impl class init function */
impl->init(hostname, port);
}
/**
* @details
* Instead of doing the actual work, this function simply
* forwards to the insert function of the SensorDataStoreImpl
* class.
*/
bool SensorDataStore::topicToSid(SensorId* sid, std::string topic)
{
return impl->topicToSid(sid, topic);
}
/**
* @details
* Instead of doing the actual work, this function simply
* forwards to the insert function of the SensorDataStoreImpl
* class.
*/
void SensorDataStore::insert(SensorId* sid, uint64_t ts, uint64_t value)
{
impl->insert(sid, ts, value);
}
/**
* @details
* This constructor for SensorDataStore acts similarly to the
* standard constructor by calling the standard constructor
* with "localhost" as the hostname and 9160 as the port number.
*/
SensorDataStore::SensorDataStore()
{
csBackend = new CassandraBackend();
......@@ -124,13 +173,28 @@ SensorDataStore::SensorDataStore()
init("localhost", 9160);
}
SensorDataStore::SensorDataStore(string hostname, int port)
/**
* @details
* This constructor for SensorDataStore objects initializes
* the object and connects to the database at the given
* hostname on the given port.
*
* For this, the constructor allocates a CassandraBackend
* object that is then used by SensorDataStoreImpl for doing
* the raw database accesses.
*/
SensorDataStore::SensorDataStore(std::string hostname, int port)
{
csBackend = new CassandraBackend();
impl = nullptr;
init(hostname, port);
}
/**
* @details
* The SensorDataStore desctructor deallocates the
* SensorDataStoreImpl and CassandraBackend objects.
*/
SensorDataStore::~SensorDataStore()
{
/* Clean up... */
......
Supports Markdown
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