http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/transactions/transaction.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/transactions/transaction.h b/modules/platforms/cpp/core/include/ignite/transactions/transaction.h index f68470e..b51a42c 100644 --- a/modules/platforms/cpp/core/include/ignite/transactions/transaction.h +++ b/modules/platforms/cpp/core/include/ignite/transactions/transaction.h @@ -24,7 +24,6 @@ #define _IGNITE_TRANSACTIONS_TRANSACTION #include <ignite/common/concurrent.h> -#include <ignite/jni/java.h> #include "ignite/impl/transactions/transaction_impl.h" #include "ignite/transactions/transaction_consts.h" @@ -34,13 +33,26 @@ namespace ignite namespace transactions { /** - * Transaction. + * %Ignite cache transaction. + * Cache transactions have a default 2PC (two-phase-commit) behavior. + * + * @see TransactionConcurrency and TransactionIsolation for details on + * the supported isolation levels and concurrency models. + * + * This class implemented as a reference to an implementation so copying + * of this class instance will only create another reference to the same + * underlying object. Underlying object released automatically once all + * the instances are destructed. */ class IGNITE_FRIEND_EXPORT Transaction { public: /** * Constructor. + * + * Internal method. Should not be used by user. + * + * @param impl Implementation. */ Transaction(common::concurrent::SharedPointer<impl::transactions::TransactionImpl> impl); @@ -66,36 +78,60 @@ namespace ignite /** * Commit the transaction. + * + * This method should only be used on the valid instance. + * + * @throw IgniteError class instance in case of failure. */ void Commit(); /** * Commit the transaction. * + * Properly sets error param in case of failure. + * + * This method should only be used on the valid instance. + * * @param err Error. */ void Commit(IgniteError& err); /** * Rollback the transaction. + * + * This method should only be used on the valid instance. + * + * @throw IgniteError class instance in case of failure. */ void Rollback(); /** * Rollback the transaction. * + * Properly sets error param in case of failure. + * + * This method should only be used on the valid instance. + * * @param err Error. */ void Rollback(IgniteError& err); /** * Close the transaction. + * + * This method should only be used on the valid instance. + * + * @throw IgniteError class instance in case of failure. */ void Close(); /** * Close the transaction. * + * Properly sets error param in case of failure. + * + * This method should only be used on the valid instance. + * * @param err Error. */ void Close(IgniteError& err); @@ -106,6 +142,10 @@ namespace ignite * After transaction have been marked as rollback-only it may * only be rolled back. Error occurs if such transaction is * being commited. + * + * This method should only be used on the valid instance. + * + * @throw IgniteError class instance in case of failure. */ void SetRollbackOnly(); @@ -116,6 +156,10 @@ namespace ignite * only be rolled back. Error occurs if such transaction is * being commited. * + * Properly sets error param in case of failure. + * + * This method should only be used on the valid instance. + * * @param err Error. */ void SetRollbackOnly(IgniteError& err); @@ -128,6 +172,8 @@ namespace ignite * being commited. * * @return True if the transaction is rollback-only. + * + * @throw IgniteError class instance in case of failure. */ bool IsRollbackOnly(); @@ -138,6 +184,10 @@ namespace ignite * only be rolled back. Error occurs if such transaction is * being commited. * + * Properly sets error param in case of failure. + * + * This method should only be used on the valid instance. + * * @param err Error. * @return True if the transaction is rollback-only. */ @@ -146,13 +196,21 @@ namespace ignite /** * Get current state. * + * This method should only be used on the valid instance. + * * @return Transaction state. + * + * @throw IgniteError class instance in case of failure. */ TransactionState GetState(); /** * Get current state. * + * Properly sets error param in case of failure. + * + * This method should only be used on the valid instance. + * * @param err Error. * @return Transaction state. */ @@ -161,6 +219,8 @@ namespace ignite /** * Get concurrency. * + * This method should only be used on the valid instance. + * * @return Concurrency. */ TransactionConcurrency GetConcurrency() const @@ -171,6 +231,8 @@ namespace ignite /** * Get isolation. * + * This method should only be used on the valid instance. + * * @return Isolation. */ TransactionIsolation GetIsolation() const @@ -181,6 +243,8 @@ namespace ignite /** * Get timeout. * + * This method should only be used on the valid instance. + * * @return Timeout in milliseconds. Zero if timeout is infinite. */ int64_t GetTimeout() const
http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/transactions/transaction_consts.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/transactions/transaction_consts.h b/modules/platforms/cpp/core/include/ignite/transactions/transaction_consts.h index 5799b9f..8b25d3a 100644 --- a/modules/platforms/cpp/core/include/ignite/transactions/transaction_consts.h +++ b/modules/platforms/cpp/core/include/ignite/transactions/transaction_consts.h @@ -17,7 +17,7 @@ /** * @file - * Declares ignite::transactions::TransactionState enumeration. + * Declares Transaction-related enumerations. */ #ifndef _IGNITE_TRANSACTIONS_TRANSACTION_CONSTS @@ -28,14 +28,37 @@ namespace ignite namespace transactions { /** - * Transaction concurrency control. + * Transaction concurrency control model. */ enum TransactionConcurrency { - /** Optimistic concurrency control. */ + /** + * Optimistic concurrency model. In this mode all cache operations + * are not distributed to other nodes until Transaction::Commit() + * is called. In this mode one @c 'PREPARE' message will be sent to + * participating cache nodes to start acquiring per-transaction + * locks, and once all nodes reply @c 'OK', a one-way @c 'COMMIT' + * message is sent without waiting for reply. + * + * Note that in this mode, optimistic failures are only possible in + * conjunction with ::IGNITE_TX_ISOLATION_SERIALIZABLE isolation + * level. In all other cases, optimistic transactions will never + * fail optimistically and will always be identically ordered on all + * participating grid nodes. + */ IGNITE_TX_CONCURRENCY_OPTIMISTIC = 0, - /** Pessimistic concurrency control. */ + /** + * Pessimistic concurrency model. In this mode a lock is acquired + * on all cache operations with exception of read operations in + * ::IGNITE_TX_ISOLATION_READ_COMMITTED mode. All optional filters + * passed into cache operations will be evaluated after successful + * lock acquisition. Whenever Transaction::Commit() is called, a + * single one-way @c 'COMMIT' message is sent to participating cache + * nodes without waiting for reply. Note that there is no reason for + * distributed @c 'PREPARE' step, as all locks have been already + * acquired. + */ IGNITE_TX_CONCURRENCY_PESSIMISTIC = 1 }; @@ -44,13 +67,42 @@ namespace ignite */ enum TransactionIsolation { - /** Read committed isolation level. */ + /** + * Read committed isolation level. This isolation level means that + * always a committed value will be provided for read operations. + * With this isolation level values are always read from cache + * global memory or persistent store every time a value is accessed. + * In other words, if the same key is accessed more than once within + * the same transaction, it may have different value every time + * since global cache memory may be updated concurrently by other + * threads. + */ IGNITE_TX_ISOLATION_READ_COMMITTED = 0, - /** Repeatable read isolation level. */ + /** + * Repeatable read isolation level. This isolation level means that + * if a value was read once within transaction, then all consecutive + * reads will provide the same in-transaction value. With this + * isolation level accessed values are stored within in-transaction + * memory, so consecutive access to the same key within the same + * transaction will always return the value that was previously read + * or updated within this transaction. If concurrency is + * ::IGNITE_TX_CONCURRENCY_PESSIMISTIC, then a lock on the key will + * be acquired prior to accessing the value. + */ IGNITE_TX_ISOLATION_REPEATABLE_READ = 1, - /** Serializable isolation level. */ + /** + * Serializable isolation level. This isolation level means that all + * transactions occur in a completely isolated fashion, as if all + * transactions in the system had executed serially, one after the + * other. Read access with this level happens the same way as with + * ::IGNITE_TX_ISOLATION_REPEATABLE_READ level. However, in + * ::IGNITE_TX_CONCURRENCY_OPTIMISTIC mode, if some transactions + * cannot be serially isolated from each other, then one winner will + * be picked and the other transactions in conflict will result in + * IgniteError being thrown. + */ IGNITE_TX_ISOLATION_SERIALIZABLE = 2 }; @@ -59,31 +111,31 @@ namespace ignite */ enum TransactionState { - /** Transaction started. */ + /** %Transaction started. */ IGNITE_TX_STATE_ACTIVE, - /** Transaction validating. */ + /** %Transaction validating. */ IGNITE_TX_STATE_PREPARING, - /** Transaction validation succeeded. */ + /** %Transaction validation succeeded. */ IGNITE_TX_STATE_PREPARED, - /** Transaction is marked for rollback. */ + /** %Transaction is marked for rollback. */ IGNITE_TX_STATE_MARKED_ROLLBACK, - /** Transaction commit started (validating finished). */ + /** %Transaction commit started (validating finished). */ IGNITE_TX_STATE_COMMITTING, - /** Transaction commit succeeded. */ + /** %Transaction commit succeeded. */ IGNITE_TX_STATE_COMMITTED, - /** Transaction rollback started (validation failed). */ + /** %Transaction rollback started (validation failed). */ IGNITE_TX_STATE_ROLLING_BACK, - /** Transaction rollback succeeded. */ + /** %Transaction rollback succeeded. */ IGNITE_TX_STATE_ROLLED_BACK, - /** Transaction rollback failed or is otherwise unknown state. */ + /** %Transaction rollback failed or is otherwise unknown state. */ IGNITE_TX_STATE_UNKNOWN }; } http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/transactions/transaction_metrics.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/transactions/transaction_metrics.h b/modules/platforms/cpp/core/include/ignite/transactions/transaction_metrics.h index 4986a64..00ebd10 100644 --- a/modules/platforms/cpp/core/include/ignite/transactions/transaction_metrics.h +++ b/modules/platforms/cpp/core/include/ignite/transactions/transaction_metrics.h @@ -32,13 +32,15 @@ namespace ignite namespace transactions { /** - * Transaction metrics. + * %Transaction metrics, shared across all caches. */ class IGNITE_IMPORT_EXPORT TransactionMetrics { public: /** * Default constructor. + * + * Constructed instance is not valid. */ TransactionMetrics() : valid(false), @@ -71,6 +73,8 @@ namespace ignite /** * Copy constructor. + * + * @param other Another instance. */ TransactionMetrics(const TransactionMetrics& other) : valid(other.valid), @@ -84,6 +88,9 @@ namespace ignite /** * Assignment operator. + * + * @param other Another instance. + * @return @c *this. */ TransactionMetrics& operator=(const TransactionMetrics& other) { @@ -105,7 +112,7 @@ namespace ignite { return commitTime; } - + /** * Get rollback time. * @@ -145,7 +152,7 @@ namespace ignite * in case of error. Invalid instances also often can be * created using default constructor. * - * @return True if the instance contains valid data. + * @return @c true if the instance contains valid data. */ bool IsValid() const { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/transactions/transactions.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/transactions/transactions.h b/modules/platforms/cpp/core/include/ignite/transactions/transactions.h index 130116a..98282bd 100644 --- a/modules/platforms/cpp/core/include/ignite/transactions/transactions.h +++ b/modules/platforms/cpp/core/include/ignite/transactions/transactions.h @@ -35,13 +35,22 @@ namespace ignite namespace transactions { /** - * Transactions. + * %Transactions facade. + * + * This class implemented as a reference to an implementation so copying + * of this class instance will only create another reference to the same + * underlying object. Underlying object released automatically once all + * the instances are destructed. */ class IGNITE_FRIEND_EXPORT Transactions { public: /** * Constructor. + * + * Internal method. Should not be used by user. + * + * @param impl Implementation. */ Transactions(ignite::common::concurrent::SharedPointer<impl::transactions::TransactionsImpl> impl); @@ -75,14 +84,16 @@ namespace ignite Transaction GetTx(); /** - * Start new transaction. + * Start new transaction with default isolation, concurrency + * and timeout. * * @return New transaction instance. */ Transaction TxStart(); /** - * Start new transaction. + * Start new transaction with default isolation, concurrency + * and timeout. * * @param err Error. * @return New transaction instance. @@ -90,7 +101,8 @@ namespace ignite Transaction TxStart(IgniteError& err); /** - * Start new transaction. + * Starts new transaction with the specified concurrency and + * isolation. * * @param concurrency Concurrency. * @param isolation Isolation. @@ -100,7 +112,8 @@ namespace ignite TransactionIsolation isolation); /** - * Start new transaction. + * Starts new transaction with the specified concurrency and + * isolation. * * @param concurrency Concurrency. * @param isolation Isolation. @@ -111,12 +124,14 @@ namespace ignite TransactionIsolation isolation, IgniteError& err); /** - * Start new transaction. + * Starts transaction with specified isolation, concurrency, + * timeout, and number of participating entries. * * @param concurrency Concurrency. * @param isolation Isolation. * @param timeout Timeout. Zero if for infinite timeout. - * @param txSize Number of entries participating in transaction (may be approximate). + * @param txSize Number of entries participating in transaction + * (may be approximate). * @return New transaction instance. */ Transaction TxStart(TransactionConcurrency concurrency, @@ -129,7 +144,8 @@ namespace ignite * @param concurrency Concurrency. * @param isolation Isolation. * @param timeout Timeout. Zero if for infinite timeout. - * @param txSize Number of entries participating in transaction (may be approximate). + * @param txSize Number of entries participating in transaction + * (may be approximate). * @param err Error. * @return New transaction instance. */ @@ -138,14 +154,14 @@ namespace ignite int32_t txSize, IgniteError& err); /** - * Get metrics. + * Get transaction metrics. * * @return Metrics instance. */ TransactionMetrics GetMetrics(); /** - * Get metrics. + * Get transaction metrics. * * @param err Error. * @return Metrics instance. http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/namespaces.dox ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/namespaces.dox b/modules/platforms/cpp/core/namespaces.dox index 20aa5ba..0f5f11f 100644 --- a/modules/platforms/cpp/core/namespaces.dox +++ b/modules/platforms/cpp/core/namespaces.dox @@ -37,7 +37,7 @@ } /** - * %Ignite Transaction API. + * %Ignite %Transaction API. */ namespace transactions { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/cpp.dxg ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/cpp.dxg b/modules/platforms/cpp/cpp.dxg index 605a613..d25d978 100644 --- a/modules/platforms/cpp/cpp.dxg +++ b/modules/platforms/cpp/cpp.dxg @@ -1715,8 +1715,8 @@ GENERATE_LEGEND = YES DOT_CLEANUP = YES -;INPUT=core binary -;EXCLUDE=core/include/ignite/impl core/os/linux/include/ignite/impl core/os/linux/src/impl core/os/win/include/ignite/impl core/os/win/src/impl core/src/impl binary/include/ignite/impl binary/src/impl +;INPUT=core binary common +;EXCLUDE=core/include/ignite/impl core/os/linux/include/ignite/impl core/os/linux/src/impl core/os/win/include/ignite/impl core/os/win/src/impl core/src/impl binary/include/ignite/impl binary/src/impl common/include/ignite/common common/os ;STRIP_FROM_PATH=core/include/ignite core/src binary/include/ignite binary/src ;OUTPUT_DIRECTORY=../../clients/target/cppdoc ;PROJECT_LOGO=../../../assembly/docfiles/ignite_logo.png
