Commit 586fac7a authored by Axel Auweter's avatar Axel Auweter
Browse files

Add license to DCDBLib and add some doxygen documentation.

parent c36102bf
/*
* c_api.h
*
* Created on: May 27, 2015
* Author: Axel Auweter
*/
//================================================================================
// Name : c_api.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C Application Programming Interface for DCDBLib
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
/**
* @file
......@@ -21,20 +40,48 @@
extern "C" {
#endif
/**
* Enum type for representing the outcome of a DCDB C API operation.
*/
typedef enum {
DCDB_C_OK,
DCDB_C_CONNERR,
DCDB_C_SENSORNOTFOUND,
DCDB_C_EMPTYSET,
DCDB_C_NOTINTEGRABLE,
DCDB_C_NOSENSOR,
DCDB_C_UNKNOWN
DCDB_C_OK, /**< Everything went fine. */
DCDB_C_CONNERR, /**< The connection to the database could not be made. */
DCDB_C_SENSORNOTFOUND, /**< The requested sensor cannot be found in the database's list of public sensors. */
DCDB_C_EMPTYSET, /**< The query into the database resulted in an empty set. */
DCDB_C_NOTINTEGRABLE, /**< One of the QuerySum() functions was called on a sensor that is not marked as integrable. */
DCDB_C_NOSENSOR, /**< The caller did not specify a sensor to be queried. */
DCDB_C_UNKNOWN /**< An unknown error occured. */
} DCDB_C_RESULT;
/**
* Type for passing various options to C API operations (bitmask style).
*
* So far, only the DCDB_C_LOCALTIME option exists.
*/
typedef uint32_t DCDB_C_OPTIONS;
#define DCDB_C_LOCALTIME 0x1 /**< Treat time stamps passed to the query as being in local time instead of UTC */
#define DCDB_C_LOCALTIME 0x1
/**
* @brief This function integrates a given senor's data series over time.
*
* @param result Pointer to a int64_t variable which will hold the result of the operation.
* @param hostname Hostname of a database node.
* @param port TCP port to use for connecting to the database node (for Cassandra, this is usually 9042).
* @param sensorPublicName Public name of the sensor whose values should be integrated.
* @param start time_t denoting the start of the time series.
* @param end time_t denoting the end of the timer series.
* @param options Bitmask of DCDB_C_OPTIONS.
*
* @details
* When calling this function, DCDBLib integrates the values of the given
* sensor over time (in seconds). For example, if you have a sensor which
* stores power data in Watts, the resulting value will be energy in Joules
* (Watts * seconds).
*
* If you intend to sum up the results of multiple sensors, consider the
* use of the dcdbQuerySumMultiple() or dcdbQuerySumMultipleThreaded()
* functions.
*/
DCDB_C_RESULT dcdbQuerySum(
int64_t* result,
const char* hostname,
......@@ -45,6 +92,24 @@ DCDB_C_RESULT dcdbQuerySum(
DCDB_C_OPTIONS options
);
/**
* @brief This function integrates multiple data series over time.
*
* @param result Pointer to a int64_t variable which will hold the result of the operation.
* @param hostname Hostname of a database node.
* @param port TCP port to use for connecting to the database node (for Cassandra, this is usually 9042).
* @param sensorPublicName Array of public names of the sensors whose values should be integrated.
* @param sensorPublicNameLength Number of sensors within sensorPublicName.
* @param start time_t denoting the start of the time series.
* @param end time_t denoting the end of the timer series.
* @param options Bitmask of DCDB_C_OPTIONS.
*
* @details
* When calling this function, DCDBLib integrates the values of the given
* sensors over time (in seconds). For example, if you have a sensor which
* stores power data in Watts, the resulting value will be energy in Joules
* (Watts * seconds).
*/
DCDB_C_RESULT dcdbQuerySumMultiple(
int64_t* result,
const char* hostname,
......@@ -56,6 +121,29 @@ DCDB_C_RESULT dcdbQuerySumMultiple(
DCDB_C_OPTIONS options
);
/**
* @brief This function is a threaded (this faster) implementation of dcdbQuerySumMultiple()
*
* @param result Pointer to a int64_t variable which will hold the result of the operation.
* @param hostname Hostname of a database node.
* @param port TCP port to use for connecting to the database node (for Cassandra, this is usually 9042).
* @param sensorPublicName Array of public names of the sensors whose values should be integrated.
* @param sensorPublicNameLength Number of sensors within sensorPublicName.
* @param start time_t denoting the start of the time series.
* @param end time_t denoting the end of the timer series.
* @param options Bitmask of DCDB_C_OPTIONS.
* @param numThreads Number of threads to spawn for the calculation.
*
* @details
* When calling this function, DCDBLib integrates the values of the given
* sensors over time (in seconds). For example, if you have a sensor which
* stores power data in Watts, the resulting value will be energy in Joules
* (Watts * seconds).
*
* Please be aware that it makes no sense to spawn more threads than the
* sensorPublicName array holds since the implementation will spawn at most
* one thread per sensor.
*/
DCDB_C_RESULT dcdbQuerySumMultipleThreaded(
int64_t* result,
const char* hostname,
......
/*
* connection.h
*
* Created on: May 18, 2015
* Author: Axel Auweter
*/
//================================================================================
// Name : connection.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ Application Programming Interface for DCDBLib connections
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
/**
* @file
......
/*
* sensorconfig.h
*
* Created on: May 19, 2015
* Author: Axel Auweter
*/
//================================================================================
// Name : sensorconfig.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ API for configuring DCDBLib public sensors.
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
/**
* @file
......@@ -27,67 +47,211 @@
namespace DCDB {
/* Forward-declaration of the implementation-internal classes */
class SensorConfigImpl;
/**
* This class is a container for the information DCDB keeps about public sensors.
*/
class PublicSensor
{
public:
std::string name;
bool is_virtual;
std::string pattern;
double scaling_factor;
std::string unit;
bool integrable;
std::string expression;
std::string v_sensorid;
uint64_t t_zero;
uint64_t frequency;
std::string name; /**< The public sensor's (public) name. */
bool is_virtual; /**< Denotes whether the sensor is a virtual sensor. */
std::string pattern; /**< For non-virtual sensors, this holds a pattern describing the (internal) sensor IDs to which this public sensor matches. */
double scaling_factor; /**< Unused! */
std::string unit; /**< Describes the unit of the sensor. See unitconv.h for known units. */
bool integrable; /**< Determines this sensor as being integrable. */
std::string expression; /**< For virtual sensors, this field holds the expression through which the virtual sensor's value is calculated. */
std::string v_sensorid; /**< For virtual sensors, this field holds a SensorID used for storing cached values in the database. (FIXME: Cache to be implemented) */
uint64_t t_zero; /**< For virtual sensors, this field holds the first point in time at which the sensor carries a value. */
uint64_t frequency; /**< For virtual sensors, this field holds the interval at which the sensor evaluates (in nanoseconds). */
PublicSensor();
PublicSensor(const PublicSensor &copy);
};
/**
* Enum type for representing the outcome of a DCDB SensorConfig API operation.
*/
typedef enum {
SC_OK,
SC_INVALIDSESSION,
SC_INVALIDPATTERN,
SC_INVALIDPUBLICNAME,
SC_INVALIDEXPRESSION,
SC_EXPRESSIONSELFREF,
SC_INVALIDVSENSORID,
SC_WRONGTYPE,
SC_UNKNOWNSENSOR,
SC_UNKNOWNERROR
SC_OK, /**< Everything went fine. */
SC_INVALIDSESSION, /**< The session / database connection is invalid */
SC_INVALIDPATTERN, /**< The supplied SensorID pattern is invalid */
SC_INVALIDPUBLICNAME, /**< The specified public name is invalid */
SC_INVALIDEXPRESSION, /**< The specified virtual sensor expression is invalid */
SC_EXPRESSIONSELFREF, /**< The specified virtual sensor references itself in the expression */
SC_INVALIDVSENSORID, /**< The virtual SensorID is invalid */
SC_WRONGTYPE, /**< You requested an operation for virtual sensors on a physical sensor or vice versa */
SC_UNKNOWNSENSOR, /**< The specified sensor is not known */
SC_UNKNOWNERROR /**< An unknown error occurred */
} SCError;
/**
* This class holds all functions to create/delete/modify the configuration of (virtual and non-virtual) public sensors in DCDB.
*/
class SensorConfig
{
protected:
SensorConfigImpl* impl;
public:
/**
* @brief Makes a physical sensor public.
*
* @param publicName Name under which the sensor becomes publicly available
* @param sensorPattern Pattern which describes the SensorIDs to which this sensor matches
* @return See SCError.
*/
SCError publishSensor(const char* publicName, const char* sensorPattern);
/**
* @brief Creates a new virtual sensor.
*
* @param publicName Name under which the sensor becomes publicly available
* @param vSensorExpression Arithmetic expression describing how to evaluate the virtual sensor.
* @param vSensorId SensorID under which previously evaluated values may be cached (FIXME: cache to be implemented).
* @param tZero Point in time at which the sensor evaluates for the first time.
* @param frequency Interval at which the sensor will evaluate (starting from tZero) in nanoseconds.
* @return See SCError.
*/
SCError publishVirtualSensor(const char* publicName, const char* vSensorExpression, const char * vSensorId, TimeStamp tZero, uint64_t frequency);
/**
* @brief Removes a (virtual or non-virtual) sensor from the list of public sensors.
*
* @param publicName Name under which the sensor becomes publicly available
* @return See SCError.
*/
SCError unPublishSensor(const char* publicName);
/**
* @brief Get the entire list of (virtual or non-virtual) public sensors.
*
* @param publicSensors Reference to a list of strings that will be populated with the sensor names.
* @return See SCError.
*/
SCError getPublicSensorNames(std::list<std::string>& publicSensors);
/**
* @brief Get the entire list of (virtual and non-virtual) public sensors including their definition.
*
* @param publicSensors Reference to a list of PublicSensor that will be populated with the sensors' definition.
* @return See SCError.
*/
SCError getPublicSensorsVerbose(std::list<PublicSensor>& publicSensors);
/**
* @brief Get the definition of a virtual sensor.
*
* @param sensor Reference to a PublicSensor object that will be populated with the sensor's definition.
* @param publicName Name of the sensor whose information should be retrieved.
* @return See SCError.
*/
SCError getPublicSensorByName(PublicSensor& sensor, const char* publicName);
/**
* @brief Determine whether a given sensor is a virtual sensor.
*
* @param isVirtual Reference to a bool which holds the result.
* @param publicName Name of the sensor whose information should be retrieved.
* @return See SCError.
*/
SCError isVirtual(bool& isVirtual, std::string publicName);
/**
* @brief Get the SensorID pattern for a given public sensor.
*
* @param pattern Reference to a string which holds the result.
* @param publicName Name of the sensor whose information should be retrieved.
* @return See SCError.
*/
SCError getSensorPattern(std::string& pattern, std::string publicName);
/**
* @brief Get the list of SensorIDs (available in the database) that match a given pattern.
*
* @param sensorIDs Reference to a list of SensorID which holds the result.
* @param pattern The SensorID pattern which should be matched by the resulting sensors.
* @return See SCError.
*/
SCError getSensorListForPattern(std::list<SensorId>& sensorIds, std::string pattern);
/**
* @brief Get the list of SensorIDs (available in the database) that match a given pattern - optimized version.
*
* @param pattern Reference to a string which holds the result.
* @param publicName Name of the sensor whose information should be retrieved.
* @param start Start of the time window
* @param end End of the time window
* @return See SCError.
*
* @details Since seeking the list of SensorIDs that match a given SensorID pattern is often
* used before querying the database in a given time window, this optimized version
* will be helpful in that it only returns SensorIDs that provide data in the given
* time window.
*/
SCError getSensorListForPattern(std::list<SensorId>& sensorIds, std::string pattern, TimeStamp start, TimeStamp end);
/**
* @brief Set the scaling factor for a public sensor. (FIXME: Scaling factors system is not in use!)
*
* @param publicName Name of the sensor.
* @param scalingFactor New scaling factor for the sensor.
* @return See SCError.
*/
SCError setSensorScalingFactor(std::string publicName, double scalingFactor);
/**
* @brief Set the unit for a public sensor.
*
* @param publicName Name of the sensor.
* @param unit New unis for the sensor. See unitconv.h for a list of supported units.
* @return See SCError.
*/
SCError setSensorUnit(std::string publicName, std::string unit);
/**
* @brief Set a sensor integrable or not.
*
* @param publicName Name of the sensor.
* @param integrable New integrable setting for the sensor.
* @return See SCError.
*/
SCError setSensorIntegrable(std::string publicName, bool integrable);
/**
* @brief Set a new sensor expression for a virtual sensor.
*
* @param publicName Name of the sensor.
* @param expression New virtual sensor expression.
* @return See SCError.
*/
SCError setVirtualSensorExpression(std::string publicName, std::string expression);
/**
* @brief Set the t0 for a virtual sensor.
*
* @param publicName Name of the sensor.
* @param tZero New tZero for the sensor.
* @return See SCError.
*/
SCError setVirtualSensorTZero(std::string publicName, TimeStamp tZero);
/**
* @brief Set the frequency (evaluation interval) for a virtual sensor.
*
* @param publicName Name of the sensor.
* @param frequency New evaluation interval for the sensor in nanoseconds.
* @return See SCError.
*/
SCError setVirtualSensorFrequency(std::string publicName, uint64_t frequency);
/**
* @brief Constructor for the SensorConfig class.
*
* @param conn Connection object of the current connection into the DCDB data store.
*/
SensorConfig(Connection* conn);
virtual ~SensorConfig();
};
......
/*
* sensordatastore.h
*
* Created on: Jul 24, 2013
* Author: Axel Auweter
*/
//================================================================================
// Name : sensordatastore.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ API for inserting and querying DCDB sensor data.
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
/**
* @file
......
/*
* sensorid.h
*
* Created on: May 18, 2015
* Author: Axel Auweter
*/
//================================================================================
// Name : sensorid.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ API for handling DCDB SensorIDs
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
#include <cstdint>
#include <string>
......
/*
* timestamp.h
*
* Created on: Feb 18, 2015
* Author: Axel Auweter
*/
//================================================================================
// Name : timestamp.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ API for handling time stamps in DCDBLib.
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
/**
* @file
......
/*
* unitconv.h
*
* Created on: Aug 12, 2015
* Author: Axel Auweter
*/
//================================================================================
// Name : unitconv.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ API for conversion of units in DCDBLib.
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
//================================================================================
#include <cstdint>
#include <string>
......@@ -13,6 +32,9 @@
namespace DCDB {
/**
* Enum type describing all units supported by the DCDBLib's unit conversion scheme.
*/
typedef enum {
/* Undefined */
Unit_None,
......@@ -62,6 +84,9 @@ typedef enum {
Unit_MicroCelsius,
} Unit;
/**
* This class provides an interface to the unit conversion support of DCDBLib.
*/
class UnitConv
{
public:
......
/*
* virtualsensor.h
*
* Created on: Jan 15, 2016
* Author: Axel Auweter
*/
//================================================================================
// Name : virtualsensor.h
// Author : Axel Auweter
// Copyright : Leibniz Supercomputing Centre
// Description : C++ API for evaulating virtual sensors in DCDBLib.
//================================================================================
//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or