IGNITE-3113: CPP: Binary containers documentation. This closes #711.
Project: http://git-wip-us.apache.org/repos/asf/ignite/repo Commit: http://git-wip-us.apache.org/repos/asf/ignite/commit/93445607 Tree: http://git-wip-us.apache.org/repos/asf/ignite/tree/93445607 Diff: http://git-wip-us.apache.org/repos/asf/ignite/diff/93445607 Branch: refs/heads/ignite-1232 Commit: 934456070d336fe2a5081f44429ec22d8fc22603 Parents: 5e91594 Author: isapego <[email protected]> Authored: Thu Jun 23 15:49:45 2016 +0300 Committer: vozerov-gridgain <[email protected]> Committed: Thu Jun 23 15:49:45 2016 +0300 ---------------------------------------------------------------------- .../include/ignite/binary/binary_containers.h | 191 +++++++++++++++---- .../include/ignite/binary/binary_raw_reader.h | 25 ++- .../include/ignite/binary/binary_raw_writer.h | 13 ++ .../include/ignite/binary/binary_reader.h | 13 ++ .../include/ignite/binary/binary_writer.h | 13 ++ .../platforms/cpp/common/include/ignite/date.h | 2 +- .../cpp/common/include/ignite/ignite_error.h | 19 +- .../cpp/common/include/ignite/timestamp.h | 2 +- .../platforms/cpp/common/src/ignite_error.cpp | 12 +- .../cpp/core/include/ignite/cache/cache.h | 186 ++++++++++++++++-- .../cpp/core/include/ignite/cache/cache_entry.h | 14 +- .../include/ignite/cache/query/query_argument.h | 33 ++-- .../include/ignite/cache/query/query_cursor.h | 17 +- .../ignite/cache/query/query_fields_cursor.h | 11 +- .../ignite/cache/query/query_fields_row.h | 22 ++- .../include/ignite/cache/query/query_scan.h | 10 +- .../core/include/ignite/cache/query/query_sql.h | 15 +- .../ignite/cache/query/query_sql_fields.h | 15 +- .../platforms/cpp/core/include/ignite/ignite.h | 21 +- .../core/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 +- .../include/ignite/transactions/transactions.h | 36 +++- modules/platforms/cpp/core/namespaces.dox | 2 +- modules/platforms/cpp/cpp.dxg | 4 +- 27 files changed, 687 insertions(+), 160 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/binary/include/ignite/binary/binary_containers.h ---------------------------------------------------------------------- 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 946101c..8f26416 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<typename T> 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<typename T> 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<typename K, typename V> 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<typename T> 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<typename T> 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<typename K, typename V> 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() { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_reader.h ---------------------------------------------------------------------- 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 473be3d..3104437 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); @@ -205,14 +218,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 +237,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 +256,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. http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/binary/include/ignite/binary/binary_raw_writer.h ---------------------------------------------------------------------- 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 41cfef7..c960406 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); http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/binary/include/ignite/binary/binary_reader.h ---------------------------------------------------------------------- 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 3e5bbb1..ac70f39 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); http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/binary/include/ignite/binary/binary_writer.h ---------------------------------------------------------------------- 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 1bee82a..1923694 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); http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/common/include/ignite/date.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/common/include/ignite/date.h b/modules/platforms/cpp/common/include/ignite/date.h index 31fe5d0..ffdebd3 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 { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/common/include/ignite/ignite_error.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/common/include/ignite/ignite_error.h b/modules/platforms/cpp/common/include/ignite/ignite_error.h index edba67a..4c0e263 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: http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/common/include/ignite/timestamp.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/common/include/ignite/timestamp.h b/modules/platforms/cpp/common/include/ignite/timestamp.h index 4528e53..14b83fa 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 { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/common/src/ignite_error.cpp ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/common/src/ignite_error.cpp b/modules/platforms/cpp/common/src/ignite_error.cpp index 722214b..5acbed2 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 <utility> + #include <ignite/ignite_error.h> #include <ignite/common/utils.h> @@ -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; http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/cache.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/cache/cache.h b/modules/platforms/cpp/core/include/ignite/cache/cache.h index e60c843..59b7a6a 100644 --- a/modules/platforms/cpp/core/include/ignite/cache/cache.h +++ b/modules/platforms/cpp/core/include/ignite/cache/cache.h @@ -46,6 +46,15 @@ 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. + * + * 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<typename K, typename V> class IGNITE_IMPORT_EXPORT Cache @@ -53,14 +62,23 @@ namespace ignite public: /** * Constructor. + * + * Internal method. Should not be used by user. + * + * @param impl Implementation. */ - Cache(impl::cache::CacheImpl* impl) : impl(ignite::common::concurrent::SharedPointer<impl::cache::CacheImpl>(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). + * + * This method should only be used on the valid instance. + * + * @return Name of this cache (null for default cache). */ const char* GetName() const { @@ -71,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() @@ -88,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. */ @@ -99,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. */ @@ -116,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. @@ -130,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. */ @@ -147,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. @@ -165,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. @@ -187,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. @@ -209,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. */ @@ -230,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. @@ -251,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. */ @@ -272,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. @@ -291,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. */ @@ -308,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. @@ -324,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<K, V>& vals) @@ -340,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. */ @@ -354,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 @@ -374,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. @@ -394,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 @@ -414,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. @@ -433,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. */ @@ -450,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. @@ -468,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. @@ -487,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. @@ -510,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 @@ -537,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. @@ -562,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. @@ -586,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. @@ -603,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. @@ -624,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. @@ -638,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. */ @@ -653,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. @@ -668,6 +754,8 @@ namespace ignite /** * Clear cache. + * + * This method should only be used on the valid instance. */ void Clear() { @@ -681,6 +769,8 @@ namespace ignite /** * Clear cache. * + * This method should only be used on the valid instance. + * * @param err Error. */ void Clear(IgniteError& err) @@ -692,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) @@ -707,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. */ @@ -721,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<K>& keys) @@ -736,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. */ @@ -749,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) @@ -766,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. */ @@ -782,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<K>& keys) @@ -799,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. */ @@ -822,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. */ @@ -846,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. @@ -862,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. @@ -882,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. @@ -899,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<K>& keys) @@ -915,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. */ @@ -930,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() @@ -946,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) @@ -956,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() @@ -966,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. */ @@ -977,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. */ @@ -994,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. @@ -1005,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. */ @@ -1016,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. @@ -1028,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. @@ -1046,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. @@ -1060,6 +1202,8 @@ namespace ignite /** * Perform SQL query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1077,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. @@ -1091,6 +1237,8 @@ namespace ignite /** * Perform text query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1108,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. @@ -1122,6 +1272,8 @@ namespace ignite /** * Perform scan query. * + * This method should only be used on the valid instance. + * * @param qry Query. * @return Query cursor. */ @@ -1139,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. @@ -1153,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. */ @@ -1170,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. http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/cache_entry.h ---------------------------------------------------------------------- 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 f709650..9810600 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. @@ -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; http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_argument.h ---------------------------------------------------------------------- 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 933bd60..65578ce 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<typename T> 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; } http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_cursor.h ---------------------------------------------------------------------- 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 45eb54a..4c46662 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,13 @@ 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. + * + * 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<typename K, typename V> class QueryCursor @@ -73,11 +79,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 +124,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<K, V> GetNext() { @@ -175,11 +183,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<CacheEntry<K, V>>& res) { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_cursor.h ---------------------------------------------------------------------- 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 3952ece..3946e1c 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 { @@ -70,11 +75,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 +120,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() { http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_fields_row.h ---------------------------------------------------------------------- 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 521da76..d3ac2de 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 { @@ -47,8 +52,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 +73,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 +118,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<typename T> T GetNext() @@ -135,6 +145,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. http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_scan.h ---------------------------------------------------------------------- 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 d4dd565..4228ba5 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. * http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_sql.h ---------------------------------------------------------------------- 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 d80fa51..f7a00fa 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<typename T> http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/cache/query/query_sql_fields.h ---------------------------------------------------------------------- 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 4792d34..e21fc93 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<QueryArgumentBase*>::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<typename T> http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/ignite.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/ignite.h b/modules/platforms/cpp/core/include/ignite/ignite.h index e4f9208..311dff2 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(); http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/ignite_configuration.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/ignite_configuration.h b/modules/platforms/cpp/core/include/ignite/ignite_configuration.h index ee59c11..65c4550 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<std::string> jvmOpts; /** - * Constructor. + * Default constructor. */ IgniteConfiguration() : igniteHome(), springCfgPath(), jvmLibPath(), jvmClassPath(), jvmInitMem(512), jvmMaxMem(1024), jvmOpts() http://git-wip-us.apache.org/repos/asf/ignite/blob/93445607/modules/platforms/cpp/core/include/ignite/ignition.h ---------------------------------------------------------------------- diff --git a/modules/platforms/cpp/core/include/ignite/ignition.h b/modules/platforms/cpp/core/include/ignite/ignition.h index 31f5b0b..f88efe5 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 {
