ignite-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From voze...@apache.org
Subject [1/2] ignite git commit: IGNITE-3113: CPP: Binary containers documentation.
Date Thu, 23 Jun 2016 12:42:26 GMT
Repository: ignite
Updated Branches:
  refs/heads/ignite-1.6 76d7533a4 -> c0adcc231


http://git-wip-us.apache.org/repos/asf/ignite/blob/c0adcc23/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/c0adcc23/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/c0adcc23/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/c0adcc23/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/c0adcc23/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/c0adcc23/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


Mime
View raw message