From: Alex Ainscow Date: Tue, 25 Nov 2025 10:18:51 +0000 (+0000) Subject: librados/neorados: Improve documentation for exec X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=6dc913aa7016efa5e0509c78826b1205abce8820;p=ceph-ci.git librados/neorados: Improve documentation for exec Signed-off-by: Alex Ainscow --- diff --git a/src/include/neorados/RADOS.hpp b/src/include/neorados/RADOS.hpp index b5de1beb1e3..8593b323fc6 100644 --- 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//cls__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 void exec(const ClsMethod& method, const ceph::buffer::list& inbl, Args&&... args) { static_assert(FlagTraits::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//cls__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 decltype(auto) exec(const ClsMethod& method, const ceph::buffer::list& inbl, Args&&... args) & { Op::exec_impl(method.cls, method.name, inbl, std::forward(args)...); diff --git a/src/include/rados/librados.h b/src/include/rados/librados.h index abb6406ab2d..7d2d3050401 100644 --- 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 bca249ea17a..d1d0896c974 100644 --- 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//cls__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 void exec(const ClsMethod& method, Args&&... args) { static_assert(FlagTraits::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//cls__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 void exec(const ClsMethod& 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//cls__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 int exec(const std::string& oid, const ClsMethod& method, bufferlist& inbl, bufferlist& outbl) { if constexpr (FlagTraits::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//cls__ops.h + * @param inbl where to find input + * @param outbl where to store output + */ template int aio_exec(const std::string& oid, AioCompletion *c, const ClsMethod& method, bufferlist& inbl, bufferlist *outbl) {