RDB 2
Public Member Functions | List of all members
riegl::rdb::pointcloud::Transactions Class Reference

Manage point cloud transactions. More...

#include <transactions.hpp>

Public Member Functions

 Transactions (riegl::rdb::PointcloudData *pointcloud)
 Constructor. More...
 
Transaction::ID begin (const std::string &title, const std::string &agent, const std::string &comments="", const std::string &settings="")
 Create new transaction. More...
 
void commit (Progress progress=nullptr, void *userdata=nullptr, const std::uint32_t signature=0, const std::uint32_t key_size=0, const void *const key_data=nullptr)
 Commit current transaction. More...
 
template<typename Callable >
void commit (Callable &&progress, const std::uint32_t signature=0, const std::uint32_t key_size=0, const void *const key_data=nullptr)
 Commit current transaction. More...
 
template<typename Receiver >
void commit (void(Receiver::*progress)(std::uint8_t), Receiver &receiver, const std::uint32_t signature=0, const std::uint32_t key_size=0, const void *const key_data=nullptr)
 Commit current transaction. More...
 
template<typename Receiver >
void commit (void(Receiver::*progress)(std::uint8_t) const, const Receiver &receiver, const std::uint32_t signature=0, const std::uint32_t key_size=0, const void *const key_data=nullptr)
 Commit current transaction. More...
 
void rollback ()
 Abort current transaction. More...
 
std::vector< Transaction::IDlist () const
 Get list of transactions. More...
 
Transaction::ID current () const
 ID of current transaction. More...
 
bool pending () const
 Check if transaction is pending. More...
 
Transaction details (const Transaction::ID transaction) const
 Query transaction details. More...
 
void restore (const Transaction::ID transaction)
 Restore database state. More...
 
void discard (const Transaction::ID transaction)
 Discard transaction data. More...
 
void discard (const std::vector< Transaction::ID > &transactions)
 Discard transaction data. More...
 
std::uint64_t size (const Transaction::ID transaction) const
 Estimate database size. More...
 
std::uint64_t size (const std::vector< Transaction::ID > &transactions) const
 Estimate database size. More...
 

Detailed Description

Manage point cloud transactions.

Modifying the point cloud database means to execute a transaction.

This class allows to start new transactions (see begin()) and to browse past (already executed) transactions.

See also
riegl::rdb::Pointcloud::transaction()

Definition at line 68 of file transactions.hpp.

Constructor & Destructor Documentation

◆ Transactions()

riegl::rdb::pointcloud::Transactions::Transactions ( riegl::rdb::PointcloudData *  pointcloud)
explicit

Constructor.

Note
You cannot create new Transactions objects directly, use riegl::rdb::Pointcloud::transaction() instead.

Member Function Documentation

◆ begin()

Transaction::ID riegl::rdb::pointcloud::Transactions::begin ( const std::string &  title,
const std::string &  agent,
const std::string &  comments = "",
const std::string &  settings = "" 
)

Create new transaction.

Whenever you are going to modify the point cloud, you must create a transaction by using this function. Without a transaction, any function that modifies the point cloud will fail (i.e. it throws an exception).

A transaction automatically locks the database so that other users can query data but can NOT add or modify data. Please note that only one transaction at a time is allowed. If there is already a transaction pending, this function will raise an exception (see Error::TransactionPending).

To finish a transaction either call commit() or rollback().

Note
Parameters 'title' and 'agent' are required - i.e. creating a new transaction will fail if empty strings are provided. All other parameters are optional.
Parameters 'comments' and 'settings' serve the user and client application for information, e.g. to repeat processing steps later on. They have no influence on the transaction itself. The client application is free to store information in any format that is string-compatible (e.g. plain text, INI, XML, JSON).
The total size of the 'title', 'agent', 'comments' and 'settings' strings must not exceed 500 MB (bytes, not characters).
Parameters
[in]titleshort description, e.g. "Import"
[in]agentsoftware name, e.g. "rdbimport v1.0"
[in]commentse.g. process details for humans
[in]settingse.g. process settings for software

◆ commit() [1/4]

template<typename Callable >
void riegl::rdb::pointcloud::Transactions::commit ( Callable &&  progress,
const std::uint32_t  signature = 0,
const std::uint32_t  key_size = 0,
const void *const  key_data = nullptr 
)
inline

Commit current transaction.

Overloaded commit() that takes any callable type as progress callback.

Parameters
[in]progressprogress callback function
[in]signaturesignature method (0: none, 1: default)
[in]key_sizesignature encryption key size (at least 32 byte)
[in]key_datasignature encryption key buffer

Definition at line 133 of file transactions.hpp.

◆ commit() [2/4]

void riegl::rdb::pointcloud::Transactions::commit ( Progress  progress = nullptr,
void *  userdata = nullptr,
const std::uint32_t  signature = 0,
const std::uint32_t  key_size = 0,
const void *const  key_data = nullptr 
)

Commit current transaction.

This function commits the current transaction. All changes made by the transaction become visible to others.

Parameters
[in]progresscommit progress callback function
[in]userdataprogress callback function user data
[in]signaturesignature method (0: none, 1: default)
[in]key_sizesignature encryption key size (at least 32 byte)
[in]key_datasignature encryption key buffer

◆ commit() [3/4]

