RDM::TIME_SERIES::stats< N, STATS_T, NEXT > Class Template Reference

Template Class for doing statistics. More...

#include "rdm_time_series_stats.h"

Public Member Functions

RDM_RETCODE init (RDM_DB db)
Initialize this object. More...
void reset (void)
Reset this object. More...
RDM_RETCODE flush_value (uint32_t threshold=1, RDM::DB::TRANSACTIONAL_T transactional=RDM::DB::NOT_TRANSACTIONAL)
Flush this object. More...
RDM_RETCODE flush_stats (uint32_t threshold=1, RDM::DB::TRANSACTIONAL_T transactional=RDM::DB::NOT_TRANSACTIONAL)
Flush this object. More...
template<class SOURCE_VALUE_T >
RDM_RETCODE put_value (SOURCE_VALUE_T *source_value, RDM::DB::TRANSACTIONAL_T transactional=RDM::DB::NOT_TRANSACTIONAL)
Template method for receiving a data value. More...
template<class SOURCE_STATS_T >
RDM_RETCODE put_stats (SOURCE_STATS_T *source_stats, RDM::DB::TRANSACTIONAL_T transactional=RDM::DB::NOT_TRANSACTIONAL)
Template method for receiving statistics. More...

Friends

template<class ANY_NEXT >
class RDM::DB::transaction
template<class ANY_NEXT_1 , class ANY_NEXT_2 >
class split
template<uint32_t ANY_N, class ANY_RANGE_T , class ANY_NEXT >
class collect
template<uint32_t ANY_N, class ANY_RANGE_T , class ANY_INDATA_T , class ANY_NEXT >
class fft
template<uint32_t ANY_N, class ANY_AGGREGATE_T , class ANY_AGG_ELEMENT_T , class ANY_NEXT >
class mean
template<class ANY_RATIO , class ANY_NEXT >
class scale
template<uint32_t ANY_N, class ANY_STATS_T , class ANY_NEXT >
class stats
template<uint32_t ANY_N, class ANY_NEXT >
class downsample
template<class ANY_NEXT >
class custom

Detailed Description

template<uint32_t N, class STATS_T, class NEXT>
class RDM::TIME_SERIES::stats< N, STATS_T, NEXT >

Template Class for doing statistics.

Template class for doing statistics of data values or aggregating statistics. It is an error for this class to receive ranges. The sum of the data values (sum), the sum of the squared data values (sum2), and the total number of data values (n) will be computed or aggregated. The result of this will be forwarded to the next class in the chain.

