ceph/src/cls/refcount/cls_refcount_client.h

   1 #ifndef CEPH_CLS_REFCOUNT_CLIENT_H
   2 #define CEPH_CLS_REFCOUNT_CLIENT_H
   3
   4 #include "include/types.h"
   5
   6 namespace librados {
   7   class ObjectWriteOperation;
   8   class IoCtx;
   9 }
  10
  11 /*
  12  * refcount objclass
  13  *
  14  * The refcount objclass implements a refcounting scheme that allows having multiple references
  15  * to a single rados object. The canonical way to use it is to add a reference and to remove a
  16  * reference using a specific tag. This way we ensure that refcounting operations are idempotent,
  17  * that is, a single client can only increase/decrease the refcount once using a single tag, so
  18  * any replay of operations (implicit or explicit) is possible.
  19  *
  20  * So, the regular usage would be to create an object, to increase the refcount. Then, when
  21  * wanting to have another reference to it, increase the refcount using a different tag. When
  22  * removing a reference it is required to drop the refcount (using the same tag that was used
  23  * for that reference). When the refcount drops to zero, the object is removed automaticfally.
  24  *
  25  * In order to maintain backwards compatibility with objects that were created without having
  26  * their refcount increased, the implicit_ref was added. Any object that was created without
  27  * having it's refcount increased (explicitly) is having an implicit refcount of 1. Since
  28  * we don't have a tag for this refcount, we consider this tag as a wildcard. So if the refcount
  29  * is being decreased by an unknown tag and we still have one wildcard tag, we'll accept it
  30  * as the relevant tag, and the refcount will be decreased.
  31  */
  32
  33 void cls_refcount_get(librados::ObjectWriteOperation& op, const string& tag, bool implicit_ref = false);
  34 void cls_refcount_put(librados::ObjectWriteOperation& op, const string& tag, bool implicit_ref = false);
  35 void cls_refcount_set(librados::ObjectWriteOperation& op, list<string>& refs);
  36 int cls_refcount_read(librados::IoCtx& io_ctx, string& oid, list<string> *refs, bool implicit_ref = false);
  37
  38 #endif