template<typename Receiver >
void riegl::rdb::pointcloud::Transactions::commit ( void(Receiver::*)(std::uint8_t) const  progress,
const Receiver &  receiver,
const std::uint32_t  signature = 0,
const std::uint32_t  key_size = 0,
const void *const  key_data = nullptr 
)
inline

Commit current transaction.

Overloaded commit() that takes a constant progress callback method of a constant object.

Parameters
[in]signaturesignature method (0: none, 1: default)
[in]key_sizesignature encryption key size (at least 32 byte)
[in]key_datasignature encryption key buffer

Definition at line 175 of file transactions.hpp.

◆ commit() [4/4]

template<typename Receiver >
void riegl::rdb::pointcloud::Transactions::commit ( void(Receiver::*)(std::uint8_t)  progress,
Receiver &  receiver,
const std::uint32_t  signature = 0,
const std::uint32_t  key_size = 0,
const void *const  key_data = nullptr 
)
inline

Commit current transaction.

Overloaded commit() that takes a progress callback method of an object.

Parameters
[in]signaturesignature method (0: none, 1: default)
[in]key_sizesignature encryption key size (at least 32 byte)
[in]key_datasignature encryption key buffer

Definition at line 154 of file transactions.hpp.

◆ current()

Transaction::ID riegl::rdb::pointcloud::Transactions::current ( ) const

ID of current transaction.

This function returns the ID of the current transaction. Usually this is the transaction that was committed at last. However, if restore() is used to return to a previous database state, the current transaction is the restored transaction.

Note
This function does not return the ID of a pending transaction.

◆ details()

Transaction riegl::rdb::pointcloud::Transactions::details ( const Transaction::ID  transaction) const

Query transaction details.

Parameters
[in]transactiontransaction identifier

◆ discard() [1/2]

void riegl::rdb::pointcloud::Transactions::discard ( const std::vector< Transaction::ID > &  transactions)

Discard transaction data.

This function deletes the given transaction(s). Please note that this operation only removes the transaction(s) from the database history and releases the related data blocks in the database file so that they can be re-used by subsequent transactions. However the database file size will not decrease unless you call vacuum().

Note
The first (database creation) and the current transaction (last committed or restored) can not be deleted.
See also
riegl::rdb::pointcloud::Management::finalize()
riegl::rdb::pointcloud::Management::vacuum()
Parameters
[in]transactionstransaction identifiers

◆ discard() [2/2]

void riegl::rdb::pointcloud::Transactions::discard ( const Transaction::ID  transaction)

Discard transaction data.

This function deletes the given transaction(s). Please note that this operation only removes the transaction(s) from the database history and releases the related data blocks in the database file so that they can be re-used by subsequent transactions. However the database file size will not decrease unless you call vacuum().

Note
The first (database creation) and the current transaction (last committed or restored) can not be deleted.
See also
riegl::rdb::pointcloud::Management::finalize()
riegl::rdb::pointcloud::Management::vacuum()
Parameters
[in]transactiontransaction identifier

◆ list()

std::vector<Transaction::ID> riegl::rdb::pointcloud::Transactions::list ( ) const

Get list of transactions.

The database keeps a log (journal) of all transactions. This function returns a list of identifiers (IDs) for all recorded transactions.

◆ pending()

bool riegl::rdb::pointcloud::Transactions::pending ( ) const

Check if transaction is pending.

This function checks whether there is a pending transaction that was started by this database instance. This function does not check whether a transaction was started by a different database instance of the current or different thread or process.

◆ restore()

void riegl::rdb::pointcloud::Transactions::restore ( const Transaction::ID  transaction)

Restore database state.

This function restores the database state that was current at the end of the transaction. Those transactions that were created after the restored transaction remain valid until a new transaction is created. This offers some simple undo/redo functionality.

Parameters
[in]transactiontransaction identifier

◆ rollback()

void riegl::rdb::pointcloud::Transactions::rollback ( )

Abort current transaction.

This function rolls back the current transaction and causes all changes made by the transaction to be discarded.

◆ size() [1/2]

std::uint64_t riegl::rdb::pointcloud::Transactions::size ( const std::vector< Transaction::ID > &  transactions) const

Estimate database size.

This function returns the size (in bytes) of all data of the specified transactions, which is approximately the file size of a database that contains only these transactions (and no gaps).

Note
Data blocks may be shared among multiple transactions and size() returns the total size of the union of all used data blocks. That is why size(1) + size(2) is not necessarily equal to size(1, 2).
See also
riegl::rdb::pointcloud::Transactions::discard()
riegl::rdb::pointcloud::Management::finalize()
riegl::rdb::pointcloud::Management::vacuum()
Parameters
[in]transactionstransaction identifiers

◆ size() [2/2]

std::uint64_t riegl::rdb::pointcloud::Transactions::size ( const Transaction::ID  transaction) const

Estimate database size.

This function returns the size (in bytes) of all data of the specified transactions, which is approximately the file size of a database that contains only these transactions (and no gaps).

Note
Data blocks may be shared among multiple transactions and size() returns the total size of the union of all used data blocks. That is why size(1) + size(2) is not necessarily equal to size(1, 2).
See also
riegl::rdb::pointcloud::Transactions::discard()
riegl::rdb::pointcloud::Management::finalize()
riegl::rdb::pointcloud::Management::vacuum()
Parameters
[in]transactiontransaction identifier

The documentation for this class was generated from the following file: