Currently job artifacts in CI/CD pipelines on LRZ GitLab never expire. Starting from Wed 26.1.2022 the default expiration time will be 30 days (GitLab default). Currently existing artifacts in already completed jobs will not be affected by the change. The latest artifacts for all jobs in the latest successful pipelines will be kept. More information: https://gitlab.lrz.de/help/user/admin_area/settings/continuous_integration.html#default-artifacts-expiration

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
// modify it under the terms of the GNU Lesser General Public