From: Sage Weil <sage@inktank.com>
Date: Wed, 4 Sep 2013 23:39:34 +0000 (-0700)
Subject: librados: make note of which calls steal the bufferlist contents
X-Git-Tag: v0.71~171
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=16b24f10a022a1aabdecf0af1bd428b23aa83229;p=ceph.git

librados: make note of which calls steal the bufferlist contents

This is an unfortunate feature of the API, but it can't be changed without
potentially breaking users.

Fixes: #5989
Signed-off-by: Sage Weil <sage@inktank.com>
---

diff --git a/src/include/rados/librados.hpp b/src/include/rados/librados.hpp
index 5a750cbc0d1..94d3d23a824 100644
--- a/src/include/rados/librados.hpp
+++ b/src/include/rados/librados.hpp
@@ -439,8 +439,23 @@ namespace librados
     int create(const std::string& oid, bool exclusive);
     int create(const std::string& oid, bool exclusive, const std::string& category);
 
+    /**
+     * write bytes to an object at a specified offset
+     *
+     * NOTE: this call steals the contents of @param bl.
+     */
     int write(const std::string& oid, bufferlist& bl, size_t len, uint64_t off);
+    /**
+     * append bytes to an object
+     *
+     * NOTE: this call steals the contents of @param bl.
+     */
     int append(const std::string& oid, bufferlist& bl, size_t len);
+    /**
+     * replace object contents with provided data
+     *
+     * NOTE: this call steals the contents of @param bl.
+     */
     int write_full(const std::string& oid, bufferlist& bl);
     int clone_range(const std::string& dst_oid, uint64_t dst_off,
                    const std::string& src_oid, uint64_t src_off,
@@ -457,7 +472,17 @@ namespace librados
     int stat(const std::string& oid, uint64_t *psize, time_t *pmtime);
     int exec(const std::string& oid, const char *cls, const char *method,
 	     bufferlist& inbl, bufferlist& outbl);
+    /**
+     * modify object tmap based on encoded update sequence
+     *
+     * NOTE: this call steals the contents of @param bl
+     */
     int tmap_update(const std::string& oid, bufferlist& cmdbl);
+    /**
+     * replace object contents with provided encoded tmap data
+     *
+     * NOTE: this call steals the contents of @param bl
+     */
     int tmap_put(const std::string& oid, bufferlist& bl);
     int tmap_get(const std::string& oid, bufferlist& bl);