We collect these values for easy calculation of the mean value and the standard deviation. These can be calculated as follows (we included the Bessel's correction here):

  • Mean value: sum / n
  • Standard deviation: sqrt ((sum2 - sum * sum / n) / (n - 1))

Upon destruction of this class, there might be incomplete aggregations that have not yet been passed to the next class in the chain. flush() can be called to force those incomplete aggregations to be sent to the next class. This approach may not always be desirable. Another approach is to restore the state of this class the next time this class is instantiated. See restore_aggregate for details.

Template Parameters
N The number of receved elements to average.
STATS_T The aggregate statistics class for which objects will be passed to the next class.
NEXT The class in the chain to receive statistics.
Examples
cpp70Example_main.cpp, time_series_custom.cpp, time_series_restore_aggregate.cpp, and time_series_stats.cpp.

Member Function Documentation

flush_stats()

template<uint32_t N, class STATS_T , class NEXT >
RDM_RETCODE RDM::TIME_SERIES::stats< N, STATS_T, NEXT >::flush_stats ( uint32_t threshold = 1,
RDM::DB::TRANSACTIONAL_T transactional = RDM::DB::NOT_TRANSACTIONAL
)
inline

Flush this object.

Call this method to flush what has been collected so far. A threshold can also be provided. All the data collected for those statistics will be kept as is. The same is the case where the threshold has not been reached.

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Return values
sOKAY Normal, successful return.
eNOSTARTUPDATE An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED Attempt to access a table for reading or update without proper locks.
eCURSORDB Cursor is associated with a different database.
eDBNOTOPEN Database not open.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE Attempt to insert a duplicate value as a unique/primary key.
eREADONLY Database is read-only and cannot be updated.
eREFINTEGRITY Integrity constraint violation.
eROWLIMIT Table row limit reached.
eINVARG Invalid argument.
Parameters
threshold [IN] Only flush objects where at least this many elements have been collected
transactional [IN] Is the flush required to be transactional
295 {
296RDM_RETCODE rc = sOKAY;
297
298if (n >= threshold && n > 0)
299 {
300RDM_TRANS trans;
301
302if (transactional == RDM::DB::TRANSACTIONAL)
303 {
304 rc = rdm_dbStartUpdate (db, NULL, 0, NULL, 0, &trans);
305 }
306
307if (rc == sOKAY)
308 {
309 rc = next.put_stats (&aggregate_stats, transactional);
310if (rc == sOKAY)
311 {
312 n_just_before_last_flush = n;
313 rc = next.flush_stats (threshold, transactional);
314if (rc == sOKAY)
315 {
316 n = 0;
317 }
318else
319 {
320 next.unput ();
321 }
322 }
323if (transactional == RDM::DB::TRANSACTIONAL)
324 {
325if (rc == sOKAY)
326 {
327 rc = rdm_transEnd (trans);
328 }
329else
330 {
332 }
333 }
334 }
335 }
336else
337 {
338if (n == 0)
339 {
340 n_just_before_last_flush = 0;
341 }
342 rc = next.flush_stats (threshold, transactional);
343 }
344
345return rc;
346 }

References rdm_dbStartUpdate(), rdm_transEnd(), rdm_transEndRollback(), sOKAY, and RDM::DB::TRANSACTIONAL.

Here is the call graph for this function:

flush_value()

template<uint32_t N, class STATS_T , class NEXT >
RDM_RETCODE RDM::TIME_SERIES::stats< N, STATS_T, NEXT >::flush_value ( uint32_t threshold = 1,
RDM::DB::TRANSACTIONAL_T transactional = RDM::DB::NOT_TRANSACTIONAL
)
inline

Flush this object.

Call this method to flush what has been collected so far. A threshold can also be provided. All the data collected for those values will be kept as is. The same is the case where the threshold has not been reached.

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Return values
sOKAY Normal, successful return.
eNOSTARTUPDATE An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED Attempt to access a table for reading or update without proper locks.
eCURSORDB Cursor is associated with a different database.
eDBNOTOPEN Database not open.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE Attempt to insert a duplicate value as a unique/primary key.
eREADONLY Database is read-only and cannot be updated.
eREFINTEGRITY Integrity constraint violation.
eROWLIMIT Table row limit reached.
eINVARG Invalid argument.
Parameters
threshold [IN] Only flush objects where at least this many elements have been collected
transactional [IN] Is the flush required to be transactional
213 {
214RDM_RETCODE rc = sOKAY;
215
216if (n >= threshold && n > 0)
217 {
218
219RDM_TRANS trans;
220
221if (transactional == RDM::DB::TRANSACTIONAL)
222 {
223 rc = rdm_dbStartUpdate (db, NULL, 0, NULL, 0, &trans);
224 }
225
226if (rc == sOKAY)
227 {
228 rc = next.put_stats (&aggregate_stats, RDM::DB::NOT_TRANSACTIONAL);
229if (rc == sOKAY)
230 {
231 n_just_before_last_flush = n;
232 rc = next.flush_stats (threshold, RDM::DB::NOT_TRANSACTIONAL);
233if (rc == sOKAY)
234 {
235 n = 0;
236 }
237else
238 {
239 next.unput ();
240 }
241 }
242if (transactional == RDM::DB::TRANSACTIONAL)
243 {
244if (rc == sOKAY)
245 {
246 rc = rdm_transEnd (trans);
247 }
248else
249 {
251 }
252 }
253 }
254 }
255else
256 {
257if (n == 0)
258 {
259 n_just_before_last_flush = 0;
260 }
261 rc = next.flush_stats (threshold, transactional);
262 }
263
264return rc;
265 }

References RDM::DB::NOT_TRANSACTIONAL, rdm_dbStartUpdate(), rdm_transEnd(), rdm_transEndRollback(), sOKAY, and RDM::DB::TRANSACTIONAL.

Here is the call graph for this function:

init()

template<uint32_t N, class STATS_T , class NEXT >
RDM_RETCODE RDM::TIME_SERIES::stats< N, STATS_T, NEXT >::init ( RDM_DB db )
inline

Initialize this object.

Call this method before sending it any data values or statistics.

Return values
sOKAY Normal, successful return.
eINVARG Invalid argument.
eDBNOTOPEN Database not open.
eCURSORDB Cursor is associated with a different database.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
Parameters
db [IN] Use this database for chained classes that need to insert rows
Examples
time_series_custom.cpp.
166 {
167RDM_RETCODE rc = next.init (db);
168 n = 0;
169
170return rc;
171 }

put_stats()

template<uint32_t N, class STATS_T , class NEXT >
template<class SOURCE_STATS_T >
RDM_RETCODE RDM::TIME_SERIES::stats< N, STATS_T, NEXT >::put_stats ( SOURCE_STATS_T * source_stats,
RDM::DB::TRANSACTIONAL_T transactional = RDM::DB::NOT_TRANSACTIONAL
)
inline

Template method for receiving statistics.

Receive one statistic and process it accordingly.

The type for the value provided is required to have columns for 'time_stamp_first', 'time_stamp_last', 'n', 'value_sum', and 'value_sum2' with appropriate types. Such a type can be generated using rdm-compile with a schema including a table similar to this:

CREATE TABLE stats
(
time_stamp_first UINT64 NOT NULL,
time_stamp_last UINT64 PRIMARY KEY,
n UINT64 NOT NULL,
value_sum DOUBLE NOT NULL,
value_sum2 DOUBLE NOT NULL
);

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Template Parameters
SOURCE_STATS_T The actual type of the statistic received.
Return values
sOKAY Normal, successful return.
eNOSTARTUPDATE An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED Attempt to access a table for reading or update without proper locks.
eCURSORDB Cursor is associated with a different database.
eDBNOTOPEN Database not open.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE Attempt to insert a duplicate value as a unique/primary key.
eREADONLY Database is read-only and cannot be updated.
eREFINTEGRITY Integrity constraint violation.
eROWLIMIT Table row limit reached.
eINVARG Invalid argument.
Parameters
[in] source_stats The source statistics sent to this class
transactional [IN] Is the put required to be transactional
482 {
483RDM_RETCODE rc = sOKAY;
484
485 prev_aggregate_stats = aggregate_stats;
486
487if (n == 0)
488 {
489 aggregate_stats.time_stamp_first =
490 source_stats->time_stamp_first;
491 aggregate_stats.n = source_stats->n;
492 aggregate_stats.value_sum = source_stats->value_sum;
493 aggregate_stats.value_sum2 = source_stats->value_sum2;
494 }
495else
496 {
497 aggregate_stats.n += source_stats->n;
498 aggregate_stats.value_sum = aggregate_stats.value_sum + source_stats->value_sum;
499 aggregate_stats.value_sum2 = aggregate_stats.value_sum2 + source_stats->value_sum2;
500 }
501 aggregate_stats.time_stamp_last =
502 source_stats->time_stamp_last;
503
504if (n == N - 1)
505 {
506 rc = next.put_stats (&aggregate_stats, transactional);
507if (rc == sOKAY)
508 {
509 n_just_before_last_put = n;
510 n = 0;
511 }
512else
513 {
514 aggregate_stats = prev_aggregate_stats;
515 }
516 }
517else
518 {
519 n++;
520 }
521
522return rc;
523 }

References sOKAY.

put_value()

template<uint32_t N, class STATS_T , class NEXT >
template<class SOURCE_VALUE_T >
RDM_RETCODE RDM::TIME_SERIES::stats< N, STATS_T, NEXT >::put_value ( SOURCE_VALUE_T * source_value,
RDM::DB::TRANSACTIONAL_T transactional = RDM::DB::NOT_TRANSACTIONAL
)
inline

Template method for receiving a data value.

Receive one data value and process it accordingly.

The type for the value provided is required to have columns for 'time_stamp_current' and 'value_current' with appropriate types. Such a type can be generated using rdm-compile with a schema including a table similar to this:

CREATE TABLE measurement
(
time_stamp_current UINT64 PRIMARY KEY,
value_current DOUBLE NOT NULL
);

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Template Parameters
SOURCE_VALUE_T The actual type of the source values received
Return values
sOKAY Normal, successful return.
eNOSTARTUPDATE An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED Attempt to access a table for reading or update without proper locks.
eCURSORDB Cursor is associated with a different database.
eDBNOTOPEN Database not open.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE Attempt to insert a duplicate value as a unique/primary key.
eREADONLY Database is read-only and cannot be updated.
eREFINTEGRITY Integrity constraint violation.
eROWLIMIT Table row limit reached.
eINVARG Invalid argument.
Parameters
[in] source_value The source value sent to this class
transactional [IN] Is the put required to be transactional
390 {
391RDM_RETCODE rc = sOKAY;
392
393 prev_aggregate_stats = aggregate_stats;
394
395if (n == 0)
396 {
397 aggregate_stats.time_stamp_first =
398 source_value->time_stamp_current;
399 aggregate_stats.n = 1;
400 aggregate_stats.value_sum = source_value->value_current;
401 aggregate_stats.value_sum2 = source_value->value_current *
402 source_value->value_current;
403 }
404else
405 {
406 aggregate_stats.n++;
407 aggregate_stats.value_sum = aggregate_stats.value_sum + source_value->value_current;
408 aggregate_stats.value_sum2 = aggregate_stats.value_sum2 + source_value->value_current *
409 source_value->value_current;
410 }
411
412 aggregate_stats.time_stamp_last =
413 source_value->time_stamp_current;
414
415if (n == N - 1)
416 {
417 rc = next.put_stats (&aggregate_stats, transactional);
418if (rc == sOKAY)
419 {
420 n_just_before_last_put = n;
421 n = 0;
422 }
423else
424 {
425 aggregate_stats = prev_aggregate_stats;
426 }
427 }
428else
429 {
430 n++;
431 }
432
433
434return rc;
435 }

References sOKAY.

reset()

template<uint32_t N, class STATS_T , class NEXT >
void RDM::TIME_SERIES::stats< N, STATS_T, NEXT >::reset ( void )
inline

Reset this object.

Call this method to discard all internally kept data values, ranges, and statistics that have not yet been persisted and start over from scratch.

180 {
181 next.reset ();
182 n = 0;
183 }

Friends And Related Function Documentation

collect

template<uint32_t N, class STATS_T , class NEXT >
template<uint32_t ANY_N, class ANY_RANGE_T , class ANY_NEXT >
friend class collect
friend

custom

template<uint32_t N, class STATS_T , class NEXT >
template<class ANY_NEXT >
friend class custom
friend

downsample

template<uint32_t N, class STATS_T , class NEXT >
template<uint32_t ANY_N, class ANY_NEXT >
friend class downsample
friend

fft

template<uint32_t N, class STATS_T , class NEXT >
template<uint32_t ANY_N, class ANY_RANGE_T , class ANY_INDATA_T , class ANY_NEXT >
friend class fft
friend

mean

template<uint32_t N, class STATS_T , class NEXT >
template<uint32_t ANY_N, class ANY_AGGREGATE_T , class ANY_AGG_ELEMENT_T , class ANY_NEXT >
friend class mean
friend

RDM::DB::transaction

template<uint32_t N, class STATS_T , class NEXT >
template<class ANY_NEXT >
friend class RDM::DB::transaction
friend

scale

template<uint32_t N, class STATS_T , class NEXT >
template<class ANY_RATIO , class ANY_NEXT >
friend class scale
friend

split

template<uint32_t N, class STATS_T , class NEXT >
template<class ANY_NEXT_1 , class ANY_NEXT_2 >
friend class split
friend

stats

template<uint32_t N, class STATS_T , class NEXT >
template<uint32_t ANY_N, class ANY_STATS_T , class ANY_NEXT >
friend class stats
friend

The documentation for this class was generated from the following files:
RDM_RETCODE rdm_transEnd(RDM_TRANS trans)
End a transactional operation.
@ NOT_TRANSACTIONAL
Definition: rdm_db_transaction.h:36
RDM_RETCODE rdm_transEndRollback(RDM_TRANS trans)
End a transactional operation with a rollback.
@ sOKAY
Definition: rdmretcodetypes.h:97
struct RDM_TRANS_S * RDM_TRANS
Definition: rdmtypes.h:307
RDM_RETCODE rdm_dbStartUpdate(RDM_DB db, const RDM_TABLE_ID *writeTableIds, uint32_t numWriteTableIds, const RDM_TABLE_ID *readTableIds, uint32_t numReadTableIds, RDM_TRANS *pTrans)
Get write locks.
@ TRANSACTIONAL
Definition: rdm_db_transaction.h:35
RDM_RETCODE
RDM status and error return codes.
Definition: rdmretcodetypes.h:43