You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ak...@apache.org on 2016/06/27 03:22:50 UTC
[06/22] ignite git commit: IGNITE-3113: CPP: Binary containers
documentation. This closes #711.
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