couchbase 3.4.2 → 3.4.4

data/ext/couchbase/couchbase/transactions/async_attempt_context.hxx

@@ -15,6 +15,7 @@
  */
 #pragma once
 
+#include <couchbase/scope.hxx>
 #include <couchbase/transactions/transaction_get_result.hxx>
 #include <couchbase/transactions/transaction_query_options.hxx>
 #include <couchbase/transactions/transaction_query_result.hxx>
@@ -24,52 +25,130 @@ namespace couchbase::transactions
 using async_result_handler = std::function<void(transaction_op_error_context, transaction_get_result)>;
 using async_query_handler = std::function<void(transaction_op_error_context, transaction_query_result)>;
 using async_err_handler = std::function<void(transaction_op_error_context)>;
+
+/**
+ * The async_attempt_context is used for all asynchronous transaction operations
+ *
+ * In the example below, we get 3 documents in parallel, and update each when the get returns the document:
+ *
+ * @snippet test/test_transaction_examples.cxx simple-async-txn
+ */
 class async_attempt_context
 {
 
   public:
+    /**
+     * Get document from a collection.
+     *
+     * Fetch the document contents, in the form of a @ref transaction_get_result.   This can be used in subsequent calls
+     * to @ref async_attempt_context::replace or @ref async_attempt_context::remove
+     *
+     * @param coll The collection which contains the document.
+     * @param id The document id which is used to uniquely identify it.
+     * @param handler The handler which implements @ref async_result_handler
+     */
     virtual void get(const collection& coll, std::string id, async_result_handler&& handler) = 0;
+    /**
+     * Remove a document from a collection.
+     *
+     * Removes a document from a collection, where the document was gotten from a previous call to @ref async_attempt_context::get
+     *
+     * @param doc The document to remove.
+     * @param handler The handler which implements @ref async_err_handler
+     */
     virtual void remove(transaction_get_result doc, async_err_handler&& handler) = 0;
 
+    /**
+     * Insert a document into a collection.
+     *
+     * Given an id and the content, this inserts a new document into a collection.   Note that currently this content can be either a
+     * <std::vector<std::byte>> or an object which can be serialized with the @ref codec::tao_json_serializer.
+     *
+     * @tparam Content type of the document.
+     * @param coll Collection to insert the document into.
+     * @param id The document id.
+     * @param content The content of the document.
+     * @param handler The handler which implements @ref async_result_handler
+     */
     template<typename Content>
     void insert(const collection& coll, std::string id, Content&& content, async_result_handler&& handler)
     {
         if constexpr (std::is_same_v<Content, std::vector<std::byte>>) {
             return insert_raw(std::forward<std::vector<std::byte>>(content), std::move(id), content, std::move(handler));
         } else {
+            // TODO: transcoder support
             return insert_raw(coll, std::move(id), codec::tao_json_serializer::serialize(content), std::move(handler));
         }
     }
-
+    /**
+     * Replace the contents of a document in a collection.
+     *
+     * Replaces the contents of an existing document. Note that currently this content can be either a
+     * <std::vector<std::byte>> or an object which can be serialized with the @ref codec::tao_json_serializer.
+     *
+     * @tparam Content type of the document
+     * @param doc Document whose content will be replaced.  This is gotten from a call to @ref async_attempt_context::get
+     * @param content New content of the document
+     * @param handler The handler which implements @ref async_result_handler
+     */
     template<typename Content>
     void replace(transaction_get_result doc, Content&& content, async_result_handler&& handler)
     {
         if constexpr (std::is_same_v<Content, std::vector<std::byte>>) {
             return replace_raw(std::move(doc), std::forward<std::vector<std::byte>>(content), std::move(handler));
         } else {
+            // TODO: transcoder support
             return replace_raw(std::move(doc), codec::tao_json_serializer::serialize(content), std::move(handler));
         }
     }
-
+    /**
+     * Perform a query, within a scope.
+     *
+     * Performs a query given a specific scope.   Note that all subsequent transaction operations will be handled by the query service.
+     *
+     * @param scope Scope for the query.
+     * @param statement The query statement
+     * @param opts Options for the query
+     * @param handler Handler which implements @ref async_query_handler.
+     */
     void query(const scope& scope, std::string statement, transaction_query_options opts, async_query_handler&& handler)
     {
         return query(std::move(statement), std::move(opts), fmt::format("{}.{}", scope.bucket_name(), scope.name()), std::move(handler));
     }
-
+    /**
+     * Perform a query.
+     *
+     * Performs an unscoped query.
+     *
+     * @param statement The query statement.
+     * @param opts Options for the query.
+     * @param handler Handler which implements @ref async_query_handler.
+     */
     void query(std::string statement, transaction_query_options opts, async_query_handler&& handler)
     {
         return query(statement, opts, {}, std::move(handler));
     };
-
+    /**
+     * Perform a query.
+     *
+     * Performs an unscoped query.
+     *
+     * @param statement The query statement.
+     * @param handler Handler which implements @ref async_query_handler
+     */
     void query(std::string statement, async_query_handler&& handler)
     {
         return query(std::move(statement), {}, std::move(handler));
     }
+
     virtual ~async_attempt_context() = default;
 
   protected:
+    /** @private */
     virtual void insert_raw(const collection& coll, std::string id, std::vector<std::byte> content, async_result_handler&& handler) = 0;
+    /** @private */
     virtual void replace_raw(transaction_get_result doc, std::vector<std::byte> content, async_result_handler&& handler) = 0;
+    /** @private */
     virtual void query(std::string statement,
                        transaction_query_options opts,
                        std::optional<std::string> query_context,

data/ext/couchbase/couchbase/transactions/attempt_context.hxx

@@ -21,12 +21,42 @@
 
 namespace couchbase::transactions
 {
+/**
+ * The attempt_context is used for all synchronous transaction operations
+ *
+ * In the example below, we get a document then replace its content:
+ *
+ * @snippet test/test_transaction_examples.cxx simple-blocking-txn
+ */
+
 class attempt_context
 {
   public:
+    /**
+     * Get a document from a collection.
+     *
+     * Fetch the document contents, in the form of a @ref transaction_get_result.   This can be used in subsequent calls
+     * to @ref attempt_context::replace or @ref attempt_context::remove
+     *
+     * @param coll The collection which contains the document.
+     * @param id The unique id of the document.
+     * @return The result of the operation, which is an @ref transaction_op_error_context and a @ref transaction_get_result.
+     */
     virtual std::pair<transaction_op_error_context, transaction_get_result> get(const couchbase::collection& coll,
                                                                                 const std::string& id) = 0;
 
+    /**
+     * Insert a document into a collection.
+     *
+     * Given an id and the content, this inserts a new document into a collection.   Note that currently this content can be either a
+     * <std::vector<std::byte>> or an object which can be serialized with the @ref codec::tao_json_serializer.
+     *
+     * @tparam Content Type of the contents of the document.
+     * @param coll Collection in which to insert document.
+     * @param id The unique id of the document.
+     * @param content The content of the document.
+     * @return The result of the operation, which is an @ref transaction_op_error_context and a @ref transaction_get_result.
+     */
     template<typename Content>
     std::pair<transaction_op_error_context, transaction_get_result> insert(const couchbase::collection& coll,
                                                                            const std::string& id,
@@ -39,6 +69,17 @@ class attempt_context
         }
     }
 
+    /**
+     * Replace the contents of a document in a collection.
+     *
+     * Replaces the contents of an existing document. Note that currently this content can be either a
+     * <std::vector<std::byte>> or an object which can be serialized with the @ref codec::tao_json_serializer.
+
+     * @tparam Content Type of the contents of the document.
+     * @param doc Document whose content will be replaced.  This is gotten from a call to @ref attempt_context::get
+     * @param content New content of the document.
+     * @return The result of the operation, which is an @ref transaction_op_error_context and a @ref transaction_get_result.
+     */
     template<typename Content>
     std::pair<transaction_op_error_context, transaction_get_result> replace(const transaction_get_result& doc, const Content& content)
     {
@@ -49,14 +90,37 @@ class attempt_context
         }
     }
 
+    /**
+     * Remove a document.
+     *
+     * Removes a document from a collection, where the document was gotten from a previous call to @ref attempt_context::get
+     *
+     * @param doc The document to remove.
+     * @return The result of the operation.
+     */
     virtual transaction_op_error_context remove(const transaction_get_result& doc) = 0;
 
+    /**
+     * Perform an unscoped query.
+     *
+     * @param statement The query statement.
+     * @param options Options for the query.
+     * @return The result of the operation, with is an @ref transaction_op_error_context and a @ref transaction_query_result.
+     */
     std::pair<transaction_op_error_context, transaction_query_result> query(const std::string& statement,
                                                                             const transaction_query_options& options = {})
     {
         return do_public_query(statement, options, {});
     }
 
+    /**
+     * Perform a scoped query.
+     *
+     * @param scope Scope for the query.
+     * @param statement The query statement.
+     * @param opts Options for the query.
+     * @return The result of the operation, with is an @ref transaction_op_error_context and a @ref transaction_query_result.
+     */
     std::pair<transaction_op_error_context, transaction_query_result> query(const scope& scope,
                                                                             const std::string& statement,
                                                                             const transaction_query_options& opts = {})
@@ -67,11 +131,14 @@ class attempt_context
     virtual ~attempt_context() = default;
 
   protected:
+    /** @private */
     virtual std::pair<transaction_op_error_context, transaction_get_result> replace_raw(const transaction_get_result& doc,
                                                                                         std::vector<std::byte> content) = 0;
+    /** @private */
     virtual std::pair<transaction_op_error_context, transaction_get_result> insert_raw(const couchbase::collection& coll,
                                                                                        const std::string& id,
                                                                                        std::vector<std::byte> content) = 0;
+    /** @private */
     virtual std::pair<transaction_op_error_context, transaction_query_result> do_public_query(const std::string& statement,
                                                                                               const transaction_query_options& options,
                                                                                               std::optional<std::string> query_context) = 0;

data/ext/couchbase/couchbase/transactions/transaction_get_result.hxx

@@ -48,6 +48,8 @@ class transaction_get_result
     }
 
   public:
+    /** @private */
+
     transaction_get_result();
     /**
      * Content of the document.

data/ext/couchbase/couchbase/transactions/transaction_keyspace.hxx

@@ -66,12 +66,20 @@ struct transaction_keyspace {
       : transaction_keyspace{ bucket_name, couchbase::scope::default_name, couchbase::collection::default_name }
     {
     }
-
+    /**
+     * Check if a keyspace is valid.
+     *
+     * A valid transaction_keyspace must have the bucket, scope, and collection all set.   Note that both the scope and collection default
+     * to _default, but there is no default for the bucket so it must be set.
+     *
+     * @return true if valid.
+     */
     bool valid()
     {
         return !bucket.empty() && !scope.empty() && !collection.empty();
     }
 
+    /** @private */
     template<typename OStream>
     friend OStream& operator<<(OStream& os, const transaction_keyspace& keyspace)
     {
@@ -84,6 +92,8 @@ struct transaction_keyspace {
     }
 };
 } // namespace couchbase::transactions
