RDM::DB::transaction< NEXT > Class Template Reference

Template Class for doing transactions. More...

#include "rdm_db_transaction.h"

Public Member Functions

RDM_RETCODE init (RDM_DB db)
Initialize this object. More...
RDM_RETCODE begin (void)
Start a transaction. More...
RDM_RETCODE end (void)
End a transaction. More...
RDM_RETCODE rollback (void)
Roll back a transaction. More...
void reset (void)
Reset this object. More...
RDM_RETCODE flush_value (uint32_t threshold=1, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
Flush this object. More...
RDM_RETCODE flush_stats (uint32_t threshold=1, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
Flush this object. More...
RDM_RETCODE flush_range (uint32_t threshold=1, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
Flush this object. More...
template<class SOURCE_VALUE_T >
RDM_RETCODE put_value (SOURCE_VALUE_T *source_value, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
Template method for receiving a data value. More...
template<class SOURCE_STATS_T >
RDM_RETCODE put_stats (SOURCE_STATS_T *source_stats, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
Template method for receiving statistics. More...
template<class SOURCE_RANGE_T >
RDM_RETCODE put_range (SOURCE_RANGE_T *source_range, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
Template method for receiving ranges. More...

Data Fields

NEXT next

Detailed Description

template<class NEXT>
class RDM::DB::transaction< NEXT >

Template Class for doing transactions.

Template class for doing transactions of data values, ranges, or statistics. What is received by this class will be forwarded to the next class. start() must be called before data can received. Call end() when done. Alternatively, rollback() can be called to roll back the transaction. Rolling back the transaction will also rewind the state of the time series classes back to the state when the transaction was started.

Template Parameters
NEXT The next class in the chain of classes to receive data, ranges, or statistics.
Examples
cpp70Example_main.cpp, and time_series_fft.cpp.

Member Function Documentation

begin()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::begin ( void )
inline

Start a transaction.

Before doing any put or flush operations, a transaction must be started by calling this method. Call end() or rollback() when done.

For the correct operation, none of the RDM transaction operations, such as rdm_dbStartUpdate(), rdm_dbStartRead(), and rdm_dbEnd(), should be called until end() has been called.

Return values
sOKAY Normal, successful return.
eTRACTIVE Transaction is active.
111 {
112RDM_RETCODE rc;
113
114if (transaction_active)
115 {
116 rc = eTRACTIVE;
117 }
118else
119 {
120if (RDM_LEN (tables_to_write_lock) > 1)
121 {
122 rc = rdm_dbStartUpdate (db, tables_to_write_lock, RDM_LEN (tables_to_write_lock) - 1, tables_to_read_lock, RDM_LEN (tables_to_read_lock) - 1, &trans);
123 }
124else
125 {
126 rc = rdm_dbStartRead (db, tables_to_read_lock, RDM_LEN (tables_to_read_lock) - 1, &trans);
127 }
128if (rc == sOKAY)
129 {
130 transaction_active = true;
131 next_backup_state = next;
132 }
133 }
134
135return rc;
136 }

References eTRACTIVE, RDM::DB::transaction< NEXT >::next, rdm_dbStartRead(), rdm_dbStartUpdate(), RDM_LEN, and sOKAY.

Here is the call graph for this function:

end()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::end ( void )
inline

End a transaction.

Call this method to end a transaction started with begin(). Any changes made using the put or flush methods will be applied.

Return values
sOKAY Normal, successful return.
eTRNOTACT Transaction not active.
148 {
149RDM_RETCODE rc;
150
151if (transaction_active)
152 {
153 rc = rdm_transEnd (trans);
154if (rc == sOKAY)
155 {
156 transaction_active = false;
157 }
158 }
159else
160 {
161 rc = eTRNOTACT;
162 }
163
164return rc;
165 }

References eTRNOTACT, rdm_transEnd(), and sOKAY.

Here is the call graph for this function:

flush_range()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::flush_range ( uint32_t threshold = 1,
TRANSACTIONAL_T transactional = 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 ranges will be kept as is. The same is the case when 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
306 {
307RDM_RETCODE rc = next.flush_range (threshold, transactional);
308
309return rc;
310 }

References RDM::DB::transaction< NEXT >::next.

flush_stats()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::flush_stats ( uint32_t threshold = 1,
TRANSACTIONAL_T transactional = 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 when 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
271 {
272RDM_RETCODE rc = next.flush_stats (threshold, transactional);
273
274return rc;
275 }

References RDM::DB::transaction< NEXT >::next.

flush_value()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::flush_value ( uint32_t threshold = 1,
TRANSACTIONAL_T transactional = 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 when 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
236 {
237RDM_RETCODE rc = next.flush_value (threshold, transactional);
238
239return rc;
240 }

References RDM::DB::transaction< NEXT >::next.

init()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::init ( RDM_DB db )
inline

Initialize this object.

Call this method before sending it any data values, ranges, 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
81 {
82RDM_RETCODE rc = next.init (db);
83
84if (rc == sOKAY)
85 {
86 transaction::db = db;
87 transaction_active = false;
88 }
89
90 (void) next.init_tables_to_read_lock (tables_to_read_lock);
91 (void) next.init_tables_to_write_lock (tables_to_write_lock);
92
93return rc;
94 }

References RDM::DB::transaction< NEXT >::next, and sOKAY.

put_range()

template<class NEXT >
template<class SOURCE_RANGE_T >
RDM_RETCODE RDM::DB::transaction< NEXT >::put_range ( SOURCE_RANGE_T * source_range,
TRANSACTIONAL_T transactional = NOT_TRANSACTIONAL
)
inline

Template method for receiving ranges.

Receive one range and process it accordingly.

The type for the value provided is required to have columns for 'time_stamp_first', 'time_stamp_last', and 'value_range' with appropriate types. The column 'value_range' must be an array that is able to hold a static number of elements. Such a type can be generated using rdm-compile with a schema including a table similar to this:

CREATE TABLE range
(
value_range DOUBLE ARRAY [32] NOT NULL,
time_stamp_first UINT64 NOT NULL,
time_stamp_last UINT64 PRIMARY KEY
);

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_RANGE_T The actual type of the range 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_range The source range sent to this class
transactional [IN] Is the put required to be transactional
456 {
457RDM_RETCODE rc = next.put_range (source_range, transactional);
458
459return rc;
460 }

References RDM::DB::transaction< NEXT >::next.

put_stats()

template<class NEXT >
template<class SOURCE_STATS_T >
RDM_RETCODE RDM::DB::transaction< NEXT >::put_stats ( SOURCE_STATS_T * source_stats,
TRANSACTIONAL_T transactional = 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_STAT_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
405 {
406RDM_RETCODE rc = next.put_stats (source_stats, transactional);
407
408return rc;
409 }

References RDM::DB::transaction< NEXT >::next.

put_value()

template<class NEXT >
template<class SOURCE_VALUE_T >
RDM_RETCODE RDM::DB::transaction< NEXT >::put_value ( SOURCE_VALUE_T * source_value,
TRANSACTIONAL_T transactional = 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
354 {
355RDM_RETCODE rc = next.put_value (source_value, transactional);
356
357return rc;
358 }

References RDM::DB::transaction< NEXT >::next.

reset()

template<class NEXT >
void RDM::DB::transaction< 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.

204 {
205next.reset ();
206 }

References RDM::DB::transaction< NEXT >::next.

rollback()

template<class NEXT >
RDM_RETCODE RDM::DB::transaction< NEXT >::rollback ( void )
inline

Roll back a transaction.

Call this method to roll back a transaction started with begin(). Any changes made using the put or flush methods will be rolled back.

Return values
sOKAY Normal, successful return.
eTRNOTACT Transaction not active.
177 {
178RDM_RETCODE rc;
179
180if (transaction_active)
181 {
182 rc = rdm_transEndRollback (trans);
183if (rc == sOKAY)
184 {
185 transaction_active = false;
186next = next_backup_state;
187 }
188 }
189else
190 {
191 rc = eTRNOTACT;
192 }
193
194return rc;
195 }

References eTRNOTACT, RDM::DB::transaction< NEXT >::next, rdm_transEndRollback(), and sOKAY.

Here is the call graph for this function:

Field Documentation

next


The documentation for this class was generated from the following file:
RDM_RETCODE rdm_transEnd(RDM_TRANS trans)
End a transactional operation.
@ eTRACTIVE
Definition: rdmretcodetypes.h:110
@ eTRNOTACT
Definition: rdmretcodetypes.h:111
RDM_RETCODE rdm_transEndRollback(RDM_TRANS trans)
End a transactional operation with a rollback.
RDM_RETCODE rdm_dbStartRead(RDM_DB db, const RDM_TABLE_ID *tableIds, uint32_t numTableIds, RDM_TRANS *pTrans)
Get read locks.
@ sOKAY
Definition: rdmretcodetypes.h:98
NEXT next
Definition: rdm_db_transaction.h:66
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.
#define RDM_LEN(x)
Definition: psptypes.h:78
RDM_RETCODE
RDM status and error return codes.
Definition: rdmretcodetypes.h:44