From 5bbe06be8f46526019a68de9d04ae1784749fc94 Mon Sep 17 00:00:00 2001 From: isapego Date: Wed, 11 May 2016 19:57:47 +0300 Subject: [PATCH 1/3] IGNITE-3113: Binary containers documentation. --- .../include/ignite/binary/binary_containers.h | 191 ++++++++++++++---- modules/platforms/cpp/core/namespaces.dox | 2 +- modules/platforms/cpp/cpp.dxg | 4 +- 3 files changed, 158 insertions(+), 39 deletions(-) diff --git a/modules/platforms/cpp/binary/include/ignite/binary/binary_containers.h b/modules/platforms/cpp/binary/include/ignite/binary/binary_containers.h index 946101c684eba..8f2641612e3c7 100644 --- a/modules/platforms/cpp/binary/include/ignite/binary/binary_containers.h +++ b/modules/platforms/cpp/binary/include/ignite/binary/binary_containers.h @@ -37,37 +37,51 @@ namespace ignite { /** * Binary string array writer. + * + * Can be used to write array of strings one by one. + * + * Use Write() method to write array string by string, then finilize + * the writing by calling Close() method. Once the Close() method have + * been called, instance is not usable and will throw an IgniteError + * on any subsequent attempt to use it. */ class IGNITE_IMPORT_EXPORT BinaryStringArrayWriter { public: /** * Constructor. - * + * Internal call. Should not be used by user. + * + * @param impl Writer implementation. * @param id Identifier. - * @param impl Writer. */ BinaryStringArrayWriter(impl::binary::BinaryWriterImpl* impl, int32_t id); /** - * Write string. + * Write null-terminated string. + * + * @param val Null-terminated character sequence to write. * - * @param val Null-terminated character sequence. + * @throw IgniteError if the writer instance is closed already. */ void Write(const char* val); /** * Write string. * - * @param val String. - * @param len String length (characters). + * @param val String to write. + * @param len String length in bytes. + * + * @throw IgniteError if the writer instance is closed already. */ void Write(const char* val, int32_t len); /** * Write string. * - * @param val String. + * @param val String to write. + * + * @throw IgniteError if the writer instance is closed already. */ void Write(const std::string& val) { @@ -76,18 +90,32 @@ namespace ignite /** * Close the writer. + * + * This method should be called to finilize writing + * of the array. + * + * @throw IgniteError if the writer instance is closed already. */ void Close(); + private: /** Implementation delegate. */ impl::binary::BinaryWriterImpl* impl; - /** Idnetifier. */ + /** Identifier. */ const int32_t id; }; /** - * Binary collection writer. + * Binary array writer. + * + * Can be used to write array of values of the specific type one by + * one. + * + * Use Write() method to write array value by value, then finilize + * the writing by calling Close() method. Once the Close() method have + * been called, instance is not usable and will throw an IgniteError + * on any subsequent attempt to use it. */ template class IGNITE_IMPORT_EXPORT BinaryArrayWriter @@ -95,11 +123,13 @@ namespace ignite public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Writer. + * @param impl Writer implementation. * @param id Identifier. */ - BinaryArrayWriter(impl::binary::BinaryWriterImpl* impl, int32_t id) : impl(impl), id(id) + BinaryArrayWriter(impl::binary::BinaryWriterImpl* impl, int32_t id) : + impl(impl), id(id) { // No-op. } @@ -107,7 +137,9 @@ namespace ignite /** * Write a value. * - * @param val Value. + * @param val Value to write. + * + * @throw IgniteError if the writer instance is closed already. */ void Write(const T& val) { @@ -116,11 +148,17 @@ namespace ignite /** * Close the writer. + * + * This method should be called to finilize writing + * of the array. + * + * @throw IgniteError if the writer instance is closed already. */ void Close() { impl->CommitContainer(id); } + private: /** Implementation delegate. */ impl::binary::BinaryWriterImpl* impl; @@ -131,6 +169,14 @@ namespace ignite /** * Binary collection writer. + * + * Can be used to write collection of values of the specific type one by + * one. + * + * Use Write() method to write collection value by value, then finilize + * the writing by calling Close() method. Once the Close() method have + * been called, instance is not usable and will throw an IgniteError + * on any subsequent attempt to use it. */ template class IGNITE_IMPORT_EXPORT BinaryCollectionWriter @@ -138,11 +184,13 @@ namespace ignite public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Writer. + * @param impl Writer implementation. * @param id Identifier. */ - BinaryCollectionWriter(impl::binary::BinaryWriterImpl* impl, int32_t id) : impl(impl), id(id) + BinaryCollectionWriter(impl::binary::BinaryWriterImpl* impl, int32_t id) : + impl(impl), id(id) { // No-op. } @@ -150,7 +198,9 @@ namespace ignite /** * Write a value. * - * @param val Value. + * @param val Value to write. + * + * @throw IgniteError if the writer instance is closed already. */ void Write(const T& val) { @@ -159,6 +209,11 @@ namespace ignite /** * Close the writer. + * + * This method should be called to finilize writing + * of the collection. + * + * @throw IgniteError if the writer instance is closed already. */ void Close() { @@ -174,6 +229,13 @@ namespace ignite /** * Binary map writer. + * + * Can be used to write map element by element. + * + * Use Write() method to write map value by value, then finilize + * the writing by calling Close() method. Once the Close() method have + * been called, instance is not usable and will throw an IgniteError + * on any subsequent attempt to use it. */ template class IGNITE_IMPORT_EXPORT BinaryMapWriter @@ -181,19 +243,24 @@ namespace ignite public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Writer. + * @param impl Writer implementation. + * @param id Identifier. */ - BinaryMapWriter(impl::binary::BinaryWriterImpl* impl, int32_t id) : impl(impl), id(id) + BinaryMapWriter(impl::binary::BinaryWriterImpl* impl, int32_t id) : + impl(impl), id(id) { // No-op. } /** - * Write a value. + * Write a map entry. + * + * @param key Key element of the map entry. + * @param val Value element of the map entry. * - * @param key Key. - * @param val Value. + * @throw IgniteError if the writer instance is closed already. */ void Write(const K& key, const V& val) { @@ -202,6 +269,10 @@ namespace ignite /** * Close the writer. + * + * This method should be called to finilize writing of the map. + * + * @throw IgniteError if the writer instance is closed already. */ void Close() { @@ -217,14 +288,20 @@ namespace ignite /** * Binary string array reader. + * + * Can be used to read array of strings string by string. + * + * Use GetNext() method to read array value by value while HasNext() + * method returns true. */ class IGNITE_IMPORT_EXPORT BinaryStringArrayReader { public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Reader. + * @param impl Reader implementation. * @param id Identifier. * @param size Array size. */ @@ -240,20 +317,24 @@ namespace ignite /** * Get next element. * - * @param res Array to store data to. + * @param res Buffer to store data to. * @param len Expected length of string. NULL terminator will be set in case len is * greater than real string length. * @return Actual amount of elements read. If "len" argument is less than actual * array size or resulting array is set to null, nothing will be written * to resulting array and returned value will contain required array length. * -1 will be returned in case array in stream was null. + * + * @throw IgniteError if there is no element to read. */ int32_t GetNext(char* res, int32_t len); /** * Get next element. * - * @return String. + * @return String. + * + * @throw IgniteError if there is no element to read. */ std::string GetNext() { @@ -279,22 +360,30 @@ namespace ignite int32_t GetSize() const; /** - * Whether array is NULL. + * Check whether array is NULL. + * + * @return True if the array is NULL. */ bool IsNull() const; + private: /** Implementation delegate. */ impl::binary::BinaryReaderImpl* impl; /** Identifier. */ - const int32_t id; + const int32_t id; /** Size. */ - const int32_t size; + const int32_t size; }; /** * Binary array reader. + * + * Can be used to read array of values of the specific type one by one. + * + * Use GetNext() method to read array value by value while HasNext() + * method returns true. */ template class BinaryArrayReader @@ -302,8 +391,9 @@ namespace ignite public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Reader. + * @param impl Reader implementation. * @param id Identifier. * @param size Array size. */ @@ -327,6 +417,8 @@ namespace ignite * Read next element. * * @return Next element. + * + * @throw IgniteError if there is no element to read. */ T GetNext() { @@ -344,7 +436,9 @@ namespace ignite } /** - * Whether array is NULL. + * Check whether array is NULL. + * + * @return True if the array is NULL. */ bool IsNull() { @@ -363,6 +457,12 @@ namespace ignite /** * Binary collection reader. + * + * Can be used to read collection of values of the specific type + * one by one. + * + * Use GetNext() method to read array value by value while HasNext() + * method returns true. */ template class BinaryCollectionReader @@ -370,8 +470,9 @@ namespace ignite public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Reader. + * @param impl Reader implementation. * @param id Identifier. * @param type Collection type. * @param size Collection size. @@ -396,6 +497,8 @@ namespace ignite * Read next element. * * @return Next element. + * + * @throw IgniteError if there is no element to read. */ T GetNext() { @@ -405,7 +508,8 @@ namespace ignite /** * Get collection type. * - * @return Type. + * @return Collection type. See CollectionType for the list of + * available values and their description. */ CollectionType GetType() { @@ -423,7 +527,9 @@ namespace ignite } /** - * Whether collection is NULL. + * Check whether collection is NULL. + * + * @return True if the collection is NULL. */ bool IsNull() { @@ -445,6 +551,11 @@ namespace ignite /** * Binary map reader. + * + * Can be used to read map entry by entry. + * + * Use GetNext() method to read array value by value while HasNext() + * method returns true. */ template class BinaryMapReader @@ -452,8 +563,9 @@ namespace ignite public: /** * Constructor. + * Internal call. Should not be used by user. * - * @param impl Reader. + * @param impl Reader implementation. * @param id Identifier. * @param type Map type. * @param size Map size. @@ -477,8 +589,12 @@ namespace ignite /** * Read next element. * - * @param key Key. - * @param val Value. + * @param key Pointer to buffer where key element should be stored. + * Should not be null. + * @param val Pointer to buffer where value element should be + * stored. Should not be null. + * + * @throw IgniteError if there is no element to read. */ void GetNext(K* key, V* val) { @@ -488,7 +604,8 @@ namespace ignite /** * Get map type. * - * @return Type. + * @return Map type. See MapType for the list of available values + * and their description. */ MapType GetType() { @@ -506,7 +623,9 @@ namespace ignite } /** - * Whether map is NULL. + * Check whether map is NULL. + * + * @return True if the map is NULL. */ bool IsNull() { diff --git a/modules/platforms/cpp/core/namespaces.dox b/modules/platforms/cpp/core/namespaces.dox index 20aa5baefcb55..0f5f11fe20568 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 { diff --git a/modules/platforms/cpp/cpp.dxg b/modules/platforms/cpp/cpp.dxg index 605a613649113..d25d9781c5f0e 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 From 12e4e285d82f572a0d850dd51b4db01b15434850 Mon Sep 17 00:00:00 2001 From: isapego Date: Wed, 11 May 2016 21:18:41 +0300 Subject: [PATCH 2/3] IGNITE-3113: Some fixes for documentation. --- .../include/ignite/binary/binary_raw_reader.h | 12 +++---- .../cpp/common/include/ignite/ignite_error.h | 19 ++++++----- .../platforms/cpp/common/src/ignite_error.cpp | 12 +++---- .../cpp/core/include/ignite/cache/cache.h | 11 +++++-- .../core/include/ignite/cache/cache_entry.h | 12 +++---- .../ignite/cache/query/query_argument.h | 33 ++++++++++--------- .../include/ignite/cache/query/query_cursor.h | 12 ++++--- .../ignite/cache/query/query_fields_cursor.h | 6 ++-- .../ignite/cache/query/query_fields_row.h | 17 +++++++--- .../include/ignite/cache/query/query_scan.h | 10 +++--- .../include/ignite/cache/query/query_sql.h | 15 ++++++--- .../ignite/cache/query/query_sql_fields.h | 15 ++++++--- 12 files changed, 103 insertions(+), 71 deletions(-) diff --git a/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h b/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h index 473be3de39037..b2c27bd335046 100644 --- a/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h +++ b/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h @@ -205,14 +205,14 @@ namespace ignite int32_t ReadDoubleArray(double* res, int32_t len); /** - * Read Guid. Maps to "UUID" type in Java. + * Read Guid. Maps to "java.util.UUID" type in Java. * * @return Result. */ Guid ReadGuid(); /** - * Read array of Guids. Maps to "UUID[]" type in Java. + * Read array of Guids. Maps to "java.util.UUID[]" type in Java. * * @param res Array to store data to. * @param len Expected length of array. @@ -224,14 +224,14 @@ namespace ignite int32_t ReadGuidArray(Guid* res, int32_t len); /** - * Read Date. Maps to "Date" type in Java. + * Read Date. Maps to "java.util.Date" type in Java. * * @return Result. */ Date ReadDate(); /** - * Read array of Dates. Maps to "Date[]" type in Java. + * Read array of Dates. Maps to "java.util.Date[]" type in Java. * * @param res Array to store data to. * @param len Expected length of array. @@ -243,14 +243,14 @@ namespace ignite int32_t ReadDateArray(Date* res, int32_t len); /** - * Read Timestamp. Maps to "Timestamp" type in Java. + * Read Timestamp. Maps to "java.sql.Timestamp" type in Java. * * @return Result. */ Timestamp ReadTimestamp(); /** - * Read array of Timestamps. Maps to "Timestamp[]" type in Java. + * Read array of Timestamps. Maps to "java.sql.Timestamp[]" type in Java. * * @param res Array to store data to. * @param len Expected length of array. diff --git a/modules/platforms/cpp/common/include/ignite/ignite_error.h b/modules/platforms/cpp/common/include/ignite/ignite_error.h index edba67a7ec821..4c0e263113458 100644 --- a/modules/platforms/cpp/common/include/ignite/ignite_error.h +++ b/modules/platforms/cpp/common/include/ignite/ignite_error.h @@ -76,7 +76,7 @@ namespace ignite { namespace java { - /* Error constants. */ + /* JNI error constants. */ const int IGNITE_JNI_ERR_SUCCESS = 0; const int IGNITE_JNI_ERR_GENERIC = 1; const int IGNITE_JNI_ERR_JVM_INIT = 2; @@ -84,7 +84,7 @@ namespace ignite } /** - * Ignite error information. + * %Ignite error information. */ class IGNITE_IMPORT_EXPORT IgniteError : public std::exception { @@ -119,7 +119,7 @@ namespace ignite /** Binary error. */ static const int IGNITE_ERR_BINARY = 1002; - /** Generic Ignite error. */ + /** Generic %Ignite error. */ static const int IGNITE_ERR_GENERIC = 2000; /** Illegal argument passed. */ @@ -202,12 +202,13 @@ namespace ignite static void ThrowIfNeeded(IgniteError& err); /** - * Create empty error. + * Default constructor. + * Creates empty error. Code is IGNITE_SUCCESS and message is NULL. */ IgniteError(); /** - * Create error with specific code. + * Create error with specific code. Message is set to NULL. * * @param code Error code. */ @@ -232,7 +233,7 @@ namespace ignite * Assignment operator. * * @param other Other instance. - * @return Assignment result. + * @return *this. */ IgniteError& operator=(const IgniteError& other); @@ -251,7 +252,7 @@ namespace ignite /** * Get error message. * - * @return Error message. + * @return Error message. Can be NULL. */ const char* GetText() const IGNITE_NO_THROW; @@ -264,12 +265,12 @@ namespace ignite virtual const char* what() const IGNITE_NO_THROW; /** - * Set error. + * Initializes IgniteError instance from the JNI error. * * @param jniCode Error code. * @param jniCls Error class. * @param jniMsg Error message. - * @param err Error. + * @param err Error. Can not be NULL. */ static void SetError(const int jniCode, const char* jniCls, const char* jniMsg, IgniteError* err); private: diff --git a/modules/platforms/cpp/common/src/ignite_error.cpp b/modules/platforms/cpp/common/src/ignite_error.cpp index 722214b9b8c37..5acbed2ce683f 100644 --- a/modules/platforms/cpp/common/src/ignite_error.cpp +++ b/modules/platforms/cpp/common/src/ignite_error.cpp @@ -14,6 +14,8 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +#include + #include #include @@ -61,14 +63,8 @@ namespace ignite { IgniteError tmp(other); - int tmpCode = code; - char* tmpMsg = msg; - - code = tmp.code; - msg = tmp.msg; - - tmp.code = tmpCode; - tmp.msg = tmpMsg; + std::swap(code, tmp.code); + std::swap(msg, tmp.msg); } return *this; diff --git a/modules/platforms/cpp/core/include/ignite/cache/cache.h b/modules/platforms/cpp/core/include/ignite/cache/cache.h index e60c843bba7b6..2beb66e1b7066 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/cache.h +++ b/modules/platforms/cpp/core/include/ignite/cache/cache.h @@ -46,6 +46,10 @@ namespace ignite { /** * Main entry point for all Data Grid APIs. + * + * Both key and value types should be default-constructable, + * copy-constructable and assignable. Also BinaryType class + * template should be specialized for both types. */ template class IGNITE_IMPORT_EXPORT Cache @@ -54,13 +58,16 @@ namespace ignite /** * Constructor. */ - Cache(impl::cache::CacheImpl* impl) : impl(ignite::common::concurrent::SharedPointer(impl)) + Cache(impl::cache::CacheImpl* impl) : + impl(impl) { // No-op. } /** - * Name of this cache (null for default cache). + * Get name of this cache (null for default cache). + * + * @return Name of this cache (null for default cache). */ const char* GetName() const { diff --git a/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h b/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h index f709650ac1aab..3d34c85c21fc6 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h +++ b/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h @@ -67,10 +67,10 @@ namespace ignite * * @param other Other instance. */ - CacheEntry(const CacheEntry& other) + CacheEntry(const CacheEntry& other) : + key(other.key), val(other.val) { - key = other.key; - val = other.val; + // No-op. } /** @@ -82,10 +82,8 @@ namespace ignite { if (this != &other) { - CacheEntry tmp(other); - - std::swap(key, tmp.key); - std::swap(val, tmp.val); + key = other.key; + val = other.val; } return *this; diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_argument.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_argument.h index 933bd603e3c85..65578cee3bac6 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_argument.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_argument.h @@ -27,11 +27,11 @@ #include "ignite/binary/binary_raw_writer.h" namespace ignite -{ +{ namespace cache { namespace query - { + { /** * Base class for all query arguments. */ @@ -49,18 +49,24 @@ namespace ignite /** * Copy argument. * - * @return Copy. + * @return Copy of this argument instance. */ virtual QueryArgumentBase* Copy() const = 0; /** - * Write argument. + * Write argument using provided writer. + * + * @param writer Writer to use to write this argument. */ virtual void Write(ignite::binary::BinaryRawWriter& writer) = 0; }; /** - * Query argument. + * Query argument class template. + * + * Template argument type should be copy-constructable and + * assignable. Also BinaryType class template should be specialized + * for this type. */ template class QueryArgument : public QueryArgumentBase @@ -71,7 +77,8 @@ namespace ignite * * @param val Value. */ - QueryArgument(const T& val) : val(val) + QueryArgument(const T& val) : + val(val) { // No-op. } @@ -81,26 +88,22 @@ namespace ignite * * @param other Other instance. */ - QueryArgument(const QueryArgument& other) + QueryArgument(const QueryArgument& other) : + val(other.val) { - val = other.val; + // No-op. } /** * Assignment operator. * * @param other Other instance. + * @return *this. */ QueryArgument& operator=(const QueryArgument& other) { if (this != &other) - { - QueryArgument tmp(other); - - T val0 = val; - val = tmp.val; - tmp.val = val0; - } + val = other.val; return *this; } diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h index 45eb54af151e9..c17c6b7da3d42 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h @@ -42,7 +42,8 @@ namespace ignite * Query cursor class template. * * Both key and value types should be default-constructable, - * copy-constructable and assignable. + * copy-constructable and assignable. Also BinaryType class + * template should be specialized for both types. */ template class QueryCursor @@ -73,11 +74,12 @@ namespace ignite /** * Check whether next entry exists. - * Throws IgniteError class instance in case of failure. * * This method should only be used on the valid instance. * * @return True if next entry exists. + * + * @throw IgniteError class instance in case of failure. */ bool HasNext() { @@ -117,11 +119,12 @@ namespace ignite /** * Get next entry. - * Throws IgniteError class instance in case of failure. * * This method should only be used on the valid instance. * * @return Next entry. + * + * @throw IgniteError class instance in case of failure. */ CacheEntry GetNext() { @@ -175,11 +178,12 @@ namespace ignite /** * Get all entries. - * Throws IgniteError class instance in case of failure. * * This method should only be used on the valid instance. * * @param Vector where query entries will be stored. + * + * @throw IgniteError class instance in case of failure. */ void GetAll(std::vector>& res) { diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h index 3952ece2157ef..2d057d69c0fb8 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h @@ -70,11 +70,12 @@ namespace ignite /** * Check whether next entry exists. - * Throws IgniteError class instance in case of failure. * * This method should only be used on the valid instance. * * @return True if next entry exists. + * + * @throw IgniteError class instance in case of failure. */ bool HasNext() { @@ -114,11 +115,12 @@ namespace ignite /** * Get next entry. - * Throws IgniteError class instance in case of failure. * * This method should only be used on the valid instance. * * @return Next entry. + * + * @throw IgniteError class instance in case of failure. */ QueryFieldsRow GetNext() { diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h index 521da762e164b..7b665b8781371 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h @@ -47,8 +47,7 @@ namespace ignite /** * Default constructor. * - * Constructed instance is not valid and thus can not be used - * as a cursor. + * Constructed instance is not valid and thus can not be used. */ QueryFieldsRow() : impl(0) { @@ -69,11 +68,12 @@ namespace ignite /** * Check whether next entry exists. - * Throws IgniteError class instance in case of failure. * * This method should only be used on the valid instance. * * @return True if next entry exists. + * + * @throw IgniteError class instance in case of failure. */ bool HasNext() { @@ -113,11 +113,16 @@ namespace ignite /** * Get next entry. - * Throws IgniteError class instance in case of failure. + * + * Template argument type should be default-constructable, + * copy-constructable and assignable. Also BinaryType class + * template should be specialized for this type. * * This method should only be used on the valid instance. * * @return Next entry. + * + * @throw IgniteError class instance in case of failure. */ template T GetNext() @@ -135,6 +140,10 @@ namespace ignite * Get next entry. * Properly sets error param in case of failure. * + * Template argument type should be default-constructable, + * copy-constructable and assignable. Also BinaryType class + * template should be specialized for this type. + * * This method should only be used on the valid instance. * * @param err Used to set operation result. diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_scan.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_scan.h index d4dd565d954de..4228ba5bc3ebd 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_scan.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_scan.h @@ -29,11 +29,11 @@ #include "ignite/binary/binary_raw_writer.h" namespace ignite -{ +{ namespace cache { namespace query - { + { /** * Scan query. */ @@ -47,7 +47,7 @@ namespace ignite { // No-op. } - + /** * Constructor. * @@ -57,7 +57,7 @@ namespace ignite { // No-op. } - + /** * Get partition to scan. * @@ -117,7 +117,7 @@ namespace ignite { this->loc = loc; } - + /** * Write query info to the stream. * diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_sql.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_sql.h index d80fa51f004af..f7a00faa50189 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_sql.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_sql.h @@ -31,11 +31,11 @@ #include "ignite/binary/binary_raw_writer.h" namespace ignite -{ +{ namespace cache { namespace query - { + { /** * Sql query. */ @@ -48,8 +48,8 @@ namespace ignite * @param type Type name. * @param sql SQL string. */ - SqlQuery(const std::string& type, const std::string& sql) : type(type), sql(sql), pageSize(1024), - loc(false), args() + SqlQuery(const std::string& type, const std::string& sql) + : type(type), sql(sql), pageSize(1024), loc(false), args() { // No-op. } @@ -59,7 +59,8 @@ namespace ignite * * @param other Other instance. */ - SqlQuery(const SqlQuery& other) : type(other.type), sql(other.sql), pageSize(other.pageSize), + SqlQuery(const SqlQuery& other) : + type(other.type), sql(other.sql), pageSize(other.pageSize), loc(other.loc), args() { args.reserve(other.args.size()); @@ -199,6 +200,10 @@ namespace ignite /** * Add argument. * + * Template argument type should be copy-constructable and + * assignable. Also BinaryType class template should be specialized + * for this type. + * * @param arg Argument. */ template diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_sql_fields.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_sql_fields.h index 4792d34e12922..e21fc9381ada3 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_sql_fields.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_sql_fields.h @@ -47,7 +47,8 @@ namespace ignite * * @param sql SQL string. */ - SqlFieldsQuery(const std::string& sql) : sql(sql), pageSize(1024), loc(false), args() + SqlFieldsQuery(const std::string& sql) : + sql(sql), pageSize(1024), loc(false), args() { // No-op. } @@ -58,7 +59,8 @@ namespace ignite * @param sql SQL string. * @param loc Whether query should be executed locally. */ - SqlFieldsQuery(const std::string& sql, bool loc) : sql(sql), pageSize(1024), loc(false), args() + SqlFieldsQuery(const std::string& sql, bool loc) : + sql(sql), pageSize(1024), loc(false), args() { // No-op. } @@ -68,7 +70,8 @@ namespace ignite * * @param other Other instance. */ - SqlFieldsQuery(const SqlFieldsQuery& other) : sql(other.sql), pageSize(other.pageSize), loc(other.loc), + SqlFieldsQuery(const SqlFieldsQuery& other) : + sql(other.sql), pageSize(other.pageSize), loc(other.loc), args() { args.reserve(other.args.size()); @@ -106,7 +109,7 @@ namespace ignite for (std::vector::iterator it = args.begin(); it != args.end(); ++it) delete *it; } - + /** * Get SQL string. * @@ -170,6 +173,10 @@ namespace ignite /** * Add argument. * + * Template argument type should be copy-constructable and + * assignable. Also BinaryType class template should be specialized + * for this type. + * * @param arg Argument. */ template From ebd4202caa22f8a277d5c029231de5894f3c1f2e Mon Sep 17 00:00:00 2001 From: isapego Date: Thu, 12 May 2016 16:17:32 +0300 Subject: [PATCH 3/3] IGNITE-3113: Further documentation fixes. --- .../include/ignite/binary/binary_raw_reader.h | 13 ++ .../include/ignite/binary/binary_raw_writer.h | 13 ++ .../include/ignite/binary/binary_reader.h | 13 ++ .../include/ignite/binary/binary_writer.h | 13 ++ .../cpp/common/include/ignite/date.h | 2 +- .../cpp/common/include/ignite/timestamp.h | 2 +- .../cpp/core/include/ignite/cache/cache.h | 175 ++++++++++++++++-- .../core/include/ignite/cache/cache_entry.h | 2 +- .../include/ignite/cache/query/query_cursor.h | 5 + .../ignite/cache/query/query_fields_cursor.h | 5 + .../ignite/cache/query/query_fields_row.h | 5 + .../cpp/core/include/ignite/ignite.h | 21 ++- .../include/ignite/ignite_configuration.h | 4 +- .../cpp/core/include/ignite/ignition.h | 2 +- .../include/ignite/transactions/transaction.h | 68 ++++++- .../ignite/transactions/transaction_consts.h | 84 +++++++-- .../ignite/transactions/transaction_metrics.h | 13 +- .../ignite/transactions/transactions.h | 36 +++- 18 files changed, 426 insertions(+), 50 deletions(-) diff --git a/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h b/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h index b2c27bd335046..31044374f770a 100644 --- a/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h +++ b/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h @@ -41,6 +41,17 @@ namespace ignite { /** * Binary raw reader. + * + * 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. + * + * @note User should not store copy of this instance as it can be + * invalidated as soon as the initially passed to user instance has + * been destructed. For example this means that if user received an + * instance of this class as a function argument then he should not + * store and use copy of this class out of the scope of this + * function. */ class IGNITE_IMPORT_EXPORT BinaryRawReader { @@ -48,6 +59,8 @@ namespace ignite /** * Constructor. * + * Internal method. Should not be used by user. + * * @param impl Implementation. */ BinaryRawReader(ignite::impl::binary::BinaryReaderImpl* impl); diff --git a/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_writer.h b/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_writer.h index 41cfef7688ab8..c96040634805b 100644 --- a/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_writer.h +++ b/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_writer.h @@ -40,6 +40,17 @@ namespace ignite { /** * Binary raw writer. + * + * 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. + * + * @note User should not store copy of this instance as it can be + * invalidated as soon as the initially passed to user instance has + * been destructed. For example this means that if user received an + * instance of this class as a function argument then he should not + * store and use copy of this class out of the scope of this + * function. */ class IGNITE_IMPORT_EXPORT BinaryRawWriter { @@ -47,6 +58,8 @@ namespace ignite /** * Constructor. * + * Internal method. Should not be used by user. + * * @param impl Implementation. */ BinaryRawWriter(ignite::impl::binary::BinaryWriterImpl* impl); diff --git a/modules/platforms/cpp/binary/include/ignite/binary/binary_reader.h b/modules/platforms/cpp/binary/include/ignite/binary/binary_reader.h index 3e5bbb18e43bc..ac70f39bd83d9 100644 --- a/modules/platforms/cpp/binary/include/ignite/binary/binary_reader.h +++ b/modules/platforms/cpp/binary/include/ignite/binary/binary_reader.h @@ -39,6 +39,17 @@ namespace ignite { /** * Binary reader. + * + * 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. + * + * @note User should not store copy of this instance as it can be + * invalidated as soon as the initially passed to user instance has + * been destructed. For example this means that if user received an + * instance of this class as a function argument then he should not + * store and use copy of this class out of the scope of this + * function. */ class IGNITE_IMPORT_EXPORT BinaryReader { @@ -46,6 +57,8 @@ namespace ignite /** * Constructor. * + * Internal method. Should not be used by user. + * * @param impl Implementation. */ BinaryReader(ignite::impl::binary::BinaryReaderImpl* impl); diff --git a/modules/platforms/cpp/binary/include/ignite/binary/binary_writer.h b/modules/platforms/cpp/binary/include/ignite/binary/binary_writer.h index 1bee82ace0423..1923694959498 100644 --- a/modules/platforms/cpp/binary/include/ignite/binary/binary_writer.h +++ b/modules/platforms/cpp/binary/include/ignite/binary/binary_writer.h @@ -36,6 +36,17 @@ namespace ignite { /** * Binary writer. + * + * 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. + * + * @note User should not store copy of this instance as it can be + * invalidated as soon as the initially passed to user instance has + * been destructed. For example this means that if user received an + * instance of this class as a function argument then he should not + * store and use copy of this class out of the scope of this + * function. */ class IGNITE_IMPORT_EXPORT BinaryWriter { @@ -43,6 +54,8 @@ namespace ignite /** * Constructor. * + * Internal method. Should not be used by user. + * * @param impl Implementation. */ BinaryWriter(ignite::impl::binary::BinaryWriterImpl* impl); diff --git a/modules/platforms/cpp/common/include/ignite/date.h b/modules/platforms/cpp/common/include/ignite/date.h index 31fe5d02566a7..ffdebd30e605a 100644 --- a/modules/platforms/cpp/common/include/ignite/date.h +++ b/modules/platforms/cpp/common/include/ignite/date.h @@ -30,7 +30,7 @@ namespace ignite { /** - * Date type. + * %Date type. */ class IGNITE_IMPORT_EXPORT Date { diff --git a/modules/platforms/cpp/common/include/ignite/timestamp.h b/modules/platforms/cpp/common/include/ignite/timestamp.h index 4528e536e5fa2..14b83fa2acfde 100644 --- a/modules/platforms/cpp/common/include/ignite/timestamp.h +++ b/modules/platforms/cpp/common/include/ignite/timestamp.h @@ -32,7 +32,7 @@ namespace ignite { /** - * Timestamp type. + * %Timestamp type. */ class IGNITE_IMPORT_EXPORT Timestamp { diff --git a/modules/platforms/cpp/core/include/ignite/cache/cache.h b/modules/platforms/cpp/core/include/ignite/cache/cache.h index 2beb66e1b7066..59b7a6abffdad 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/cache.h +++ b/modules/platforms/cpp/core/include/ignite/cache/cache.h @@ -50,6 +50,11 @@ namespace ignite * Both key and value types should be default-constructable, * copy-constructable and assignable. Also BinaryType class * template should be specialized for both types. + * + * 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. */ template class IGNITE_IMPORT_EXPORT Cache @@ -57,6 +62,10 @@ namespace ignite public: /** * Constructor. + * + * Internal method. Should not be used by user. + * + * @param impl Implementation. */ Cache(impl::cache::CacheImpl* impl) : impl(impl) @@ -67,6 +76,8 @@ namespace ignite /** * Get name of this cache (null for default cache). * + * This method should only be used on the valid instance. + * * @return Name of this cache (null for default cache). */ const char* GetName() const @@ -78,6 +89,8 @@ namespace ignite * Checks whether this cache contains no key-value mappings. * Semantically equals to Cache.Size(IGNITE_PEEK_MODE_PRIMARY) == 0. * + * This method should only be used on the valid instance. + * * @return True if cache is empty. */ bool IsEmpty() @@ -95,6 +108,8 @@ namespace ignite * Checks whether this cache contains no key-value mappings. * Semantically equals to Cache.Size(IGNITE_PEEK_MODE_PRIMARY) == 0. * + * This method should only be used on the valid instance. + * * @param err Error. * @return True if cache is empty. */ @@ -106,6 +121,8 @@ namespace ignite /** * Check if cache contains mapping for this key. * + * This method should only be used on the valid instance. + * * @param key Key. * @return True if cache contains mapping for this key. */ @@ -123,6 +140,8 @@ namespace ignite /** * Check if cache contains mapping for this key. * + * This method should only be used on the valid instance. + * * @param key Key. * @param err Error. * @return True if cache contains mapping for this key. @@ -137,6 +156,8 @@ namespace ignite /** * Check if cache contains mapping for these keys. * + * This method should only be used on the valid instance. + * * @param keys Keys. * @return True if cache contains mapping for all these keys. */ @@ -154,6 +175,8 @@ namespace ignite /** * Check if cache contains mapping for these keys. * + * This method should only be used on the valid instance. + * * @param keys Keys. * @param err Error. * @return True if cache contains mapping for all these keys. @@ -172,6 +195,8 @@ namespace ignite * This method does not participate in any transactions, however, it may peek at transactional * value depending on the peek modes used. * + * This method should only be used on the valid instance. + * * @param key Key. * @param peekModes Peek modes. * @return Value. @@ -194,6 +219,8 @@ namespace ignite * This method does not participate in any transactions, however, it may peek at transactional * value depending on the peek modes used. * + * This method should only be used on the valid instance. + * * @param key Key. * @param peekModes Peek modes. * @param err Error. @@ -216,6 +243,8 @@ namespace ignite * will be loaded from persistent store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key. * @return Value. */ @@ -237,6 +266,8 @@ namespace ignite * will be loaded from persistent store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key. * @param err Error. * @return Value. @@ -258,6 +289,8 @@ namespace ignite * will be loaded from persistent store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param keys Keys. * @return Map of key-value pairs. */ @@ -279,6 +312,8 @@ namespace ignite * will be loaded from persistent store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param keys Keys. * @param err Error. * @return Map of key-value pairs. @@ -298,6 +333,8 @@ namespace ignite * If the cache previously contained a mapping for the key, * the old value is replaced by the specified value. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. */ @@ -315,6 +352,8 @@ namespace ignite * If the cache previously contained a mapping for the key, * the old value is replaced by the specified value. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @param err Error. @@ -331,6 +370,8 @@ namespace ignite * If write-through is enabled, the stored values will be persisted to store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param vals Key-value pairs to store in cache. */ void PutAll(const std::map& vals) @@ -347,6 +388,8 @@ namespace ignite * If write-through is enabled, the stored values will be persisted to store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param vals Key-value pairs to store in cache. * @param err Error. */ @@ -361,6 +404,8 @@ namespace ignite * Associates the specified value with the specified key in this cache, * returning an existing value if one existed. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @return The value associated with the key at the start of the @@ -381,6 +426,8 @@ namespace ignite * Associates the specified value with the specified key in this cache, * returning an existing value if one existed. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @param err Error. @@ -401,6 +448,8 @@ namespace ignite * Atomically replaces the value for a given key if and only if there is * a value currently mapped by the key. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @return The previous value associated with the specified key, or @@ -421,6 +470,8 @@ namespace ignite * Atomically replaces the value for a given key if and only if there is * a value currently mapped by the key. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @param err Error. @@ -440,6 +491,8 @@ namespace ignite /** * Atomically removes the entry for a key only if currently mapped to some value. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is associated. * @return The value if one existed or null if no mapping existed for this key. */ @@ -457,6 +510,8 @@ namespace ignite /** * Atomically removes the entry for a key only if currently mapped to some value. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is associated. * @param err Error. * @return The value if one existed or null if no mapping existed for this key. @@ -475,6 +530,8 @@ namespace ignite * Atomically associates the specified key with the given value if it is not * already associated with a value. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @return True if a value was set. @@ -494,6 +551,8 @@ namespace ignite * Atomically associates the specified key with the given value if it is not * already associated with a value. * + * This method should only be used on the valid instance. + * * @param key Key with which the specified value is to be associated. * @param val Value to be associated with the specified key. * @param err Error. @@ -517,6 +576,8 @@ namespace ignite * If write-through is enabled, the stored value will be persisted to store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key to store in cache. * @param val Value to be associated with the given key. * @return Previously contained value regardless of whether put happened or not @@ -544,6 +605,8 @@ namespace ignite * If write-through is enabled, the stored value will be persisted to store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key to store in cache. * @param val Value to be associated with the given key. * @param err Error. @@ -569,6 +632,8 @@ namespace ignite * If write-through is enabled, the stored value will be persisted to store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key to store in cache. * @param val Value to be associated with the given key. * @return True if the value was replaced. @@ -593,6 +658,8 @@ namespace ignite * If write-through is enabled, the stored value will be persisted to store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key to store in cache. * @param val Value to be associated with the given key. * @param err Error. @@ -610,6 +677,8 @@ namespace ignite * old value passed as argument. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key to store in cache. * @param oldVal Old value to match. * @param newVal Value to be associated with the given key. @@ -631,6 +700,8 @@ namespace ignite * old value passed as argument. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key to store in cache. * @param oldVal Old value to match. * @param newVal Value to be associated with the given key. @@ -645,8 +716,12 @@ namespace ignite } /** - * Attempts to evict all entries associated with keys. Note, that entry will be evicted only - * if it's not used (not participating in any locks or transactions). + * Attempts to evict all entries associated with keys. + * + * @note Entry will be evicted only if it's not used (not + * participating in any locks or transactions). + * + * This method should only be used on the valid instance. * * @param keys Keys to evict from cache. */ @@ -660,8 +735,12 @@ namespace ignite } /** - * Attempts to evict all entries associated with keys. Note, that entry will be evicted only - * if it's not used (not participating in any locks or transactions). + * Attempts to evict all entries associated with keys. + * + * @note Entry will be evicted only if it's not used (not + * participating in any locks or transactions). + * + * This method should only be used on the valid instance. * * @param keys Keys to evict from cache. * @param err Error. @@ -675,6 +754,8 @@ namespace ignite /** * Clear cache. + * + * This method should only be used on the valid instance. */ void Clear() { @@ -688,6 +769,8 @@ namespace ignite /** * Clear cache. * + * This method should only be used on the valid instance. + * * @param err Error. */ void Clear(IgniteError& err) @@ -699,6 +782,8 @@ namespace ignite * Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. * + * This method should only be used on the valid instance. + * * @param key Key to clear. */ void Clear(const K& key) @@ -714,6 +799,8 @@ namespace ignite * Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. * + * This method should only be used on the valid instance. + * * @param key Key to clear. * @param err Error. */ @@ -728,6 +815,8 @@ namespace ignite * Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. * + * This method should only be used on the valid instance. + * * @param keys Keys to clear. */ void ClearAll(const std::set& keys) @@ -743,6 +832,8 @@ namespace ignite * Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. * + * This method should only be used on the valid instance. + * * @param keys Keys to clear. * @param err Error. */ @@ -756,9 +847,12 @@ namespace ignite /** * Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. - * Note that this operation is local as it merely clears an entry from local cache, it does not + * + * @note This operation is local as it merely clears an entry from local cache, it does not * remove entries from remote caches. * + * This method should only be used on the valid instance. + * * @param key Key to clear. */ void LocalClear(const K& key) @@ -773,9 +867,12 @@ namespace ignite /** * Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. - * Note that this operation is local as it merely clears an entry from local cache, it does not + * + * @note This operation is local as it merely clears an entry from local cache, it does not * remove entries from remote caches. * + * This method should only be used on the valid instance. + * * @param key Key to clear. * @param err Error. */ @@ -789,9 +886,12 @@ namespace ignite /** * Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. - * Note that this operation is local as it merely clears entries from local cache, it does not + * + * @note This operation is local as it merely clears entries from local cache, it does not * remove entries from remote caches. * + * This method should only be used on the valid instance. + * * @param keys Keys to clear. */ void LocalClearAll(const std::set& keys) @@ -806,9 +906,12 @@ namespace ignite /** * Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. * Entry is cleared only if it is not currently locked, and is not participating in a transaction. - * Note that this operation is local as it merely clears entries from local cache, it does not + * + * @note This operation is local as it merely clears entries from local cache, it does not * remove entries from remote caches. * + * This method should only be used on the valid instance. + * * @param keys Keys to clear. * @param err Error. */ @@ -829,6 +932,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key whose mapping is to be removed from cache. * @return False if there was no matching key. */ @@ -853,6 +958,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key whose mapping is to be removed from cache. * @param err Error. * @return False if there was no matching key. @@ -869,6 +976,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key whose mapping is to be removed from cache. * @param val Value to match against currently cached value. * @return True if entry was removed, false otherwise. @@ -889,6 +998,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param key Key whose mapping is to be removed from cache. * @param val Value to match against currently cached value. * @param err Error. @@ -906,6 +1017,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param keys Keys whose mappings are to be removed from cache. */ void RemoveAll(const std::set& keys) @@ -922,6 +1035,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param keys Keys whose mappings are to be removed from cache. * @param err Error. */ @@ -937,6 +1052,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param err Error. */ void RemoveAll() @@ -953,6 +1070,8 @@ namespace ignite * If write-through is enabled, the value will be removed from store. * This method is transactional and will enlist the entry into ongoing transaction if there is one. * + * This method should only be used on the valid instance. + * * @param err Error. */ void RemoveAll(IgniteError& err) @@ -963,6 +1082,8 @@ namespace ignite /** * Gets the number of all entries cached on this node. * + * This method should only be used on the valid instance. + * * @return Cache size on this node. */ int32_t LocalSize() @@ -973,6 +1094,8 @@ namespace ignite /** * Gets the number of all entries cached on this node. * + * This method should only be used on the valid instance. + * * @param err Error. * @return Cache size on this node. */ @@ -984,6 +1107,8 @@ namespace ignite /** * Gets the number of all entries cached on this node. * + * This method should only be used on the valid instance. + * * @param Peek modes. * @return Cache size on this node. */ @@ -1001,6 +1126,8 @@ namespace ignite /** * Gets the number of all entries cached on this node. * + * This method should only be used on the valid instance. + * * @param Peek modes. * @param err Error. * @return Cache size on this node. @@ -1012,7 +1139,9 @@ namespace ignite /** * Gets the number of all entries cached across all nodes. - * NOTE: this operation is distributed and will query all participating nodes for their cache sizes. + * @note this operation is distributed and will query all participating nodes for their cache sizes. + * + * This method should only be used on the valid instance. * * @return Cache size across all nodes. */ @@ -1023,7 +1152,9 @@ namespace ignite /** * Gets the number of all entries cached across all nodes. - * NOTE: this operation is distributed and will query all participating nodes for their cache sizes. + * @note This operation is distributed and will query all participating nodes for their cache sizes. + * + * This method should only be used on the valid instance. * * @param err Error. * @return Cache size across all nodes. @@ -1035,7 +1166,9 @@ namespace ignite /** * Gets the number of all entries cached across all nodes. - * NOTE: this operation is distributed and will query all participating nodes for their cache sizes. + * @note This operation is distributed and will query all participating nodes for their cache sizes. + * + * This method should only be used on the valid instance. * * @param Peek modes. * @return Cache size across all nodes. @@ -1053,7 +1186,9 @@ namespace ignite /** * Gets the number of all entries cached across all nodes. - * NOTE: this operation is distributed and will query all participating nodes for their cache sizes. + * @note This operation is distributed and will query all participating nodes for their cache sizes. + * + * This method should only be used on the valid instance. * * @param Peek modes. * @param err Error. @@ -1067,6 +1202,8 @@ namespace ignite /** * Perform SQL query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1084,6 +1221,8 @@ namespace ignite /** * Perform SQL query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @param err Error. * @return Query cursor. @@ -1098,6 +1237,8 @@ namespace ignite /** * Perform text query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1115,6 +1256,8 @@ namespace ignite /** * Perform text query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @param err Error. * @return Query cursor. @@ -1129,6 +1272,8 @@ namespace ignite /** * Perform scan query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1146,6 +1291,8 @@ namespace ignite /** * Perform scan query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @param err Error. * @return Query cursor. @@ -1160,6 +1307,8 @@ namespace ignite /** * Perform sql fields query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1177,6 +1326,8 @@ namespace ignite /** * Perform sql fields query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @param err Error. * @return Query cursor. diff --git a/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h b/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h index 3d34c85c21fc6..9810600724d5b 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h +++ b/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h @@ -30,7 +30,7 @@ namespace ignite namespace cache { /** - * Cache entry class template. + * %Cache entry class template. * * Both key and value types should be default-constructable, * copy-constructable and assignable. diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h index c17c6b7da3d42..4c46662802dbb 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h @@ -44,6 +44,11 @@ namespace ignite * Both key and value types should be default-constructable, * copy-constructable and assignable. Also BinaryType class * template should be specialized for both types. + * + * 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. */ template class QueryCursor diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h index 2d057d69c0fb8..3946e1c8ed2da 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h @@ -41,6 +41,11 @@ namespace ignite { /** * Query fields cursor. + * + * 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 QueryFieldsCursor { diff --git a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h index 7b665b8781371..d3ac2de973d27 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h +++ b/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h @@ -40,6 +40,11 @@ namespace ignite { /** * Query fields cursor. + * + * 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 QueryFieldsRow { diff --git a/modules/platforms/cpp/core/include/ignite/ignite.h b/modules/platforms/cpp/core/include/ignite/ignite.h index e4f92082ac95a..311dff20441e4 100644 --- a/modules/platforms/cpp/core/include/ignite/ignite.h +++ b/modules/platforms/cpp/core/include/ignite/ignite.h @@ -31,7 +31,12 @@ namespace ignite { /** - * Main interface to operate with Ignite. + * Main interface to operate with %Ignite. + * + * 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_IMPORT_EXPORT Ignite { @@ -57,6 +62,8 @@ namespace ignite /** * Get cache. * + * This method should only be used on the valid instance. + * * @param name Cache name. * @return Cache. */ @@ -75,6 +82,8 @@ namespace ignite /** * Get cache. * + * This method should only be used on the valid instance. + * * @param name Cache name. * @param err Error; * @return Cache. @@ -90,6 +99,8 @@ namespace ignite /** * Get or create cache. * + * This method should only be used on the valid instance. + * * @param name Cache name. * @return Cache. */ @@ -108,6 +119,8 @@ namespace ignite /** * Get or create cache. * + * This method should only be used on the valid instance. + * * @param name Cache name. * @param err Error; * @return Cache. @@ -123,6 +136,8 @@ namespace ignite /** * Create cache. * + * This method should only be used on the valid instance. + * * @param name Cache name. * @return Cache. */ @@ -141,6 +156,8 @@ namespace ignite /** * Create cache. * + * This method should only be used on the valid instance. + * * @param name Cache name. * @param err Error; * @return Cache. @@ -156,6 +173,8 @@ namespace ignite /** * Get transactions. * + * This method should only be used on the valid instance. + * * @return Transaction class instance. */ transactions::Transactions GetTransactions(); diff --git a/modules/platforms/cpp/core/include/ignite/ignite_configuration.h b/modules/platforms/cpp/core/include/ignite/ignite_configuration.h index ee59c115251bf..65c455057a0c0 100644 --- a/modules/platforms/cpp/core/include/ignite/ignite_configuration.h +++ b/modules/platforms/cpp/core/include/ignite/ignite_configuration.h @@ -32,7 +32,7 @@ namespace ignite { /** - * Ignite configuration. + * %Ignite configuration. */ struct IgniteConfiguration { @@ -58,7 +58,7 @@ namespace ignite std::list jvmOpts; /** - * Constructor. + * Default constructor. */ IgniteConfiguration() : igniteHome(), springCfgPath(), jvmLibPath(), jvmClassPath(), jvmInitMem(512), jvmMaxMem(1024), jvmOpts() diff --git a/modules/platforms/cpp/core/include/ignite/ignition.h b/modules/platforms/cpp/core/include/ignite/ignition.h index 31f5b0b53ce60..f88efe5358064 100644 --- a/modules/platforms/cpp/core/include/ignite/ignition.h +++ b/modules/platforms/cpp/core/include/ignite/ignition.h @@ -31,7 +31,7 @@ namespace ignite { /** - * This class defines a factory for the main Ignite API. + * This class defines a factory for the main %Ignite API. */ class IGNITE_IMPORT_EXPORT Ignition { diff --git a/modules/platforms/cpp/core/include/ignite/transactions/transaction.h b/modules/platforms/cpp/core/include/ignite/transactions/transaction.h index f68470e52fc8a..b51a42c53371c 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 -#include #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); @@ -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 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 5799b9f3e7c17..8b25d3a5f8530 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 }; } 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 4986a643155fb..00ebd1048216a 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 { diff --git a/modules/platforms/cpp/core/include/ignite/transactions/transactions.h b/modules/platforms/cpp/core/include/ignite/transactions/transactions.h index 130116a3b4672..98282bd9a648e 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); @@ -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.