From: Sage Weil <sage@redhat.com>
Date: Mon, 22 Dec 2014 21:56:07 +0000 (-0800)
Subject: librados: warn about rados_watch_flush() prior to ioctx shutdown
X-Git-Tag: v0.92~98^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=1fbe9b6f3a67584829fe17b6bb08cfa1b787d82c;p=ceph.git

librados: warn about rados_watch_flush() prior to ioctx shutdown

Signed-off-by: Sage Weil <sage@redhat.com>
---

diff --git a/src/include/rados/librados.h b/src/include/rados/librados.h
index acc3ced8f0e..70cec7fbbdb 100644
--- a/src/include/rados/librados.h
+++ b/src/include/rados/librados.h
@@ -393,6 +393,10 @@ CEPH_RADOS_API int rados_connect(rados_t cluster);
  * completed. To do that, you must call rados_aio_flush() on all open
  * io contexts.
  *
+ * @warning We implicitly call rados_watch_flush() on shutdown.  If
+ * there are watches being used, this should be done explicitly before
+ * destroying the relevant IoCtx.  We do it here as a safety measure.
+ *
  * @post the cluster handle cannot be used again
  *
  * @param cluster the cluster to shutdown
@@ -632,6 +636,12 @@ CEPH_RADOS_API int rados_ioctx_create(rados_t cluster, const char *pool_name,
  * writes have completed. You must call rados_aio_flush()
  * on the io context before destroying it to do that.
  *
+ * @warning If this ioctx is used by rados_watch, the caller needs to
+ * be sure that all registered watches are disconnected via
+ * rados_unwatch() and that rados_watch_flush() is called.  This
+ * ensures that a racing watch callback does not make use of a
+ * destroyed ioctx.
+ *
  * @param io the io context to dispose of
  */
 CEPH_RADOS_API void rados_ioctx_destroy(rados_ioctx_t io);
diff --git a/src/include/rados/librados.hpp b/src/include/rados/librados.hpp
index e3e206d9500..ac892fd24c4 100644
--- a/src/include/rados/librados.hpp
+++ b/src/include/rados/librados.hpp
@@ -590,6 +590,10 @@ namespace librados
    * rados.ioctx_create("my_pool", p);
    * p->stat(&stats);
    * ... etc ...
+   *
+   * NOTE: be sure to call watch_flush() prior to destroying any IoCtx
+   * that is used for watch events to ensure that racing callbacks
+   * have completed.
    */
   class CEPH_RADOS_API IoCtx
   {