+
+/** @private */
 template<>
 struct fmt::formatter<couchbase::transactions::transaction_keyspace> {
   public:

data/ext/couchbase/couchbase/transactions/transaction_options.hxx

@@ -24,44 +24,91 @@
 
 namespace couchbase::transactions
 {
+/**
+ * The transaction_options can be passed in to override some elements of the global @ref transactions_config.
+ */
 class transaction_options
 {
   public:
     transaction_options() = default;
 
+    /**
+     * Set durability for this transaction.
+     *
+     * @see couchbase::durability_level for details.
+     *
+     * @param level Durability level for this transaction.
+     * @return reference to this object, convenient for chaining operations.
+     */
     transaction_options& durability_level(durability_level level)
     {
         durability_ = level;
         return *this;
     }
-
+    /**
+     * Get the durability if it has been set.
+     *
+     * @see couchbase::durability_level for details.
+     *
+     * @return durability if set.
+     */
     std::optional<couchbase::durability_level> durability_level()
     {
         return durability_;
     }
-
+    /**
+     * Set the @ref query_scan_consistency for this transaction.
+     *
+     * @see query_options::scan_consistency for details.
+     *
+     * @param scan_consistency The desired @ref query_scan_consistency for this transaction.
+     * @return reference to this object, convenient for chaining operations.
+     */
     transaction_options& scan_consistency(query_scan_consistency scan_consistency)
     {
         scan_consistency_ = scan_consistency;
         return *this;
     }
-
+    /**
+     * Get the scan_consistency if it has been set.
+     *
+     * @see query_options::scan_consistency for details.
+     *
+     * @return The scan_consistency, if set.
+     */
     std::optional<query_scan_consistency> scan_consistency()
     {
         return scan_consistency_;
     }
-
+    /**
+     * Set the timeout for key-value operations for this transaction.
+     *
+     * @param kv_timeout Desired key-value timeout.
+     * @return reference to this object, convenient for chaining operations.
+     */
     transaction_options& kv_timeout(std::chrono::milliseconds kv_timeout)
     {
         kv_timeout_ = kv_timeout;
         return *this;
     }
 
+    /**
+     * Get the key-value timeout if it has been set.
+     *
+     * @return The key-value timeout, if set.
+     */
     std::optional<std::chrono::milliseconds> kv_timeout()
     {
         return kv_timeout_;
     }
 
+    /**
+     * Set the expiration time for this transaction.
+     *
+     * @tparam T expiration time type, e.g. @ref std::chrono::milliseconds, or similar
+     * @param expiration_time Desired expiration time.
+     * @return reference to this object, convenient for chaining operations.
+     */
     template<typename T>
     transaction_options& expiration_time(T expiration_time)
     {
@@ -69,29 +116,53 @@ class transaction_options
         return *this;
     }
 
+    /**
+     * Get the expiration time, if set.
+     *
+     * @return the expiration time, if set.
+     */
     std::optional<std::chrono::nanoseconds> expiration_time()
     {
         return expiration_time_;
     }
 
+    /**
+     * Set the metadata collection to use for this transaction
+     *
+     * Transactions involve a the creation and use of some metadata documents, which by default are placed in the default collection of
+     * scope which the first document in the that has a mutating operation performed on it.   However, you can set this to a specific
+     * collection to isolate these documents from your documents, if desired.
+     *
+     * @param coll The desired collection to use.
+     * @return reference to this object, convenient for chaining operations.
+     */
     transaction_options& metadata_collection(const couchbase::collection& coll)
     {
         metadata_collection_.emplace(coll.bucket_name(), coll.scope_name(), coll.name());
         return *this;
     }
-
+    /**
+     * Set metadata collection to use for this transaction
+     *
+     * @param keyspace The desired collection to use
+     * @return reference to this object, convenient for chaining operations.
+     */
     transaction_options& metadata_collection(const couchbase::transactions::transaction_keyspace& keyspace)
     {
         metadata_collection_.emplace(keyspace);
         return *this;
     }
-
+    /**
+     * Get the metadata collection, if set.
+     *
+     * @return the metadata collection, as a @ref transaction_keyspace, if set.
+     */
     std::optional<transaction_keyspace> metadata_collection()
     {
         return metadata_collection_;
     }
 
-    /** @internal */
+    /** @private */
     transaction_options& test_factories(std::shared_ptr<core::transactions::attempt_context_testing_hooks> hooks,
                                         std::shared_ptr<core::transactions::cleanup_testing_hooks> cleanup_hooks)
     {
@@ -99,7 +170,7 @@ class transaction_options
         cleanup_hooks_ = cleanup_hooks;
         return *this;
     }
-
+    /** @private */
     [[nodiscard]] transactions_config::built apply(const transactions_config::built& conf) const;
 
   private: