ceph/src/include/rados/librados.hpp

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