librados/neorados: Improve documentation for exec

Signed-off-by: Alex Ainscow <aainscow@uk.ibm.com>

diff --git a/src/include/neorados/RADOS.hpp b/src/include/neorados/RADOS.hpp
index 59a5a08860cd171caa26c8d09569ead5ad231c3b..88ad02f9948915a3536c19f658e1da98481dfd49 100644 (file)
--- a/src/include/neorados/RADOS.hpp
+++ b/src/include/neorados/RADOS.hpp
@@ -386,6 +386,24 @@ public:
   }
  public:
 
+  /**
+   * Execute an OSD class method on an object
+   *
+   * The OSD has a plugin mechanism for performing complicated
+   * operations on an object atomically. These plugins are called
+   * classes. This function allows librados users to call the custom
+   * methods. The input and output formats are defined by the class.
+   * Classes in ceph.git can be found in src/cls subdirectories
+   *
+   * This Op may be a read, so only read execs are permitted with this interface
+   *
+   * @param method the method as defined in cls/<class>/cls_<class>_ops.h
+   * @param inbl where to find input
+   * @param out (optional) where to store output
+   * @param ec (optional) storage for error code
+   * @param f (optional) handler callback
+   * @returns return code (>=0 for success, otherwise stanard OSD errors)
+   */
   template <typename Tag, typename ClassID, typename... Args>
   void exec(const ClsMethod<Tag, ClassID>& method, const ceph::buffer::list& inbl, Args&&... args) {
     static_assert(FlagTraits<Tag>::is_readonly,
@@ -1011,6 +1029,24 @@ public:
     return std::move(*this);
   }
 
+  /**
+   * Execute an OSD class method on an object
+   *
+   * The OSD has a plugin mechanism for performing complicated
+   * operations on an object atomically. These plugins are called
+   * classes. This function allows librados users to call the custom
+   * methods. The input and output formats are defined by the class.
+   * Classes in ceph.git can be found in src/cls subdirectories
+   *
+   * This is a write op, so all execs are permitted (including reads)
+   *
+   * @param method the method as defined in cls/<class>/cls_<class>_ops.h
+   * @param inbl where to find input
+   * @param out (optional) where to store output
+   * @param ec (optional) storage for error code
+   * @param f (optional) handler callback
+   * @returns return code (>=0 for success, otherwise stanard OSD errors)
+   */
   template <typename Tag, typename ClassID, typename... Args>
   decltype(auto) exec(const ClsMethod<Tag, ClassID>& method, const ceph::buffer::list& inbl, Args&&... args) & {
     Op::exec_impl(method.cls, method.name, inbl, std::forward<Args>(args)...);

diff --git a/src/include/rados/librados.h b/src/include/rados/librados.h
index d788e64e2a5278b97a5b3bbc7f57a625df148adb..4797ce8c152f5539e97aaf79a5c37b725abfeca9 100644 (file)
--- a/src/include/rados/librados.h
+++ b/src/include/rados/librados.h
@@ -3066,6 +3066,10 @@ CEPH_RADOS_API void rados_write_op_zero(rados_write_op_t write_op,
  * Execute an OSD class method on an object
  * See rados_exec() for general description.
  *
+ * Use this for reads as well as writes. The rados_read_op_exec has been
+ * deprecated as there is no client-side checking for the chosen cls method
+ * actually being a read vs write.
+ *
  * @param write_op operation to add this action to
  * @param cls the name of the class
  * @param method the name of the method

diff --git a/src/include/rados/librados.hpp b/src/include/rados/librados.hpp
index 2a7c1e0ade2add1b61a932a044c3ed1301be558a..dbcef6958e2fc0eb25a222488397a11c84f10431 100644 (file)
--- a/src/include/rados/librados.hpp
+++ b/src/include/rados/librados.hpp
@@ -348,8 +348,19 @@ inline namespace v14_2_0 {
     void exec_impl(const char *cls, const char *method, bufferlist& inbl, ObjectOperationCompletion *completion);
    public:
 
-    // By default only allow READ operations. ObjectWriteOperation overrides this
-    // to allow writes.
+    /**
+     * Execute an OSD class method on an object
+     * See IoCtx::exec() for general description.
+     *
+     * Add an exec to read OR write operation. Only read-only methods may be
+     * added this way. Use ObjectWriteOperation::exec() for write methods.
+     *
+     * @param method the method as defined in cls/<class>/cls_<class>_ops.h
+     * @param inbl where to find input
+     * @param obl (optional) where to store output
+     * @param prval (optional) storage for return value.
+     * @param completion (optional) completion callback.
+     */
     template <typename Tag, typename ClassID, typename... Args>
     void exec(const ClsMethod<Tag, ClassID>& method, Args&&... args) {
       static_assert(FlagTraits<Tag>::is_readonly,