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 b5de1beb1e397e9d0d0a9e16395fe045f9ce6b2c..8593b323fc6def5b4defa18bc9e53e2487c259d2 100644 (file)
--- a/src/include/neorados/RADOS.hpp
+++ b/src/include/neorados/RADOS.hpp
@@ -407,6 +407,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,
@@ -1164,6 +1182,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 abb6406ab2d57bf75fcfc04adac8901109fc864d..7d2d30504014bdace9c71ee226c006ec62ce1842 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
@@ -3444,6 +3448,9 @@ CEPH_RADOS_API void rados_read_op_checksum(rados_read_op_t read_op,
  * invalid OSD. Reads are permitted as part of write ops. If performance is a
  * concern, consider moving to the C++ interface, which provides safety.
  *
+ * NOTE: At the time this function was deprecated, it was unused within the
+ *       ceph code base.
+ *
  * Execute an OSD class method on an object
  * See rados_exec() for general description.
  *
@@ -3472,11 +3479,14 @@ CEPH_RADOS_API void rados_read_op_exec(rados_read_op_t read_op,
   __attribute__((deprecated("Use write ops instead")));
 
 /**
-  * * Deprecated because this op does not prevent the client specifying a cls op
-   * that includes a write operation. This could allow the op to be routed to
-   * invalid OSD. Reads are permitted as part of write ops. If performance is a
-   * concern, consider moving to the C++ interface, which provides safety.
-   *
+ * Deprecated because this op does not prevent the client specifying a cls op
+ * that includes a write operation. This could allow the op to be routed to
+ * invalid OSD. Reads are permitted as part of write ops. If performance is a
+ * concern, consider moving to the C++ interface, which provides safety.
+ *
+ * NOTE: At the time this function was deprecated, it was unused within the
+ *       ceph code base.
+ *
  * Execute an OSD class method on an object
  * See rados_exec() for general description.
  *

diff --git a/src/include/rados/librados.hpp b/src/include/rados/librados.hpp
index bca249ea17aaf4b3f81af9f07840d343d6754e82..d1d0896c97400dbb91e75d55067fe9cd9206a0fc 100644 (file)
--- a/src/include/rados/librados.hpp
+++ b/src/include/rados/librados.hpp
@@ -355,8 +355,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,
@@ -554,6 +565,18 @@ inline namespace v14_2_0 {
 
     using ObjectOperation::exec; // For deprecated rw operations.
 
+    /**
+     * Execute an OSD class method on an object
+     * See IoCtx::exec() for general description.
+     *
+     * Add an exec to write operation. Read or Write exec methods are permitted.
+     *
+     * @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) {
       // Read or write operations are permitted, so allow this.
@@ -925,6 +948,24 @@ inline namespace v14_2_0 {
     int exec_rw(const std::string& oid, const char *cls, const char *method,
              bufferlist& inbl, bufferlist& outbl);
    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
+     *
+     * Synchronous variant of exec. Op will be routed as read if the method
+     * is not flagged as a write.
+     *
+     * @param oid the object name
+     * @param method the method as defined in cls/<class>/cls_<class>_ops.h
+     * @param inbl where to find input
+     * @param outbl where to store output
+     * @returns return code (>=0 for success, otherwise stanard OSD errors)
+     */
     template <typename Tag, typename ClassID>
     int exec(const std::string& oid, const ClsMethod<Tag, ClassID>& method, bufferlist& inbl, bufferlist& outbl) {
       if constexpr (FlagTraits<Tag>::is_readonly) {
@@ -1231,6 +1272,19 @@ inline namespace v14_2_0 {
              bufferlist& inbl, bufferlist *outbl);
 
   public:
+    /**
+     * Execute an OSD class method on an object
+     * See exec() for general description.
+     *
+     * Asynchronous variant of exec. Op will be routed as read if the exec
+     * method is not flagged as a write.
+     *
+     * @param oid the object name
+     * @param c aio completion
+     * @param method the method as defined in cls/<class>/cls_<class>_ops.h
+     * @param inbl where to find input
+     * @param outbl where to store output
+     */
     template <typename Tag, typename ClassID>
     int aio_exec(const std::string& oid, AioCompletion *c,
           const ClsMethod<Tag, ClassID>& method, bufferlist& inbl, bufferlist *outbl) {