ceph/src/include/rados/librados.hpp

   1 #ifndef __LIBRADOS_HPP
   2 #define __LIBRADOS_HPP
   3
   4 #include <string>
   5 #include <list>
   6 #include <map>
   7 #include <memory>
   8 #include <set>
   9 #include <vector>
  10 #include <utility>
  11 #include "buffer.h"
  12
  13 #include "librados.h"
  14 #include "librados_fwd.hpp"
  15 #include "rados_types.hpp"
  16
  17 namespace libradosstriper
  18 {
  19   class RadosStriper;
  20 }
  21
  22 namespace neorados { class RADOS; }
  23
  24 namespace librados {
  25
  26 using ceph::bufferlist;
  27
  28 struct AioCompletionImpl;
  29 struct IoCtxImpl;
  30 struct ListObjectImpl;
  31 class NObjectIteratorImpl;
  32 struct ObjListCtx;
  33 class ObjectOperationImpl;
  34 struct PlacementGroupImpl;
  35 struct PoolAsyncCompletionImpl;
  36
  37 typedef struct rados_cluster_stat_t cluster_stat_t;
  38 typedef struct rados_pool_stat_t pool_stat_t;
  39
  40 typedef void *list_ctx_t;
  41 typedef uint64_t auid_t;
  42 typedef void *config_t;
  43
  44 typedef struct {
  45   std::string client;
  46   std::string cookie;
  47   std::string address;
  48 } locker_t;
  49
  50 typedef std::map<std::string, pool_stat_t> stats_map;
  51
  52 typedef void *completion_t;
  53 typedef void (*callback_t)(completion_t cb, void *arg);
  54
  55 inline namespace v14_2_0 {
  56
  57   class IoCtx;
  58   class RadosClient;
  59
  60   class CEPH_RADOS_API ListObject
  61   {
  62   public:
  63     const std::string& get_nspace() const;
  64     const std::string& get_oid() const;
  65     const std::string& get_locator() const;
  66
  67     ListObject();
  68     ~ListObject();
  69     ListObject( const ListObject&);
  70     ListObject& operator=(const ListObject& rhs);
  71   private:
  72     ListObject(ListObjectImpl *impl);
  73
  74     friend class librados::NObjectIteratorImpl;
  75     friend std::ostream& operator<<(std::ostream& out, const ListObject& lop);
  76
  77     ListObjectImpl *impl;
  78   };
  79   CEPH_RADOS_API std::ostream& operator<<(std::ostream& out, const librados::ListObject& lop);
  80
  81   class CEPH_RADOS_API NObjectIterator;
  82
  83   class CEPH_RADOS_API ObjectCursor
  84   {
  85     public:
  86     ObjectCursor();
  87     ObjectCursor(const ObjectCursor &rhs);
  88     explicit ObjectCursor(rados_object_list_cursor c);
  89     ~ObjectCursor();
  90     ObjectCursor& operator=(const ObjectCursor& rhs);
  91     bool operator<(const ObjectCursor &rhs) const;
  92     bool operator==(const ObjectCursor &rhs) const;
  93     void set(rados_object_list_cursor c);
  94
  95     friend class IoCtx;
  96     friend class librados::NObjectIteratorImpl;
  97     friend std::ostream& operator<<(std::ostream& os, const librados::ObjectCursor& oc);
  98
  99     std::string to_str() const;
 100     bool from_str(const std::string& s);
 101
 102     protected:
 103     rados_object_list_cursor c_cursor;
 104   };
 105   CEPH_RADOS_API std::ostream& operator<<(std::ostream& os, const librados::ObjectCursor& oc);
 106
 107   class CEPH_RADOS_API NObjectIterator {
 108   public:
 109     using iterator_category = std::forward_iterator_tag;
 110     using value_type = ListObject;
 111     using difference_type = std::ptrdiff_t;
 112     using pointer = ListObject*;
 113     using reference = ListObject&;
 114     static const NObjectIterator __EndObjectIterator;
 115     NObjectIterator(): impl(NULL) {}
 116     ~NObjectIterator();
 117     NObjectIterator(const NObjectIterator &rhs);
 118     NObjectIterator& operator=(const NObjectIterator& rhs);
 119
 120     bool operator==(const NObjectIterator& rhs) const;
 121     bool operator!=(const NObjectIterator& rhs) const;
 122     const ListObject& operator*() const;
 123     const ListObject* operator->() const;
 124     NObjectIterator &operator++(); //< Preincrement; errors are thrown as exceptions
 125     NObjectIterator operator++(int); //< Postincrement; errors are thrown as exceptions
 126     friend class IoCtx;
 127     friend class librados::NObjectIteratorImpl;
 128
 129     /// get current hash position of the iterator, rounded to the current pg
 130     uint32_t get_pg_hash_position() const;
 131
 132     /// move the iterator to a given hash position. this may (will!) be rounded
 133     /// to the nearest pg. errors are thrown as exceptions
 134     uint32_t seek(uint32_t pos);
 135
 136     /// move the iterator to a given cursor position. errors are thrown as exceptions
 137     uint32_t seek(const ObjectCursor& cursor);
 138
 139     /// get current cursor position
 140     ObjectCursor get_cursor();
 141
 142     /**
 143      * Configure PGLS filter to be applied OSD-side (requires caller
 144      * to know/understand the format expected by the OSD)
 145      */
 146     void set_filter(const bufferlist &bl);
 147
 148   private:
 149     NObjectIterator(ObjListCtx *ctx_);
 150     void get_next();
 151     NObjectIteratorImpl *impl;
 152   };
 153
 154   class CEPH_RADOS_API ObjectItem
 155   {
 156     public:
 157     std::string oid;
 158     std::string nspace;
 159     std::string locator;
 160   };
 161
 162   /// DEPRECATED; do not use
 163   class CEPH_RADOS_API WatchCtx {
 164   public:
 165     virtual ~WatchCtx();
 166     virtual void notify(uint8_t opcode, uint64_t ver, bufferlist& bl) = 0;
 167   };
 168
 169   class CEPH_RADOS_API WatchCtx2 {
 170   public:
 171     virtual ~WatchCtx2();
 172     /**
 173      * Callback activated when we receive a notify event.
 174      *
 175      * @param notify_id unique id for this notify event
 176      * @param cookie the watcher we are notifying
 177      * @param notifier_id the unique client id of the notifier
 178      * @param bl opaque notify payload (from the notifier)
 179      */
 180     virtual void handle_notify(uint64_t notify_id,
 181                                uint64_t cookie,
 182                                uint64_t notifier_id,
 183                                bufferlist& bl) = 0;
 184
 185     /**
 186      * Callback activated when we encounter an error with the watch.
 187      *
 188      * Errors we may see:
 189      *   -ENOTCONN  : our watch was disconnected
 190      *   -ETIMEDOUT : our watch is still valid, but we may have missed
 191      *                a notify event.
 192      *
 193      * @param cookie the watcher with the problem
 194      * @param err error
 195      */
 196     virtual void handle_error(uint64_t cookie, int err) = 0;
 197   };
 198
 199   struct CEPH_RADOS_API AioCompletion {
 200     AioCompletion(AioCompletionImpl *pc_) : pc(pc_) {}
 201     ~AioCompletion();
 202     int set_complete_callback(void *cb_arg, callback_t cb);
 203     int set_safe_callback(void *cb_arg, callback_t cb)
 204       __attribute__ ((deprecated));
 205     int wait_for_complete();
 206     int wait_for_safe() __attribute__ ((deprecated));
 207     int wait_for_complete_and_cb();
 208     int wait_for_safe_and_cb() __attribute__ ((deprecated));
 209     bool is_complete();
 210     bool is_safe() __attribute__ ((deprecated));
 211     bool is_complete_and_cb();
 212     bool is_safe_and_cb() __attribute__ ((deprecated));
 213     int get_return_value();
 214     int get_version() __attribute__ ((deprecated));
 215     uint64_t get_version64();
 216     void release();
 217     AioCompletionImpl *pc;
 218   };
 219
 220   struct CEPH_RADOS_API PoolAsyncCompletion {
 221     PoolAsyncCompletion(PoolAsyncCompletionImpl *pc_) : pc(pc_) {}
 222     ~PoolAsyncCompletion();
 223     int set_callback(void *cb_arg, callback_t cb);
 224     int wait();
 225     bool is_complete();
 226     int get_return_value();
 227     void release();
 228     PoolAsyncCompletionImpl *pc;
 229   };
 230
 231   /**
 232    * These are per-op flags which may be different among
 233    * ops added to an ObjectOperation.
 234    */
 235   enum ObjectOperationFlags {
 236     OP_EXCL =   LIBRADOS_OP_FLAG_EXCL,
 237     OP_FAILOK = LIBRADOS_OP_FLAG_FAILOK,
 238     OP_FADVISE_RANDOM = LIBRADOS_OP_FLAG_FADVISE_RANDOM,
 239     OP_FADVISE_SEQUENTIAL = LIBRADOS_OP_FLAG_FADVISE_SEQUENTIAL,
 240     OP_FADVISE_WILLNEED = LIBRADOS_OP_FLAG_FADVISE_WILLNEED,
 241     OP_FADVISE_DONTNEED = LIBRADOS_OP_FLAG_FADVISE_DONTNEED,
 242     OP_FADVISE_NOCACHE = LIBRADOS_OP_FLAG_FADVISE_NOCACHE,
 243   };
 244
 245   class CEPH_RADOS_API ObjectOperationCompletion {
 246   public:
 247     virtual ~ObjectOperationCompletion() {}
 248     virtual void handle_completion(int r, bufferlist& outbl) = 0;
 249   };
 250
 251   /**
 252    * These flags apply to the ObjectOperation as a whole.
 253    *
 254    * Prior to octopus BALANCE_READS and LOCALIZE_READS should only
 255    * be used when reading from data you're certain won't change, like
 256    * a snapshot, or where eventual consistency is ok.  Since octopus
 257    * (get_min_compatible_osd() >= CEPH_RELEASE_OCTOPUS) both are safe
 258    * for general use.
 259    *
 260    * ORDER_READS_WRITES will order reads the same way writes are
 261    * ordered (e.g., waiting for degraded objects).  In particular, it
 262    * will make a write followed by a read sequence be preserved.
 263    *
 264    * IGNORE_CACHE will skip the caching logic on the OSD that normally
 265    * handles promotion of objects between tiers.  This allows an operation
 266    * to operate (or read) the cached (or uncached) object, even if it is
 267    * not coherent.
 268    *
 269    * IGNORE_OVERLAY will ignore the pool overlay tiering metadata and
 270    * process the op directly on the destination pool.  This is useful
 271    * for CACHE_FLUSH and CACHE_EVICT operations.
 272    */
 273   enum ObjectOperationGlobalFlags {
 274     OPERATION_NOFLAG             = LIBRADOS_OPERATION_NOFLAG,
 275     OPERATION_BALANCE_READS      = LIBRADOS_OPERATION_BALANCE_READS,
 276     OPERATION_LOCALIZE_READS     = LIBRADOS_OPERATION_LOCALIZE_READS,
 277     OPERATION_ORDER_READS_WRITES = LIBRADOS_OPERATION_ORDER_READS_WRITES,
 278     OPERATION_IGNORE_CACHE       = LIBRADOS_OPERATION_IGNORE_CACHE,
 279     OPERATION_SKIPRWLOCKS        = LIBRADOS_OPERATION_SKIPRWLOCKS,
 280     OPERATION_IGNORE_OVERLAY     = LIBRADOS_OPERATION_IGNORE_OVERLAY,
 281     // send requests to cluster despite the cluster or pool being
 282     // marked full; ops will either succeed (e.g., delete) or return
 283     // EDQUOT or ENOSPC
 284     OPERATION_FULL_TRY           = LIBRADOS_OPERATION_FULL_TRY,
 285     // mainly for delete
 286     OPERATION_FULL_FORCE         = LIBRADOS_OPERATION_FULL_FORCE,
 287     OPERATION_IGNORE_REDIRECT    = LIBRADOS_OPERATION_IGNORE_REDIRECT,
 288     OPERATION_ORDERSNAP          = LIBRADOS_OPERATION_ORDERSNAP,
 289     // enable/allow return value and per-op return code/buffers
 290     OPERATION_RETURNVEC          = LIBRADOS_OPERATION_RETURNVEC,
 291   };
 292
 293   /*
 294    * Alloc hint flags for the alloc_hint operation.
 295    */
 296   enum AllocHintFlags {
 297     ALLOC_HINT_FLAG_SEQUENTIAL_WRITE = 1,
 298     ALLOC_HINT_FLAG_RANDOM_WRITE = 2,
 299     ALLOC_HINT_FLAG_SEQUENTIAL_READ = 4,
 300     ALLOC_HINT_FLAG_RANDOM_READ = 8,
 301     ALLOC_HINT_FLAG_APPEND_ONLY = 16,
 302     ALLOC_HINT_FLAG_IMMUTABLE = 32,
 303     ALLOC_HINT_FLAG_SHORTLIVED = 64,
 304     ALLOC_HINT_FLAG_LONGLIVED = 128,
 305     ALLOC_HINT_FLAG_COMPRESSIBLE = 256,
 306     ALLOC_HINT_FLAG_INCOMPRESSIBLE = 512,
 307   };
 308
 309   /*
 310    * ObjectOperation : compound object operation
 311    * Batch multiple object operations into a single request, to be applied
 312    * atomically.
 313    */
 314   class CEPH_RADOS_API ObjectOperation
 315   {
 316   public:
 317     ObjectOperation();
 318     virtual ~ObjectOperation();
 319
 320     ObjectOperation(const ObjectOperation&) = delete;
 321     ObjectOperation& operator=(const ObjectOperation&) = delete;
 322
 323     /**
 324      * Move constructor.
 325      * \warning A moved from ObjectOperation is invalid and may not be used for
 326      *          any purpose. This is a hard contract violation and will
 327      *          kill your program.
 328      */
 329     ObjectOperation(ObjectOperation&&);
 330     ObjectOperation& operator =(ObjectOperation&&);
 331
 332     size_t size();
 333     void set_op_flags(ObjectOperationFlags flags) __attribute__((deprecated));
 334     //flag mean ObjectOperationFlags
 335     void set_op_flags2(int flags);
 336
 337     void cmpext(uint64_t off, const bufferlist& cmp_bl, int *prval);
 338     void cmpxattr(const char *name, uint8_t op, const bufferlist& val);
 339     void cmpxattr(const char *name, uint8_t op, uint64_t v);
 340     void exec(const char *cls, const char *method, bufferlist& inbl);
 341     void exec(const char *cls, const char *method, bufferlist& inbl, bufferlist *obl, int *prval);
 342     void exec(const char *cls, const char *method, bufferlist& inbl, ObjectOperationCompletion *completion);
 343     /**
 344      * Guard operation with a check that object version == ver
 345      *
 346      * @param ver [in] version to check
 347      */
 348     void assert_version(uint64_t ver);
 349
 350     /**
 351      * Guard operation with a check that the object already exists
 352      */
 353     void assert_exists();
 354
 355     /**
 356      * get key/value pairs for specified keys
 357      *
 358      * @param assertions [in] comparison assertions
 359      * @param prval [out] place error code in prval upon completion
 360      *
 361      * assertions has the form of mappings from keys to (comparison rval, assertion)
 362      * The assertion field may be CEPH_OSD_CMPXATTR_OP_[GT|LT|EQ].
 363      *
 364      * That is, to assert that the value at key 'foo' is greater than 'bar':
 365      *
 366      * ObjectReadOperation op;
 367      * int r;
 368      * map<string, pair<bufferlist, int> > assertions;
 369      * bufferlist bar(string('bar'));
 370      * assertions['foo'] = make_pair(bar, CEPH_OSD_CMP_XATTR_OP_GT);
 371      * op.omap_cmp(assertions, &r);
 372      */
 373     void omap_cmp(
 374       const std::map<std::string, std::pair<bufferlist, int> > &assertions,
 375       int *prval);
 376
 377   protected:
 378     ObjectOperationImpl* impl;
 379     friend class IoCtx;
 380     friend class Rados;
 381   };
 382
 383   /*
 384    * ObjectWriteOperation : compound object write operation
 385    * Batch multiple object operations into a single request, to be applied
 386    * atomically.
 387    */
 388   class CEPH_RADOS_API ObjectWriteOperation : public ObjectOperation
 389   {
 390   protected:
 391     time_t *unused;
 392   public:
 393     ObjectWriteOperation() : unused(NULL) {}
 394     ~ObjectWriteOperation() override {}
 395
 396     ObjectWriteOperation(ObjectWriteOperation&&) = default;
 397     ObjectWriteOperation& operator =(ObjectWriteOperation&&) = default;
 398
 399     void mtime(time_t *pt);
 400     void mtime2(struct timespec *pts);
 401
 402     void create(bool exclusive);
 403     void create(bool exclusive,
 404                 const std::string& category); ///< NOTE: category is unused
 405
 406     void write(uint64_t off, const bufferlist& bl);
 407     void write_full(const bufferlist& bl);
 408     void writesame(uint64_t off, uint64_t write_len,
 409                    const bufferlist& bl);
 410     void append(const bufferlist& bl);
 411     void remove();
 412     void truncate(uint64_t off);
 413     void zero(uint64_t off, uint64_t len);
 414     void rmxattr(const char *name);
 415     void setxattr(const char *name, const bufferlist& bl);
 416     void setxattr(const char *name, const bufferlist&& bl);
 417     void tmap_update(const bufferlist& cmdbl);
 418     void tmap_put(const bufferlist& bl);
 419     void selfmanaged_snap_rollback(uint64_t snapid);
 420
 421     /**
 422      * Rollback an object to the specified snapshot id
 423      *
 424      * Used with pool snapshots
 425      *
 426      * @param snapid [in] snopshot id specified
 427      */
 428     void snap_rollback(uint64_t snapid);
 429
 430     /**
 431      * set keys and values according to map
 432      *
 433      * @param map [in] keys and values to set
 434      */
 435     void omap_set(const std::map<std::string, bufferlist> &map);
 436
 437     /**
 438      * set header
 439      *
 440      * @param bl [in] header to set
 441      */
 442     void omap_set_header(const bufferlist &bl);
 443
 444     /**
 445      * Clears omap contents
 446      */
 447     void omap_clear();
 448
 449     /**
 450      * Clears keys in to_rm
 451      *
 452      * @param to_rm [in] keys to remove
 453      */
 454     void omap_rm_keys(const std::set<std::string> &to_rm);
 455
 456     /**
 457      * Copy an object
 458      *
 459      * Copies an object from another location.  The operation is atomic in that
 460      * the copy either succeeds in its entirety or fails (e.g., because the
 461      * source object was modified while the copy was in progress).
 462      *
 463      * @param src source object name
 464      * @param src_ioctx ioctx for the source object
 465      * @param src_version current version of the source object
 466      * @param src_fadvise_flags the fadvise flags for source object
 467      */
 468     void copy_from(const std::string& src, const IoCtx& src_ioctx,
 469                    uint64_t src_version, uint32_t src_fadvise_flags);
 470
 471     /**
 472      * Copy an object
 473      *
 474      * Copies an object from another location.  The operation is atomic in that
 475      * the copy either succeeds in its entirety or fails (e.g., because the
 476      * source object was modified while the copy was in progress).  Instead of
 477      * copying truncate_seq and truncate_size from the source object it receives
 478      * these values as parameters.
 479      *
 480      * @param src source object name
 481      * @param src_ioctx ioctx for the source object
 482      * @param src_version current version of the source object
 483      * @param truncate_seq truncate sequence for the destination object
 484      * @param truncate_size truncate size for the destination object
 485      * @param src_fadvise_flags the fadvise flags for source object
 486      */
 487     void copy_from2(const std::string& src, const IoCtx& src_ioctx,
 488                     uint64_t src_version, uint32_t truncate_seq,
 489                     uint64_t truncate_size, uint32_t src_fadvise_flags);
 490
 491     /**
 492      * undirty an object
 493      *
 494      * Clear an objects dirty flag
 495      */
 496     void undirty();
 497
 498     /**
 499      * Set allocation hint for an object
 500      *
 501      * @param expected_object_size expected size of the object, in bytes
 502      * @param expected_write_size expected size of writes to the object, in bytes
 503      * @param flags flags ()
 504      */
 505     void set_alloc_hint(uint64_t expected_object_size,
 506                         uint64_t expected_write_size);
 507     void set_alloc_hint2(uint64_t expected_object_size,
 508                          uint64_t expected_write_size,
 509                          uint32_t flags);
 510
 511     /**
 512      * Pin/unpin an object in cache tier
 513      *
 514      * @returns 0 on success, negative error code on failure
 515      */
 516     void cache_pin();
 517     void cache_unpin();
 518
 519     /**
 520      * Extensible tier
 521      *
 522      * Set redirect target
 523      */
 524     void set_redirect(const std::string& tgt_obj, const IoCtx& tgt_ioctx,
 525                       uint64_t tgt_version, int flag = 0);
 526     void tier_promote();
 527     void unset_manifest();
 528
 529     friend class IoCtx;
 530   };
 531
 532   /*
 533    * ObjectReadOperation : compound object operation that return value
 534    * Batch multiple object operations into a single request, to be applied
 535    * atomically.
 536    */
 537   class CEPH_RADOS_API ObjectReadOperation : public ObjectOperation
 538   {
 539   public:
 540     ObjectReadOperation() {}
 541     ~ObjectReadOperation() override {}
 542
 543     ObjectReadOperation(ObjectReadOperation&&) = default;
 544     ObjectReadOperation& operator =(ObjectReadOperation&&) = default;
 545
 546     void stat(uint64_t *psize, time_t *pmtime, int *prval);
 547     void stat2(uint64_t *psize, struct timespec *pts, int *prval);
 548     void getxattr(const char *name, bufferlist *pbl, int *prval);
 549     void getxattrs(std::map<std::string, bufferlist> *pattrs, int *prval);
 550     void read(size_t off, uint64_t len, bufferlist *pbl, int *prval);
 551     void checksum(rados_checksum_type_t type, const bufferlist &init_value_bl,
 552                   uint64_t off, size_t len, size_t chunk_size, bufferlist *pbl,
 553                   int *prval);
 554
 555     /**
 556      * see aio_sparse_read()
 557      */
 558     void sparse_read(uint64_t off, uint64_t len, std::map<uint64_t,uint64_t> *m,
 559                      bufferlist *data_bl, int *prval,
 560                      uint64_t truncate_size = 0,
 561                      uint32_t truncate_seq = 0);
 562
 563     /**
 564      * omap_get_vals: keys and values from the object omap
 565      *
 566      * Get up to max_return keys and values beginning after start_after
 567      *
 568      * @param start_after [in] list no keys smaller than start_after
 569      * @param max_return [in] list no more than max_return key/value pairs
 570      * @param out_vals [out] place returned values in out_vals on completion
 571      * @param prval [out] place error code in prval upon completion
 572      */
 573     void omap_get_vals(
 574       const std::string &start_after,
 575       uint64_t max_return,
 576       std::map<std::string, bufferlist> *out_vals,
 577       int *prval) __attribute__ ((deprecated));  // use v2
 578
 579     /**
 580      * omap_get_vals: keys and values from the object omap
 581      *
 582      * Get up to max_return keys and values beginning after start_after
 583      *
 584      * @param start_after [in] list no keys smaller than start_after
 585      * @param max_return [in] list no more than max_return key/value pairs
 586      * @param out_vals [out] place returned values in out_vals on completion
 587      * @param prval [out] place error code in prval upon completion
 588      */
 589     void omap_get_vals2(
 590       const std::string &start_after,
 591       uint64_t max_return,
 592       std::map<std::string, bufferlist> *out_vals,
 593       bool *pmore,
 594       int *prval);
 595
 596     /**
 597      * omap_get_vals: keys and values from the object omap
 598      *
 599      * Get up to max_return keys and values beginning after start_after
 600      *
 601      * @param start_after [in] list keys starting after start_after
 602      * @param filter_prefix [in] list only keys beginning with filter_prefix
 603      * @param max_return [in] list no more than max_return key/value pairs
 604      * @param out_vals [out] place returned values in out_vals on completion
 605      * @param prval [out] place error code in prval upon completion
 606      */
 607     void omap_get_vals(
 608       const std::string &start_after,
 609       const std::string &filter_prefix,
 610       uint64_t max_return,
 611       std::map<std::string, bufferlist> *out_vals,
 612       int *prval) __attribute__ ((deprecated));  // use v2
 613
 614     /**
 615      * omap_get_vals2: keys and values from the object omap
 616      *
 617      * Get up to max_return keys and values beginning after start_after
 618      *
 619      * @param start_after [in] list keys starting after start_after
 620      * @param filter_prefix [in] list only keys beginning with filter_prefix
 621      * @param max_return [in] list no more than max_return key/value pairs
 622      * @param out_vals [out] place returned values in out_vals on completion
 623      * @param pmore [out] pointer to bool indicating whether there are more keys
 624      * @param prval [out] place error code in prval upon completion
 625      */
 626     void omap_get_vals2(
 627       const std::string &start_after,
 628       const std::string &filter_prefix,
 629       uint64_t max_return,
 630       std::map<std::string, bufferlist> *out_vals,
 631       bool *pmore,
 632       int *prval);
 633
 634
 635     /**
 636      * omap_get_keys: keys from the object omap
 637      *
 638      * Get up to max_return keys beginning after start_after
 639      *
 640      * @param start_after [in] list keys starting after start_after
 641      * @param max_return [in] list no more than max_return keys
 642      * @param out_keys [out] place returned values in out_keys on completion
 643      * @param prval [out] place error code in prval upon completion
 644      */
 645     void omap_get_keys(const std::string &start_after,
 646                        uint64_t max_return,
 647                        std::set<std::string> *out_keys,
 648                        int *prval) __attribute__ ((deprecated)); // use v2
 649
 650     /**
 651      * omap_get_keys2: keys from the object omap
 652      *
 653      * Get up to max_return keys beginning after start_after
 654      *
 655      * @param start_after [in] list keys starting after start_after
 656      * @param max_return [in] list no more than max_return keys
 657      * @param out_keys [out] place returned values in out_keys on completion
 658      * @param pmore [out] pointer to bool indicating whether there are more keys
 659      * @param prval [out] place error code in prval upon completion
 660      */
 661     void omap_get_keys2(const std::string &start_after,
 662                         uint64_t max_return,
 663                         std::set<std::string> *out_keys,
 664                         bool *pmore,
 665                         int *prval);
 666
 667     /**
 668      * omap_get_header: get header from object omap
 669      *
 670      * @param header [out] place header here upon completion
 671      * @param prval [out] place error code in prval upon completion
 672      */
 673     void omap_get_header(bufferlist *header, int *prval);
 674
 675     /**
 676      * get key/value pairs for specified keys
 677      *
 678      * @param keys [in] keys to get
 679      * @param map [out] place key/value pairs found here on completion
 680      * @param prval [out] place error code in prval upon completion
 681      */
 682     void omap_get_vals_by_keys(const std::set<std::string> &keys,
 683                                std::map<std::string, bufferlist> *map,
 684                                int *prval);
 685
 686     /**
 687      * list_watchers: Get list watchers of object
 688      *
 689      * @param out_watchers [out] place returned values in out_watchers on completion
 690      * @param prval [out] place error code in prval upon completion
 691      */
 692     void list_watchers(std::list<obj_watch_t> *out_watchers, int *prval);
 693
 694     /**
 695      * list snapshot clones associated with a logical object
 696      *
 697      * This will include a record for each version of the object,
 698      * include the "HEAD" (which will have a cloneid of SNAP_HEAD).
 699      * Each clone includes a vector of snap ids for which it is
 700      * defined to exist.
 701      *
 702      * NOTE: this operation must be submitted from an IoCtx with a
 703      * read snapid of SNAP_DIR for reliable results.
 704      *
 705      * @param out_snaps [out] pointer to resulting snap_set_t
 706      * @param prval [out] place error code in prval upon completion
 707      */
 708     void list_snaps(snap_set_t *out_snaps, int *prval);
 709
 710     /**
 711      * query dirty state of an object
 712      *
 713      * @param isdirty [out] pointer to resulting bool
 714      * @param prval [out] place error code in prval upon completion
 715      */
 716     void is_dirty(bool *isdirty, int *prval);
 717
 718     /**
 719      * flush a cache tier object to backing tier; will block racing
 720      * updates.
 721      *
 722      * This should be used in concert with OPERATION_IGNORE_CACHE to avoid
 723      * triggering a promotion.
 724      */
 725     void cache_flush();
 726
 727     /**
 728      * Flush a cache tier object to backing tier; will EAGAIN if we race
 729      * with an update.  Must be used with the SKIPRWLOCKS flag.
 730      *
 731      * This should be used in concert with OPERATION_IGNORE_CACHE to avoid
 732      * triggering a promotion.
 733      */
 734     void cache_try_flush();
 735
 736     /**
 737      * evict a clean cache tier object
 738      *
 739      * This should be used in concert with OPERATION_IGNORE_CACHE to avoid
 740      * triggering a promote on the OSD (that is then evicted).
 741      */
 742     void cache_evict();
 743
 744     /**
 745      * Extensible tier
 746      *
 747      * set_chunk: make a chunk pointing a part of the source object at the target
 748      *            object
 749      *
 750      * @param src_offset [in] source offset to indicate the start position of
 751      *                          a chunk in the source object
 752      * @param src_length [in] source length to set the length of the chunk
 753      * @param tgt_oid    [in] target object's id to set a chunk
 754      * @param tgt_offset [in] the start position of the target object
 755      * @param flag       [in] flag for the source object
 756      *
 757      */
 758     void set_chunk(uint64_t src_offset, uint64_t src_length, const IoCtx& tgt_ioctx,
 759                    std::string tgt_oid, uint64_t tgt_offset, int flag = 0);
 760     /**
 761      * flush a manifest tier object to backing tier, performing deduplication;
 762      * will block racing updates.
 763      *
 764      * Invoking tier_flush() implicitly makes a manifest object even if
 765      * the target object is not manifest.
 766      */
 767     void tier_flush();
 768     /**
 769      * evict a manifest tier object to backing tier; will block racing
 770      * updates.
 771      */
 772     void tier_evict();
 773   };
 774
 775   /* IoCtx : This is a context in which we can perform I/O.
 776    * It includes a Pool,
 777    *
 778    * Typical use (error checking omitted):
 779    *
 780    * IoCtx p;
 781    * rados.ioctx_create("my_pool", p);
 782    * p->stat(&stats);
 783    * ... etc ...
 784    *
 785    * NOTE: be sure to call watch_flush() prior to destroying any IoCtx
 786    * that is used for watch events to ensure that racing callbacks
 787    * have completed.
 788    */
 789   class CEPH_RADOS_API IoCtx
 790   {
 791   public:
 792     IoCtx();
 793     static void from_rados_ioctx_t(rados_ioctx_t p, IoCtx &pool);
 794     IoCtx(const IoCtx& rhs);
 795     IoCtx& operator=(const IoCtx& rhs);
 796     IoCtx(IoCtx&& rhs) noexcept;
 797     IoCtx& operator=(IoCtx&& rhs) noexcept;
 798
 799     ~IoCtx();
 800
 801     bool is_valid() const;
 802
 803     // Close our pool handle
 804     void close();
 805
 806     // deep copy
 807     void dup(const IoCtx& rhs);
 808
 809     // set pool auid
 810     int set_auid(uint64_t auid_)
 811       __attribute__ ((deprecated));
 812
 813     // set pool auid
 814     int set_auid_async(uint64_t auid_, PoolAsyncCompletion *c)
 815       __attribute__ ((deprecated));
 816
 817     // get pool auid
 818     int get_auid(uint64_t *auid_)
 819       __attribute__ ((deprecated));
 820
 821     uint64_t get_instance_id() const;
 822
 823     std::string get_pool_name();
 824
 825     bool pool_requires_alignment();
 826     int pool_requires_alignment2(bool * req);
 827     uint64_t pool_required_alignment();
 828     int pool_required_alignment2(uint64_t * alignment);
 829
 830     // create an object
 831     int create(const std::string& oid, bool exclusive);
 832     int create(const std::string& oid, bool exclusive,
 833                const std::string& category); ///< category is unused
 834
 835     /**
 836      * write bytes to an object at a specified offset
 837      *
 838      * NOTE: this call steals the contents of @param bl.
 839      */
 840     int write(const std::string& oid, bufferlist& bl, size_t len, uint64_t off);
 841     /**
 842      * append bytes to an object
 843      *
 844      * NOTE: this call steals the contents of @param bl.
 845      */
 846     int append(const std::string& oid, bufferlist& bl, size_t len);
 847     /**
 848      * replace object contents with provided data
 849      *
 850      * NOTE: this call steals the contents of @param bl.
 851      */
 852     int write_full(const std::string& oid, bufferlist& bl);
 853     int writesame(const std::string& oid, bufferlist& bl,
 854                   size_t write_len, uint64_t off);
 855     int read(const std::string& oid, bufferlist& bl, size_t len, uint64_t off);
 856     int checksum(const std::string& o, rados_checksum_type_t type,
 857                  const bufferlist &init_value_bl, size_t len, uint64_t off,
 858                  size_t chunk_size, bufferlist *pbl);
 859     int remove(const std::string& oid);
 860     int remove(const std::string& oid, int flags);
 861     int trunc(const std::string& oid, uint64_t size);
 862     int mapext(const std::string& o, uint64_t off, size_t len, std::map<uint64_t,uint64_t>& m);
 863     int cmpext(const std::string& o, uint64_t off, bufferlist& cmp_bl);
 864     int sparse_read(const std::string& o, std::map<uint64_t,uint64_t>& m, bufferlist& bl, size_t len, uint64_t off);
 865     int getxattr(const std::string& oid, const char *name, bufferlist& bl);
 866     int getxattrs(const std::string& oid, std::map<std::string, bufferlist>& attrset);
 867     int setxattr(const std::string& oid, const char *name, bufferlist& bl);
 868     int rmxattr(const std::string& oid, const char *name);
 869     int stat(const std::string& oid, uint64_t *psize, time_t *pmtime);
 870     int stat2(const std::string& oid, uint64_t *psize, struct timespec *pts);
 871     int exec(const std::string& oid, const char *cls, const char *method,
 872              bufferlist& inbl, bufferlist& outbl);
 873     /**
 874      * modify object tmap based on encoded update sequence
 875      *
 876      * NOTE: this call steals the contents of @param bl
 877      */
 878     int tmap_update(const std::string& oid, bufferlist& cmdbl);
 879
 880     int omap_get_vals(const std::string& oid,
 881                       const std::string& start_after,
 882                       uint64_t max_return,
 883                       std::map<std::string, bufferlist> *out_vals);
 884     int omap_get_vals2(const std::string& oid,
 885                        const std::string& start_after,
 886                        uint64_t max_return,
 887                        std::map<std::string, bufferlist> *out_vals,
 888                        bool *pmore);
 889     int omap_get_vals(const std::string& oid,
 890                       const std::string& start_after,
 891                       const std::string& filter_prefix,
 892                       uint64_t max_return,
 893                       std::map<std::string, bufferlist> *out_vals);
 894     int omap_get_vals2(const std::string& oid,
 895                        const std::string& start_after,
 896                        const std::string& filter_prefix,
 897                        uint64_t max_return,
 898                        std::map<std::string, bufferlist> *out_vals,
 899                        bool *pmore);
 900     int omap_get_keys(const std::string& oid,
 901                       const std::string& start_after,
 902                       uint64_t max_return,
 903                       std::set<std::string> *out_keys);
 904     int omap_get_keys2(const std::string& oid,
 905                        const std::string& start_after,
 906                        uint64_t max_return,
 907                        std::set<std::string> *out_keys,
 908                        bool *pmore);
 909     int omap_get_header(const std::string& oid,
 910                         bufferlist *bl);
 911     int omap_get_vals_by_keys(const std::string& oid,
 912                               const std::set<std::string>& keys,
 913                               std::map<std::string, bufferlist> *vals);
 914     int omap_set(const std::string& oid,
 915                  const std::map<std::string, bufferlist>& map);
 916     int omap_set_header(const std::string& oid,
 917                         const bufferlist& bl);
 918     int omap_clear(const std::string& oid);
 919     int omap_rm_keys(const std::string& oid,
 920                      const std::set<std::string>& keys);
 921
 922     void snap_set_read(snap_t seq);
 923     int selfmanaged_snap_set_write_ctx(snap_t seq, std::vector<snap_t>& snaps);
 924
 925     // Create a snapshot with a given name
 926     int snap_create(const char *snapname);
 927
 928     // Look up a snapshot by name.
 929     // Returns 0 on success; error code otherwise
 930     int snap_lookup(const char *snapname, snap_t *snap);
 931
 932     // Gets a timestamp for a snap
 933     int snap_get_stamp(snap_t snapid, time_t *t);
 934
 935     // Gets the name of a snap
 936     int snap_get_name(snap_t snapid, std::string *s);
 937
 938     // Remove a snapshot from this pool
 939     int snap_remove(const char *snapname);
 940
 941     int snap_list(std::vector<snap_t> *snaps);
 942
 943     int snap_rollback(const std::string& oid, const char *snapname);
 944
 945     // Deprecated name kept for backward compatibility - same as snap_rollback()
 946     int rollback(const std::string& oid, const char *snapname)
 947       __attribute__ ((deprecated));
 948
 949     int selfmanaged_snap_create(uint64_t *snapid);
 950     void aio_selfmanaged_snap_create(uint64_t *snapid, AioCompletion *c);
 951
 952     int selfmanaged_snap_remove(uint64_t snapid);
 953     void aio_selfmanaged_snap_remove(uint64_t snapid, AioCompletion *c);
 954
 955     int selfmanaged_snap_rollback(const std::string& oid, uint64_t snapid);
 956
 957     // Advisory locking on rados objects.
 958     int lock_exclusive(const std::string &oid, const std::string &name,
 959                        const std::string &cookie,
 960                        const std::string &description,
 961                        struct timeval * duration, uint8_t flags);
 962
 963     int lock_shared(const std::string &oid, const std::string &name,
 964                     const std::string &cookie, const std::string &tag,
 965                     const std::string &description,
 966                     struct timeval * duration, uint8_t flags);
 967
 968     int unlock(const std::string &oid, const std::string &name,
 969                const std::string &cookie);
 970
 971     int break_lock(const std::string &oid, const std::string &name,
 972                    const std::string &client, const std::string &cookie);
 973
 974     int list_lockers(const std::string &oid, const std::string &name,
 975                      int *exclusive,
 976                      std::string *tag,
 977                      std::list<librados::locker_t> *lockers);
 978
 979
 980     /// Start enumerating objects for a pool. Errors are thrown as exceptions.
 981     NObjectIterator nobjects_begin(const bufferlist &filter=bufferlist());
 982     /// Start enumerating objects for a pool starting from a hash position.
 983     /// Errors are thrown as exceptions.
 984     NObjectIterator nobjects_begin(uint32_t start_hash_position,
 985                                    const bufferlist &filter=bufferlist());
 986     /// Start enumerating objects for a pool starting from cursor. Errors are
 987     /// thrown as exceptions.
 988     NObjectIterator nobjects_begin(const librados::ObjectCursor& cursor,
 989                                    const bufferlist &filter=bufferlist());
 990     /// Iterator indicating the end of a pool
 991     const NObjectIterator& nobjects_end() const;
 992
 993     /// Get cursor for pool beginning
 994     ObjectCursor object_list_begin();
 995
 996     /// Get cursor for pool end
 997     ObjectCursor object_list_end();
 998
 999     /// Check whether a cursor is at the end of a pool
1000     bool object_list_is_end(const ObjectCursor &oc);
1001
1002     /// List some objects between two cursors
1003     int object_list(const ObjectCursor &start, const ObjectCursor &finish,
1004                     const size_t result_count,
1005                     const bufferlist &filter,
1006                     std::vector<ObjectItem> *result,
1007                     ObjectCursor *next);
1008
1009     /// Generate cursors that include the N out of Mth slice of the pool
1010     void object_list_slice(
1011         const ObjectCursor start,
1012         const ObjectCursor finish,
1013         const size_t n,
1014         const size_t m,
1015         ObjectCursor *split_start,
1016         ObjectCursor *split_finish);
1017
1018     /**
1019      * List available hit set objects
1020      *
1021      * @param uint32_t [in] hash position to query
1022      * @param c [in] completion
1023      * @param pls [out] list of available intervals
1024      */
1025     int hit_set_list(uint32_t hash, AioCompletion *c,
1026                      std::list< std::pair<time_t, time_t> > *pls);
1027
1028     /**
1029      * Retrieve hit set for a given hash, and time
1030      *
1031      * @param hash [in] hash position
1032      * @param c [in] completion
1033      * @param stamp [in] time interval that falls within the hit set's interval
1034      * @param pbl [out] buffer to store the result in
1035      */
1036     int hit_set_get(uint32_t hash, AioCompletion *c, time_t stamp,
1037                     bufferlist *pbl);
1038
1039     uint64_t get_last_version();
1040
1041     int aio_read(const std::string& oid, AioCompletion *c,
1042                  bufferlist *pbl, size_t len, uint64_t off);
1043     /**
1044      * Asynchronously read from an object at a particular snapshot
1045      *
1046      * This is the same as normal aio_read, except that it chooses
1047      * the snapshot to read from from its arguments instead of the
1048      * internal IoCtx state.
1049      *
1050      * The return value of the completion will be number of bytes read on
1051      * success, negative error code on failure.
1052      *
1053      * @param oid the name of the object to read from
1054      * @param c what to do when the read is complete
1055      * @param pbl where to store the results
1056      * @param len the number of bytes to read
1057      * @param off the offset to start reading from in the object
1058      * @param snapid the id of the snapshot to read from
1059      * @returns 0 on success, negative error code on failure
1060      */
1061     int aio_read(const std::string& oid, AioCompletion *c,
1062                  bufferlist *pbl, size_t len, uint64_t off, uint64_t snapid);
1063     int aio_sparse_read(const std::string& oid, AioCompletion *c,
1064                         std::map<uint64_t,uint64_t> *m, bufferlist *data_bl,
1065                         size_t len, uint64_t off);
1066     /**
1067      * Asynchronously read existing extents from an object at a
1068      * particular snapshot
1069      *
1070      * This is the same as normal aio_sparse_read, except that it chooses
1071      * the snapshot to read from from its arguments instead of the
1072      * internal IoCtx state.
1073      *
1074      * m will be filled in with a map of extents in the object,
1075      * mapping offsets to lengths (in bytes) within the range
1076      * requested. The data for all of the extents are stored
1077      * back-to-back in offset order in data_bl.
1078      *
1079      * @param oid the name of the object to read from
1080      * @param c what to do when the read is complete
1081      * @param m where to store the map of extents
1082      * @param data_bl where to store the data
1083      * @param len the number of bytes to read
1084      * @param off the offset to start reading from in the object
1085      * @param snapid the id of the snapshot to read from
1086      * @returns 0 on success, negative error code on failure
1087      */
1088     int aio_sparse_read(const std::string& oid, AioCompletion *c,
1089                         std::map<uint64_t,uint64_t> *m, bufferlist *data_bl,
1090                         size_t len, uint64_t off, uint64_t snapid);
1091     /**
1092      * Asynchronously compare an on-disk object range with a buffer
1093      *
1094      * @param oid the name of the object to read from
1095      * @param c what to do when the read is complete
1096      * @param off object byte offset at which to start the comparison
1097      * @param cmp_bl buffer containing bytes to be compared with object contents
1098      * @returns 0 on success, negative error code on failure,
1099      *  (-MAX_ERRNO - mismatch_off) on mismatch
1100      */
1101     int aio_cmpext(const std::string& oid,
1102                    librados::AioCompletion *c,
1103                    uint64_t off,
1104                    bufferlist& cmp_bl);
1105     int aio_write(const std::string& oid, AioCompletion *c, const bufferlist& bl,
1106                   size_t len, uint64_t off);
1107     int aio_append(const std::string& oid, AioCompletion *c, const bufferlist& bl,
1108                   size_t len);
1109     int aio_write_full(const std::string& oid, AioCompletion *c, const bufferlist& bl);
1110     int aio_writesame(const std::string& oid, AioCompletion *c, const bufferlist& bl,
1111                       size_t write_len, uint64_t off);
1112
1113     /**
1114      * Asynchronously remove an object
1115      *
1116      * Queues the remove and returns.
1117      *
1118      * The return value of the completion will be 0 on success, negative
1119      * error code on failure.
1120      *
1121      * @param oid the name of the object
1122      * @param c what to do when the remove is safe and complete
1123      * @returns 0 on success, -EROFS if the io context specifies a snap_seq
1124      * other than SNAP_HEAD
1125      */
1126     int aio_remove(const std::string& oid, AioCompletion *c);
1127     int aio_remove(const std::string& oid, AioCompletion *c, int flags);
1128
1129     /**
1130      * Wait for all currently pending aio writes to be safe.
1131      *
1132      * @returns 0 on success, negative error code on failure
1133      */
1134     int aio_flush();
1135
1136     /**
1137      * Schedule a callback for when all currently pending
1138      * aio writes are safe. This is a non-blocking version of
1139      * aio_flush().
1140      *
1141      * @param c what to do when the writes are safe
1142      * @returns 0 on success, negative error code on failure
1143      */
1144     int aio_flush_async(AioCompletion *c);
1145     int aio_getxattr(const std::string& oid, AioCompletion *c, const char *name, bufferlist& bl);
1146     int aio_getxattrs(const std::string& oid, AioCompletion *c, std::map<std::string, bufferlist>& attrset);
1147     int aio_setxattr(const std::string& oid, AioCompletion *c, const char *name, bufferlist& bl);
1148     int aio_rmxattr(const std::string& oid, AioCompletion *c, const char *name);
1149     int aio_stat(const std::string& oid, AioCompletion *c, uint64_t *psize, time_t *pmtime);
1150     int aio_stat2(const std::string& oid, AioCompletion *c, uint64_t *psize, struct timespec *pts);
1151
1152     /**
1153      * Cancel aio operation
1154      *
1155      * @param c completion handle
1156      * @returns 0 on success, negative error code on failure
1157      */
1158     int aio_cancel(AioCompletion *c);
1159
1160     int aio_exec(const std::string& oid, AioCompletion *c, const char *cls, const char *method,
1161                  bufferlist& inbl, bufferlist *outbl);
1162
1163     /*
1164      * asynchronous version of unlock
1165      */
1166     int aio_unlock(const std::string &oid, const std::string &name,
1167                    const std::string &cookie, AioCompletion *c);
1168
1169     // compound object operations
1170     int operate(const std::string& oid, ObjectWriteOperation *op);
1171     int operate(const std::string& oid, ObjectWriteOperation *op, int flags);
1172     int operate(const std::string& oid, ObjectReadOperation *op, bufferlist *pbl);
1173     int operate(const std::string& oid, ObjectReadOperation *op, bufferlist *pbl, int flags);
1174     int aio_operate(const std::string& oid, AioCompletion *c, ObjectWriteOperation *op);
1175     int aio_operate(const std::string& oid, AioCompletion *c, ObjectWriteOperation *op, int flags);
1176     /**
1177      * Schedule an async write operation with explicit snapshot parameters
1178      *
1179      * This is the same as the first aio_operate(), except that it
1180      * gets the snapshot context from its arguments instead of the
1181      * IoCtx internal state.
1182      *
1183      * @param oid the object to operate on
1184      * @param c what to do when the operation is complete and safe
1185      * @param op which operations to perform
1186      * @param seq latest selfmanaged snapshot sequence number for this object
1187      * @param snaps currently existing selfmanaged snapshot ids for this object
1188      * @returns 0 on success, negative error code on failure
1189      */
1190     int aio_operate(const std::string& oid, AioCompletion *c,
1191                     ObjectWriteOperation *op, snap_t seq,
1192                     std::vector<snap_t>& snaps);
1193     int aio_operate(const std::string& oid, AioCompletion *c,
1194         ObjectWriteOperation *op, snap_t seq,
1195         std::vector<snap_t>& snaps,
1196         const blkin_trace_info *trace_info);
1197     int aio_operate(const std::string& oid, AioCompletion *c,
1198         ObjectWriteOperation *op, snap_t seq,
1199         std::vector<snap_t>& snaps, int flags,
1200         const blkin_trace_info *trace_info);
1201     int aio_operate(const std::string& oid, AioCompletion *c,
1202                     ObjectReadOperation *op, bufferlist *pbl);
1203
1204     int aio_operate(const std::string& oid, AioCompletion *c,
1205                     ObjectReadOperation *op, snap_t snapid, int flags,
1206                     bufferlist *pbl)
1207       __attribute__ ((deprecated));
1208
1209     int aio_operate(const std::string& oid, AioCompletion *c,
1210                     ObjectReadOperation *op, int flags,
1211                     bufferlist *pbl);
1212     int aio_operate(const std::string& oid, AioCompletion *c,
1213         ObjectReadOperation *op, int flags,
1214         bufferlist *pbl, const blkin_trace_info *trace_info);
1215
1216     // watch/notify
1217     int watch2(const std::string& o, uint64_t *handle,
1218                librados::WatchCtx2 *ctx);
1219     int watch3(const std::string& o, uint64_t *handle,
1220                librados::WatchCtx2 *ctx, uint32_t timeout);
1221     int aio_watch(const std::string& o, AioCompletion *c, uint64_t *handle,
1222                librados::WatchCtx2 *ctx);
1223     int aio_watch2(const std::string& o, AioCompletion *c, uint64_t *handle,
1224                librados::WatchCtx2 *ctx, uint32_t timeout);
1225     int unwatch2(uint64_t handle);
1226     int aio_unwatch(uint64_t handle, AioCompletion *c);
1227     /**
1228      * Send a notify event to watchers
1229      *
1230      * Upon completion the pbl bufferlist reply payload will be
1231      * encoded like so:
1232      *
1233      *    le32 num_acks
1234      *    {
1235      *      le64 gid     global id for the client (for client.1234 that's 1234)
1236      *      le64 cookie  cookie for the client
1237      *      le32 buflen  length of reply message buffer
1238      *      u8 * buflen  payload
1239      *    } * num_acks
1240      *    le32 num_timeouts
1241      *    {
1242      *      le64 gid     global id for the client
1243      *      le64 cookie  cookie for the client
1244      *    } * num_timeouts
1245      *
1246      *
1247      */
1248     int notify2(const std::string& o,   ///< object
1249                 bufferlist& bl,         ///< optional broadcast payload
1250                 uint64_t timeout_ms,    ///< timeout (in ms)
1251                 bufferlist *pbl);       ///< reply buffer
1252     int aio_notify(const std::string& o,   ///< object
1253                    AioCompletion *c,       ///< completion when notify completes
1254                    bufferlist& bl,         ///< optional broadcast payload
1255                    uint64_t timeout_ms,    ///< timeout (in ms)
1256                    bufferlist *pbl);       ///< reply buffer
1257    /*
1258     * Decode a notify response into acks and timeout vectors.
1259     */
1260     void decode_notify_response(bufferlist &bl,
1261                                 std::vector<librados::notify_ack_t> *acks,
1262                                 std::vector<librados::notify_timeout_t> *timeouts);
1263
1264     int list_watchers(const std::string& o, std::list<obj_watch_t> *out_watchers);
1265     int list_snaps(const std::string& o, snap_set_t *out_snaps);
1266     void set_notify_timeout(uint32_t timeout);
1267
1268     /// acknowledge a notify we received.
1269     void notify_ack(const std::string& o, ///< watched object
1270                     uint64_t notify_id,   ///< notify id
1271                     uint64_t cookie,      ///< our watch handle
1272                     bufferlist& bl);      ///< optional reply payload
1273
1274     /***
1275      * check on watch validity
1276      *
1277      * Check if a watch is valid.  If so, return the number of
1278      * milliseconds since we last confirmed its liveness.  If there is
1279      * a known error, return it.
1280      *
1281      * If there is an error, the watch is no longer valid, and should
1282      * be destroyed with unwatch().  The user is still interested in
1283      * the object, a new watch should be created with watch().
1284      *
1285      * @param cookie watch handle
1286      * @returns ms since last confirmed valid, or error
1287      */
1288     int watch_check(uint64_t cookie);
1289
1290     // old, deprecated versions
1291     int watch(const std::string& o, uint64_t ver, uint64_t *cookie,
1292               librados::WatchCtx *ctx) __attribute__ ((deprecated));
1293     int notify(const std::string& o, uint64_t ver, bufferlist& bl)
1294       __attribute__ ((deprecated));
1295     int unwatch(const std::string& o, uint64_t cookie)
1296       __attribute__ ((deprecated));
1297
1298     /**
1299      * Set allocation hint for an object
1300      *
1301      * This is an advisory operation, it will always succeed (as if it
1302      * was submitted with a OP_FAILOK flag set) and is not guaranteed
1303      * to do anything on the backend.
1304      *
1305      * @param o the name of the object
1306      * @param expected_object_size expected size of the object, in bytes
1307      * @param expected_write_size expected size of writes to the object, in bytes
1308      * @returns 0 on success, negative error code on failure
1309      */
1310     int set_alloc_hint(const std::string& o,
1311                        uint64_t expected_object_size,
1312                        uint64_t expected_write_size);
1313     int set_alloc_hint2(const std::string& o,
1314                         uint64_t expected_object_size,
1315                         uint64_t expected_write_size,
1316                         uint32_t flags);
1317
1318     // assert version for next sync operations
1319     void set_assert_version(uint64_t ver);
1320
1321     /**
1322      * Pin/unpin an object in cache tier
1323      *
1324      * @param o the name of the object
1325      * @returns 0 on success, negative error code on failure
1326      */
1327     int cache_pin(const std::string& o);
1328     int cache_unpin(const std::string& o);
1329
1330     std::string get_pool_name() const;
1331
1332     void locator_set_key(const std::string& key);
1333     void set_namespace(const std::string& nspace);
1334     std::string get_namespace() const;
1335
1336     int64_t get_id();
1337
1338     // deprecated versions
1339     uint32_t get_object_hash_position(const std::string& oid)
1340       __attribute__ ((deprecated));
1341     uint32_t get_object_pg_hash_position(const std::string& oid)
1342       __attribute__ ((deprecated));
1343
1344     int get_object_hash_position2(const std::string& oid, uint32_t *hash_position);
1345     int get_object_pg_hash_position2(const std::string& oid, uint32_t *pg_hash_position);
1346
1347     config_t cct();
1348
1349     void set_osdmap_full_try()
1350       __attribute__ ((deprecated));
1351     void unset_osdmap_full_try()
1352       __attribute__ ((deprecated));
1353
1354     bool get_pool_full_try();
1355     void set_pool_full_try();
1356     void unset_pool_full_try();
1357
1358     int application_enable(const std::string& app_name, bool force);
1359     int application_enable_async(const std::string& app_name,
1360                                  bool force, PoolAsyncCompletion *c);
1361     int application_list(std::set<std::string> *app_names);
1362     int application_metadata_get(const std::string& app_name,
1363                                  const std::string &key,
1364                                  std::string *value);
1365     int application_metadata_set(const std::string& app_name,
1366                                  const std::string &key,
1367                                  const std::string& value);
1368     int application_metadata_remove(const std::string& app_name,
1369                                     const std::string &key);
1370     int application_metadata_list(const std::string& app_name,
1371                                   std::map<std::string, std::string> *values);
1372
1373   private:
1374     /* You can only get IoCtx instances from Rados */
1375     IoCtx(IoCtxImpl *io_ctx_impl_);
1376
1377     friend class Rados; // Only Rados can use our private constructor to create IoCtxes.
1378     friend class libradosstriper::RadosStriper; // Striper needs to see our IoCtxImpl
1379     friend class ObjectWriteOperation;  // copy_from needs to see our IoCtxImpl
1380     friend class ObjectReadOperation;  // set_chunk needs to see our IoCtxImpl
1381
1382     IoCtxImpl *io_ctx_impl;
1383   };
1384
1385   struct CEPH_RADOS_API PlacementGroup {
1386     PlacementGroup();
1387     PlacementGroup(const PlacementGroup&);
1388     ~PlacementGroup();
1389     bool parse(const char*);
1390     std::unique_ptr<PlacementGroupImpl> impl;
1391   };
1392
1393   CEPH_RADOS_API std::ostream& operator<<(std::ostream&, const PlacementGroup&);
1394
1395   class CEPH_RADOS_API Rados
1396   {
1397   public:
1398     static void version(int *major, int *minor, int *extra);
1399
1400     Rados();
1401     explicit Rados(IoCtx& ioctx);
1402     ~Rados();
1403     static void from_rados_t(rados_t cluster, Rados &rados);
1404
1405     int init(const char * const id);
1406     int init2(const char * const name, const char * const clustername,
1407               uint64_t flags);
1408     int init_with_context(config_t cct_);
1409     config_t cct();
1410     int connect();
1411     void shutdown();
1412     int watch_flush();
1413     int aio_watch_flush(AioCompletion*);
1414     int conf_read_file(const char * const path) const;
1415     int conf_parse_argv(int argc, const char ** argv) const;
1416     int conf_parse_argv_remainder(int argc, const char ** argv,
1417                                   const char ** remargv) const;
1418     int conf_parse_env(const char *env) const;
1419     int conf_set(const char *option, const char *value);
1420     int conf_get(const char *option, std::string &val);
1421
1422     int service_daemon_register(
1423       const std::string& service,  ///< service name (e.g., 'rgw')
1424       const std::string& name,     ///< daemon name (e.g., 'gwfoo')
1425       const std::map<std::string,std::string>& metadata); ///< static metadata about daemon
1426     int service_daemon_update_status(
1427       std::map<std::string,std::string>&& status);
1428
1429     int pool_create(const char *name);
1430     int pool_create(const char *name, uint64_t auid)
1431       __attribute__ ((deprecated));
1432     int pool_create(const char *name, uint64_t auid, uint8_t crush_rule)
1433       __attribute__ ((deprecated));
1434     int pool_create_with_rule(const char *name, uint8_t crush_rule);
1435     int pool_create_async(const char *name, PoolAsyncCompletion *c);
1436     int pool_create_async(const char *name, uint64_t auid, PoolAsyncCompletion *c)
1437       __attribute__ ((deprecated));
1438     int pool_create_async(const char *name, uint64_t auid, uint8_t crush_rule, PoolAsyncCompletion *c)
1439       __attribute__ ((deprecated));
1440     int pool_create_with_rule_async(const char *name, uint8_t crush_rule, PoolAsyncCompletion *c);
1441     int pool_get_base_tier(int64_t pool, int64_t* base_tier);
1442     int pool_delete(const char *name);
1443     int pool_delete_async(const char *name, PoolAsyncCompletion *c);
1444     int64_t pool_lookup(const char *name);
1445     int pool_reverse_lookup(int64_t id, std::string *name);
1446
1447     uint64_t get_instance_id();
1448
1449     int get_min_compatible_osd(int8_t* require_osd_release);
1450     int get_min_compatible_client(int8_t* min_compat_client,
1451                                   int8_t* require_min_compat_client);
1452
1453     int mon_command(std::string cmd, const bufferlist& inbl,
1454                     bufferlist *outbl, std::string *outs);
1455     int mgr_command(std::string cmd, const bufferlist& inbl,
1456                     bufferlist *outbl, std::string *outs);
1457     int osd_command(int osdid, std::string cmd, const bufferlist& inbl,
1458                     bufferlist *outbl, std::string *outs);
1459     int pg_command(const char *pgstr, std::string cmd, const bufferlist& inbl,
1460                    bufferlist *outbl, std::string *outs);
1461
1462     int ioctx_create(const char *name, IoCtx &pioctx);
1463     int ioctx_create2(int64_t pool_id, IoCtx &pioctx);
1464
1465     // Features useful for test cases
1466     void test_blocklist_self(bool set);
1467
1468     /* pool info */
1469     int pool_list(std::list<std::string>& v);
1470     int pool_list2(std::list<std::pair<int64_t, std::string> >& v);
1471     int get_pool_stats(std::list<std::string>& v,
1472                        stats_map& result);
1473     /// deprecated; use simpler form.  categories no longer supported.
1474     int get_pool_stats(std::list<std::string>& v,
1475                        std::map<std::string, stats_map>& stats);
1476     /// deprecated; categories no longer supported
1477     int get_pool_stats(std::list<std::string>& v,
1478                        std::string& category,
1479                        std::map<std::string, stats_map>& stats);
1480     /// check if pool has selfmanaged snaps
1481     bool get_pool_is_selfmanaged_snaps_mode(const std::string& poolname);
1482
1483     int cluster_stat(cluster_stat_t& result);
1484     int cluster_fsid(std::string *fsid);
1485
1486     /**
1487      * List inconsistent placement groups in the given pool
1488      *
1489      * @param pool_id the pool id
1490      * @param pgs [out] the inconsistent PGs
1491      */
1492     int get_inconsistent_pgs(int64_t pool_id,
1493                              std::vector<PlacementGroup>* pgs);
1494     /**
1495      * List the inconsistent objects found in a given PG by last scrub
1496      *
1497      * @param pg the placement group returned by @c pg_list()
1498      * @param start_after the first returned @c objects
1499      * @param max_return the max number of the returned @c objects
1500      * @param c what to do when the operation is complete and safe
1501      * @param objects [out] the objects where inconsistencies are found
1502      * @param interval [in,out] an epoch indicating current interval
1503      * @returns if a non-zero @c interval is specified, will return -EAGAIN i
1504      *          the current interval begin epoch is different.
1505      */
1506     int get_inconsistent_objects(const PlacementGroup& pg,
1507                                  const object_id_t &start_after,
1508                                  unsigned max_return,
1509                                  AioCompletion *c,
1510                                  std::vector<inconsistent_obj_t>* objects,
1511                                  uint32_t* interval);
1512     /**
1513      * List the inconsistent snapsets found in a given PG by last scrub
1514      *
1515      * @param pg the placement group returned by @c pg_list()
1516      * @param start_after the first returned @c objects
1517      * @param max_return the max number of the returned @c objects
1518      * @param c what to do when the operation is complete and safe
1519      * @param snapsets [out] the objects where inconsistencies are found
1520      * @param interval [in,out] an epoch indicating current interval
1521      * @returns if a non-zero @c interval is specified, will return -EAGAIN i
1522      *          the current interval begin epoch is different.
1523      */
1524     int get_inconsistent_snapsets(const PlacementGroup& pg,
1525                                   const object_id_t &start_after,
1526                                   unsigned max_return,
1527                                   AioCompletion *c,
1528                                   std::vector<inconsistent_snapset_t>* snapset,
1529                                   uint32_t* interval);
1530
1531     /// get/wait for the most recent osdmap
1532     int wait_for_latest_osdmap();
1533
1534     int blocklist_add(const std::string& client_address,
1535                       uint32_t expire_seconds);
1536
1537     std::string get_addrs() const;
1538
1539     /*
1540      * pool aio
1541      *
1542      * It is up to the caller to release the completion handler, even if the pool_create_async()
1543      * and/or pool_delete_async() fails and does not send the async request
1544      */
1545     static PoolAsyncCompletion *pool_async_create_completion();
1546
1547    // -- aio --
1548     static AioCompletion *aio_create_completion();
1549     static AioCompletion *aio_create_completion(void *cb_arg, callback_t cb_complete,
1550                                                 callback_t cb_safe)
1551       __attribute__ ((deprecated));
1552     static AioCompletion *aio_create_completion(void *cb_arg, callback_t cb_complete);
1553
1554     friend std::ostream& operator<<(std::ostream &oss, const Rados& r);
1555   private:
1556     friend class neorados::RADOS;
1557
1558     // We don't allow assignment or copying
1559     Rados(const Rados& rhs);
1560     const Rados& operator=(const Rados& rhs);
1561     RadosClient *client;
1562   };
1563
1564 } // namespace v14_2_0
1565 } // namespace librados
1566
1567 #endif
1568