src/ceph/src/pybind/rbd/rbd.pyx

   1 # cython: embedsignature=True
   2 """
   3 This module is a thin wrapper around librbd.
   4
   5 It currently provides all the synchronous methods of librbd that do
   6 not use callbacks.
   7
   8 Error codes from librbd are turned into exceptions that subclass
   9 :class:`Error`. Almost all methods may raise :class:`Error`
  10 (the base class of all rbd exceptions), :class:`PermissionError`
  11 and :class:`IOError`, in addition to those documented for the
  12 method.
  13 """
  14 # Copyright 2011 Josh Durgin
  15 # Copyright 2015 Hector Martin <marcan@marcan.st>
  16
  17 import cython
  18 import sys
  19
  20 from cpython cimport PyObject, ref, exc
  21 from libc cimport errno
  22 from libc.stdint cimport *
  23 from libc.stdlib cimport realloc, free
  24 from libc.string cimport strdup
  25
  26 from collections import Iterable
  27 from datetime import datetime
  28
  29 cimport rados
  30
  31
  32 cdef extern from "Python.h":
  33     # These are in cpython/string.pxd, but use "object" types instead of
  34     # PyObject*, which invokes assumptions in cpython that we need to
  35     # legitimately break to implement zero-copy string buffers in Image.read().
  36     # This is valid use of the Python API and documented as a special case.
  37     PyObject *PyBytes_FromStringAndSize(char *v, Py_ssize_t len) except NULL
  38     char* PyBytes_AsString(PyObject *string) except NULL
  39     int _PyBytes_Resize(PyObject **string, Py_ssize_t newsize) except -1
  40
  41 cdef extern from "time.h":
  42     ctypedef long int time_t
  43     cdef struct timespec:
  44         time_t tv_sec
  45         long tv_nsec
  46
  47 cdef extern from "limits.h":
  48     cdef uint64_t INT64_MAX
  49
  50 cdef extern from "rbd/librbd.h" nogil:
  51     enum:
  52         _RBD_FEATURE_LAYERING "RBD_FEATURE_LAYERING"
  53         _RBD_FEATURE_STRIPINGV2 "RBD_FEATURE_STRIPINGV2"
  54         _RBD_FEATURE_EXCLUSIVE_LOCK "RBD_FEATURE_EXCLUSIVE_LOCK"
  55         _RBD_FEATURE_OBJECT_MAP "RBD_FEATURE_OBJECT_MAP"
  56         _RBD_FEATURE_FAST_DIFF "RBD_FEATURE_FAST_DIFF"
  57         _RBD_FEATURE_DEEP_FLATTEN "RBD_FEATURE_DEEP_FLATTEN"
  58         _RBD_FEATURE_JOURNALING "RBD_FEATURE_JOURNALING"
  59         _RBD_FEATURE_DATA_POOL "RBD_FEATURE_DATA_POOL"
  60
  61         _RBD_FEATURES_INCOMPATIBLE "RBD_FEATURES_INCOMPATIBLE"
  62         _RBD_FEATURES_RW_INCOMPATIBLE "RBD_FEATURES_RW_INCOMPATIBLE"
  63         _RBD_FEATURES_MUTABLE "RBD_FEATURES_MUTABLE"
  64         _RBD_FEATURES_SINGLE_CLIENT "RBD_FEATURES_SINGLE_CLIENT"
  65         _RBD_FEATURES_ALL "RBD_FEATURES_ALL"
  66
  67         _RBD_FLAG_OBJECT_MAP_INVALID "RBD_FLAG_OBJECT_MAP_INVALID"
  68         _RBD_FLAG_FAST_DIFF_INVALID "RBD_FLAG_FAST_DIFF_INVALID"
  69
  70         _RBD_IMAGE_OPTION_FORMAT "RBD_IMAGE_OPTION_FORMAT"
  71         _RBD_IMAGE_OPTION_FEATURES "RBD_IMAGE_OPTION_FEATURES"
  72         _RBD_IMAGE_OPTION_ORDER "RBD_IMAGE_OPTION_ORDER"
  73         _RBD_IMAGE_OPTION_STRIPE_UNIT "RBD_IMAGE_OPTION_STRIPE_UNIT"
  74         _RBD_IMAGE_OPTION_STRIPE_COUNT "RBD_IMAGE_OPTION_STRIPE_COUNT"
  75         _RBD_IMAGE_OPTION_DATA_POOL "RBD_IMAGE_OPTION_DATA_POOL"
  76
  77         RBD_MAX_BLOCK_NAME_SIZE
  78         RBD_MAX_IMAGE_NAME_SIZE
  79
  80     ctypedef void* rados_ioctx_t
  81     ctypedef void* rbd_image_t
  82     ctypedef void* rbd_image_options_t
  83     ctypedef void *rbd_completion_t
  84
  85     ctypedef struct rbd_image_info_t:
  86         uint64_t size
  87         uint64_t obj_size
  88         uint64_t num_objs
  89         int order
  90         char block_name_prefix[RBD_MAX_BLOCK_NAME_SIZE]
  91         uint64_t parent_pool
  92         char parent_name[RBD_MAX_IMAGE_NAME_SIZE]
  93
  94     ctypedef struct rbd_snap_info_t:
  95         uint64_t id
  96         uint64_t size
  97         char *name
  98
  99     ctypedef enum rbd_mirror_mode_t:
 100         _RBD_MIRROR_MODE_DISABLED "RBD_MIRROR_MODE_DISABLED"
 101         _RBD_MIRROR_MODE_IMAGE "RBD_MIRROR_MODE_IMAGE"
 102         _RBD_MIRROR_MODE_POOL "RBD_MIRROR_MODE_POOL"
 103
 104     ctypedef struct rbd_mirror_peer_t:
 105         char *uuid
 106         char *cluster_name
 107         char *client_name
 108
 109     ctypedef enum rbd_mirror_image_state_t:
 110         _RBD_MIRROR_IMAGE_DISABLING "RBD_MIRROR_IMAGE_DISABLING"
 111         _RBD_MIRROR_IMAGE_ENABLED "RBD_MIRROR_IMAGE_ENABLED"
 112         _RBD_MIRROR_IMAGE_DISABLED "RBD_MIRROR_IMAGE_DISABLED"
 113
 114     ctypedef struct rbd_mirror_image_info_t:
 115         char *global_id
 116         rbd_mirror_image_state_t state
 117         bint primary
 118
 119     ctypedef enum rbd_mirror_image_status_state_t:
 120         _MIRROR_IMAGE_STATUS_STATE_UNKNOWN "MIRROR_IMAGE_STATUS_STATE_UNKNOWN"
 121         _MIRROR_IMAGE_STATUS_STATE_ERROR "MIRROR_IMAGE_STATUS_STATE_ERROR"
 122         _MIRROR_IMAGE_STATUS_STATE_SYNCING "MIRROR_IMAGE_STATUS_STATE_SYNCING"
 123         _MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY "MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY"
 124         _MIRROR_IMAGE_STATUS_STATE_REPLAYING "MIRROR_IMAGE_STATUS_STATE_REPLAYING"
 125         _MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY "MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY"
 126         _MIRROR_IMAGE_STATUS_STATE_STOPPED "MIRROR_IMAGE_STATUS_STATE_STOPPED"
 127
 128     ctypedef struct rbd_mirror_image_status_t:
 129         char *name
 130         rbd_mirror_image_info_t info
 131         rbd_mirror_image_status_state_t state
 132         char *description
 133         time_t last_update
 134         bint up
 135
 136     ctypedef enum rbd_lock_mode_t:
 137         _RBD_LOCK_MODE_EXCLUSIVE "RBD_LOCK_MODE_EXCLUSIVE"
 138         _RBD_LOCK_MODE_SHARED "RBD_LOCK_MODE_SHARED"
 139
 140     ctypedef enum rbd_trash_image_source_t:
 141         _RBD_TRASH_IMAGE_SOURCE_USER "RBD_TRASH_IMAGE_SOURCE_USER",
 142         _RBD_TRASH_IMAGE_SOURCE_MIRRORING "RBD_TRASH_IMAGE_SOURCE_MIRRORING"
 143
 144     ctypedef struct rbd_trash_image_info_t:
 145         char *id
 146         char *name
 147         rbd_trash_image_source_t source
 148         time_t deletion_time
 149         time_t deferment_end_time
 150
 151     ctypedef void (*rbd_callback_t)(rbd_completion_t cb, void *arg)
 152     ctypedef int (*librbd_progress_fn_t)(uint64_t offset, uint64_t total, void* ptr)
 153
 154     void rbd_version(int *major, int *minor, int *extra)
 155
 156     void rbd_image_options_create(rbd_image_options_t* opts)
 157     void rbd_image_options_destroy(rbd_image_options_t opts)
 158     int rbd_image_options_set_string(rbd_image_options_t opts, int optname,
 159                                      const char* optval)
 160     int rbd_image_options_set_uint64(rbd_image_options_t opts, int optname,
 161                                      uint64_t optval)
 162     int rbd_image_options_get_string(rbd_image_options_t opts, int optname,
 163                                      char* optval, size_t maxlen)
 164     int rbd_image_options_get_uint64(rbd_image_options_t opts, int optname,
 165                                      uint64_t* optval)
 166     int rbd_image_options_unset(rbd_image_options_t opts, int optname)
 167     void rbd_image_options_clear(rbd_image_options_t opts)
 168     int rbd_image_options_is_empty(rbd_image_options_t opts)
 169
 170     int rbd_list(rados_ioctx_t io, char *names, size_t *size)
 171     int rbd_create(rados_ioctx_t io, const char *name, uint64_t size,
 172                    int *order)
 173     int rbd_create4(rados_ioctx_t io, const char *name, uint64_t size,
 174                     rbd_image_options_t opts)
 175     int rbd_clone3(rados_ioctx_t p_ioctx, const char *p_name,
 176                    const char *p_snapname, rados_ioctx_t c_ioctx,
 177                    const char *c_name, rbd_image_options_t c_opts)
 178     int rbd_remove(rados_ioctx_t io, const char *name)
 179     int rbd_rename(rados_ioctx_t src_io_ctx, const char *srcname,
 180                    const char *destname)
 181
 182     int rbd_trash_move(rados_ioctx_t io, const char *name, uint64_t delay)
 183     int rbd_trash_get(rados_ioctx_t io, const char *id,
 184                       rbd_trash_image_info_t *info)
 185     void rbd_trash_get_cleanup(rbd_trash_image_info_t *info)
 186     int rbd_trash_list(rados_ioctx_t io, rbd_trash_image_info_t *trash_entries,
 187                        size_t *num_entries)
 188     void rbd_trash_list_cleanup(rbd_trash_image_info_t *trash_entries,
 189                                 size_t num_entries)
 190     int rbd_trash_remove(rados_ioctx_t io, const char *id, int force)
 191     int rbd_trash_restore(rados_ioctx_t io, const char *id, const char *name)
 192
 193     int rbd_mirror_mode_get(rados_ioctx_t io, rbd_mirror_mode_t *mirror_mode)
 194     int rbd_mirror_mode_set(rados_ioctx_t io, rbd_mirror_mode_t mirror_mode)
 195     int rbd_mirror_peer_add(rados_ioctx_t io, char *uuid,
 196                             size_t uuid_max_length, const char *cluster_name,
 197                             const char *client_name)
 198     int rbd_mirror_peer_remove(rados_ioctx_t io, const char *uuid)
 199     int rbd_mirror_peer_list(rados_ioctx_t io_ctx, rbd_mirror_peer_t *peers,
 200                              int *max_peers)
 201     void rbd_mirror_peer_list_cleanup(rbd_mirror_peer_t *peers, int max_peers)
 202     int rbd_mirror_peer_set_client(rados_ioctx_t io, const char *uuid,
 203                                    const char *client_name)
 204     int rbd_mirror_peer_set_cluster(rados_ioctx_t io_ctx, const char *uuid,
 205                                     const char *cluster_name)
 206     int rbd_mirror_image_status_list(rados_ioctx_t io, const char *start_id,
 207                                      size_t max, char **image_ids,
 208                                      rbd_mirror_image_status_t *images,
 209                                      size_t *len)
 210     void rbd_mirror_image_status_list_cleanup(char **image_ids,
 211                                               rbd_mirror_image_status_t *images,
 212                                               size_t len)
 213     int rbd_mirror_image_status_summary(rados_ioctx_t io,
 214                                         rbd_mirror_image_status_state_t *states,
 215                                         int *counts, size_t *maxlen)
 216
 217     int rbd_open(rados_ioctx_t io, const char *name,
 218                  rbd_image_t *image, const char *snap_name)
 219     int rbd_open_read_only(rados_ioctx_t io, const char *name,
 220                            rbd_image_t *image, const char *snap_name)
 221     int rbd_close(rbd_image_t image)
 222     int rbd_resize(rbd_image_t image, uint64_t size)
 223     int rbd_stat(rbd_image_t image, rbd_image_info_t *info, size_t infosize)
 224     int rbd_get_old_format(rbd_image_t image, uint8_t *old)
 225     int rbd_get_size(rbd_image_t image, uint64_t *size)
 226     int rbd_get_features(rbd_image_t image, uint64_t *features)
 227     int rbd_update_features(rbd_image_t image, uint64_t features,
 228                             uint8_t enabled)
 229     int rbd_get_stripe_unit(rbd_image_t image, uint64_t *stripe_unit)
 230     int rbd_get_stripe_count(rbd_image_t image, uint64_t *stripe_count)
 231     int rbd_get_create_timestamp(rbd_image_t image, timespec *timestamp)
 232     int rbd_get_overlap(rbd_image_t image, uint64_t *overlap)
 233     int rbd_get_id(rbd_image_t image, char *id, size_t id_len)
 234     int rbd_get_block_name_prefix(rbd_image_t image, char *prefix,
 235                                   size_t prefix_len)
 236     int rbd_get_parent_info2(rbd_image_t image,
 237                              char *parent_poolname, size_t ppoolnamelen,
 238                              char *parent_name, size_t pnamelen,
 239                              char *parent_id, size_t pidlen,
 240                              char *parent_snapname, size_t psnapnamelen)
 241     int rbd_get_flags(rbd_image_t image, uint64_t *flags)
 242     ssize_t rbd_read2(rbd_image_t image, uint64_t ofs, size_t len,
 243                       char *buf, int op_flags)
 244     ssize_t rbd_write2(rbd_image_t image, uint64_t ofs, size_t len,
 245                        const char *buf, int op_flags)
 246     int rbd_discard(rbd_image_t image, uint64_t ofs, uint64_t len)
 247     int rbd_copy3(rbd_image_t src, rados_ioctx_t dest_io_ctx,
 248                   const char *destname, rbd_image_options_t dest_opts)
 249     int rbd_snap_list(rbd_image_t image, rbd_snap_info_t *snaps,
 250                       int *max_snaps)
 251     void rbd_snap_list_end(rbd_snap_info_t *snaps)
 252     int rbd_snap_create(rbd_image_t image, const char *snapname)
 253     int rbd_snap_remove(rbd_image_t image, const char *snapname)
 254     int rbd_snap_remove2(rbd_image_t image, const char *snapname, uint32_t flags,
 255                          librbd_progress_fn_t cb, void *cbdata)
 256     int rbd_snap_rollback(rbd_image_t image, const char *snapname)
 257     int rbd_snap_rename(rbd_image_t image, const char *snapname,
 258                         const char* dstsnapsname)
 259     int rbd_snap_protect(rbd_image_t image, const char *snap_name)
 260     int rbd_snap_unprotect(rbd_image_t image, const char *snap_name)
 261     int rbd_snap_is_protected(rbd_image_t image, const char *snap_name,
 262                               int *is_protected)
 263     int rbd_snap_get_limit(rbd_image_t image, uint64_t *limit)
 264     int rbd_snap_set_limit(rbd_image_t image, uint64_t limit)
 265     int rbd_snap_get_timestamp(rbd_image_t image, uint64_t snap_id, timespec *timestamp)
 266     int rbd_snap_set(rbd_image_t image, const char *snapname)
 267     int rbd_flatten(rbd_image_t image)
 268     int rbd_rebuild_object_map(rbd_image_t image, librbd_progress_fn_t cb,
 269                                void *cbdata)
 270     ssize_t rbd_list_children(rbd_image_t image, char *pools, size_t *pools_len,
 271                               char *images, size_t *images_len)
 272     ssize_t rbd_list_lockers(rbd_image_t image, int *exclusive,
 273                              char *tag, size_t *tag_len,
 274                              char *clients, size_t *clients_len,
 275                              char *cookies, size_t *cookies_len,
 276                              char *addrs, size_t *addrs_len)
 277     int rbd_lock_exclusive(rbd_image_t image, const char *cookie)
 278     int rbd_lock_shared(rbd_image_t image, const char *cookie,
 279                         const char *tag)
 280     int rbd_unlock(rbd_image_t image, const char *cookie)
 281     int rbd_break_lock(rbd_image_t image, const char *client,
 282                        const char *cookie)
 283
 284     int rbd_is_exclusive_lock_owner(rbd_image_t image, int *is_owner)
 285     int rbd_lock_acquire(rbd_image_t image, rbd_lock_mode_t lock_mode)
 286     int rbd_lock_release(rbd_image_t image)
 287     int rbd_lock_get_owners(rbd_image_t image, rbd_lock_mode_t *lock_mode,
 288                             char **lock_owners, size_t *max_lock_owners)
 289     void rbd_lock_get_owners_cleanup(char **lock_owners,
 290                                      size_t lock_owner_count)
 291     int rbd_lock_break(rbd_image_t image, rbd_lock_mode_t lock_mode,
 292                        char *lock_owner)
 293
 294     # We use -9000 to propagate Python exceptions. We use except? to make sure
 295     # things still work as intended if -9000 happens to be a valid errno value
 296     # somewhere.
 297     int rbd_diff_iterate2(rbd_image_t image, const char *fromsnapname,
 298                          uint64_t ofs, uint64_t len,
 299                          uint8_t include_parent, uint8_t whole_object,
 300                          int (*cb)(uint64_t, size_t, int, void *)
 301                              nogil except? -9000,
 302                          void *arg) except? -9000
 303
 304     int rbd_flush(rbd_image_t image)
 305     int rbd_invalidate_cache(rbd_image_t image)
 306
 307     int rbd_mirror_image_enable(rbd_image_t image)
 308     int rbd_mirror_image_disable(rbd_image_t image, bint force)
 309     int rbd_mirror_image_promote(rbd_image_t image, bint force)
 310     int rbd_mirror_image_demote(rbd_image_t image)
 311     int rbd_mirror_image_resync(rbd_image_t image)
 312     int rbd_mirror_image_get_info(rbd_image_t image,
 313                                   rbd_mirror_image_info_t *mirror_image_info,
 314                                   size_t info_size)
 315     int rbd_mirror_image_get_status(rbd_image_t image,
 316                                     rbd_mirror_image_status_t *mirror_image_status,
 317                                     size_t status_size)
 318
 319     int rbd_aio_write2(rbd_image_t image, uint64_t off, size_t len,
 320                        const char *buf, rbd_completion_t c, int op_flags)
 321     int rbd_aio_read2(rbd_image_t image, uint64_t off, size_t len,
 322                       char *buf, rbd_completion_t c, int op_flags)
 323     int rbd_aio_discard(rbd_image_t image, uint64_t off, uint64_t len,
 324                         rbd_completion_t c)
 325
 326     int rbd_aio_create_completion(void *cb_arg, rbd_callback_t complete_cb,
 327                                   rbd_completion_t *c)
 328     int rbd_aio_is_complete(rbd_completion_t c)
 329     int rbd_aio_wait_for_complete(rbd_completion_t c)
 330     ssize_t rbd_aio_get_return_value(rbd_completion_t c)
 331     void rbd_aio_release(rbd_completion_t c)
 332     int rbd_aio_flush(rbd_image_t image, rbd_completion_t c)
 333
 334     int rbd_metadata_get(rbd_image_t image, const char *key, char *value,
 335                          size_t *val_len)
 336     int rbd_metadata_set(rbd_image_t image, const char *key, const char *value)
 337     int rbd_metadata_remove(rbd_image_t image, const char *key)
 338     int rbd_metadata_list(rbd_image_t image, const char *start, uint64_t max,
 339                           char *keys, size_t *key_len, char *values,
 340                           size_t *vals_len)
 341
 342 RBD_FEATURE_LAYERING = _RBD_FEATURE_LAYERING
 343 RBD_FEATURE_STRIPINGV2 = _RBD_FEATURE_STRIPINGV2
 344 RBD_FEATURE_EXCLUSIVE_LOCK = _RBD_FEATURE_EXCLUSIVE_LOCK
 345 RBD_FEATURE_OBJECT_MAP = _RBD_FEATURE_OBJECT_MAP
 346 RBD_FEATURE_FAST_DIFF = _RBD_FEATURE_FAST_DIFF
 347 RBD_FEATURE_DEEP_FLATTEN = _RBD_FEATURE_DEEP_FLATTEN
 348 RBD_FEATURE_JOURNALING = _RBD_FEATURE_JOURNALING
 349 RBD_FEATURE_DATA_POOL = _RBD_FEATURE_DATA_POOL
 350
 351 RBD_FEATURES_INCOMPATIBLE = _RBD_FEATURES_INCOMPATIBLE
 352 RBD_FEATURES_RW_INCOMPATIBLE = _RBD_FEATURES_RW_INCOMPATIBLE
 353 RBD_FEATURES_MUTABLE = _RBD_FEATURES_MUTABLE
 354 RBD_FEATURES_SINGLE_CLIENT = _RBD_FEATURES_SINGLE_CLIENT
 355 RBD_FEATURES_ALL = _RBD_FEATURES_ALL
 356
 357 RBD_FLAG_OBJECT_MAP_INVALID = _RBD_FLAG_OBJECT_MAP_INVALID
 358
 359 RBD_MIRROR_MODE_DISABLED = _RBD_MIRROR_MODE_DISABLED
 360 RBD_MIRROR_MODE_IMAGE = _RBD_MIRROR_MODE_IMAGE
 361 RBD_MIRROR_MODE_POOL = _RBD_MIRROR_MODE_POOL
 362
 363 RBD_MIRROR_IMAGE_DISABLING = _RBD_MIRROR_IMAGE_DISABLING
 364 RBD_MIRROR_IMAGE_ENABLED = _RBD_MIRROR_IMAGE_ENABLED
 365 RBD_MIRROR_IMAGE_DISABLED = _RBD_MIRROR_IMAGE_DISABLED
 366
 367 MIRROR_IMAGE_STATUS_STATE_UNKNOWN = _MIRROR_IMAGE_STATUS_STATE_UNKNOWN
 368 MIRROR_IMAGE_STATUS_STATE_ERROR = _MIRROR_IMAGE_STATUS_STATE_ERROR
 369 MIRROR_IMAGE_STATUS_STATE_SYNCING = _MIRROR_IMAGE_STATUS_STATE_SYNCING
 370 MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY = _MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY
 371 MIRROR_IMAGE_STATUS_STATE_REPLAYING = _MIRROR_IMAGE_STATUS_STATE_REPLAYING
 372 MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY = _MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY
 373 MIRROR_IMAGE_STATUS_STATE_STOPPED = _MIRROR_IMAGE_STATUS_STATE_STOPPED
 374
 375 RBD_LOCK_MODE_EXCLUSIVE = _RBD_LOCK_MODE_EXCLUSIVE
 376 RBD_LOCK_MODE_SHARED = _RBD_LOCK_MODE_SHARED
 377
 378 RBD_IMAGE_OPTION_FORMAT = _RBD_IMAGE_OPTION_FORMAT
 379 RBD_IMAGE_OPTION_FEATURES = _RBD_IMAGE_OPTION_FEATURES
 380 RBD_IMAGE_OPTION_ORDER = _RBD_IMAGE_OPTION_ORDER
 381 RBD_IMAGE_OPTION_STRIPE_UNIT = _RBD_IMAGE_OPTION_STRIPE_UNIT
 382 RBD_IMAGE_OPTION_STRIPE_COUNT = _RBD_IMAGE_OPTION_STRIPE_COUNT
 383 RBD_IMAGE_OPTION_DATA_POOL = _RBD_IMAGE_OPTION_DATA_POOL
 384
 385 class Error(Exception):
 386     pass
 387
 388
 389 class OSError(Error):
 390     """ `OSError` class, derived from `Error` """
 391     def __init__(self, message, errno=None):
 392         super(OSError, self).__init__(message)
 393         self.errno = errno
 394
 395     def __str__(self):
 396         msg = super(OSError, self).__str__()
 397         if self.errno is None:
 398             return msg
 399         return '[errno {0}] {1}'.format(self.errno, msg)
 400
 401     def __reduce__(self):
 402         return (self.__class__, (self.message, self.errno))
 403
 404 class PermissionError(OSError):
 405     pass
 406
 407
 408 class ImageNotFound(OSError):
 409     pass
 410
 411
 412 class ImageExists(OSError):
 413     pass
 414
 415
 416 class IOError(OSError):
 417     pass
 418
 419
 420 class NoSpace(OSError):
 421     pass
 422
 423
 424 class IncompleteWriteError(OSError):
 425     pass
 426
 427
 428 class InvalidArgument(OSError):
 429     pass
 430
 431
 432 class LogicError(Error):
 433     pass
 434
 435
 436 class ReadOnlyImage(OSError):
 437     pass
 438
 439
 440 class ImageBusy(OSError):
 441     pass
 442
 443
 444 class ImageHasSnapshots(OSError):
 445     pass
 446
 447
 448 class FunctionNotSupported(OSError):
 449     pass
 450
 451
 452 class ArgumentOutOfRange(OSError):
 453     pass
 454
 455
 456 class ConnectionShutdown(OSError):
 457     pass
 458
 459
 460 class Timeout(OSError):
 461     pass
 462
 463 class DiskQuotaExceeded(OSError):
 464     pass
 465
 466
 467 cdef errno_to_exception = {
 468     errno.EPERM     : PermissionError,
 469     errno.ENOENT    : ImageNotFound,
 470     errno.EIO       : IOError,
 471     errno.ENOSPC    : NoSpace,
 472     errno.EEXIST    : ImageExists,
 473     errno.EINVAL    : InvalidArgument,
 474     errno.EROFS     : ReadOnlyImage,
 475     errno.EBUSY     : ImageBusy,
 476     errno.ENOTEMPTY : ImageHasSnapshots,
 477     errno.ENOSYS    : FunctionNotSupported,
 478     errno.EDOM      : ArgumentOutOfRange,
 479     errno.ESHUTDOWN : ConnectionShutdown,
 480     errno.ETIMEDOUT : Timeout,
 481     errno.EDQUOT    : DiskQuotaExceeded,
 482 }
 483
 484 cdef make_ex(ret, msg):
 485     """
 486     Translate a librbd return code into an exception.
 487
 488     :param ret: the return code
 489     :type ret: int
 490     :param msg: the error message to use
 491     :type msg: str
 492     :returns: a subclass of :class:`Error`
 493     """
 494     ret = abs(ret)
 495     if ret in errno_to_exception:
 496         return errno_to_exception[ret](msg, errno=ret)
 497     else:
 498         return OSError(msg, errno=ret)
 499
 500
 501 cdef rados_ioctx_t convert_ioctx(rados.Ioctx ioctx) except? NULL:
 502     return <rados_ioctx_t>ioctx.io
 503
 504 cdef int no_op_progress_callback(uint64_t offset, uint64_t total, void* ptr) nogil:
 505     return 0
 506
 507 def cstr(val, name, encoding="utf-8", opt=False):
 508     """
 509     Create a byte string from a Python string
 510
 511     :param basestring val: Python string
 512     :param str name: Name of the string parameter, for exceptions
 513     :param str encoding: Encoding to use
 514     :param bool opt: If True, None is allowed
 515     :rtype: bytes
 516     :raises: :class:`InvalidArgument`
 517     """
 518     if opt and val is None:
 519         return None
 520     if isinstance(val, bytes):
 521         return val
 522     elif isinstance(val, unicode):
 523         return val.encode(encoding)
 524     else:
 525         raise InvalidArgument('%s must be a string' % name)
 526
 527 def decode_cstr(val, encoding="utf-8"):
 528     """
 529     Decode a byte string into a Python string.
 530
 531     :param bytes val: byte string
 532     :rtype: unicode or None
 533     """
 534     if val is None:
 535         return None
 536
 537     return val.decode(encoding)
 538
 539
 540 cdef char* opt_str(s) except? NULL:
 541     if s is None:
 542         return NULL
 543     return s
 544
 545 cdef void* realloc_chk(void* ptr, size_t size) except NULL:
 546     cdef void *ret = realloc(ptr, size)
 547     if ret == NULL:
 548         raise MemoryError("realloc failed")
 549     return ret
 550
 551 cdef class Completion
 552
 553 cdef void __aio_complete_cb(rbd_completion_t completion, void *args) with gil:
 554     """
 555     Callback to oncomplete() for asynchronous operations
 556     """
 557     cdef Completion cb = <Completion>args
 558     cb._complete()
 559
 560
 561 cdef class Completion(object):
 562     """completion object"""
 563
 564     cdef:
 565         object image
 566         object oncomplete
 567         rbd_completion_t rbd_comp
 568         PyObject* buf
 569         bint persisted
 570         object exc_info
 571
 572     def __cinit__(self, image, object oncomplete):
 573         self.oncomplete = oncomplete
 574         self.image = image
 575         self.persisted = False
 576
 577     def is_complete(self):
 578         """
 579         Has an asynchronous operation completed?
 580
 581         This does not imply that the callback has finished.
 582
 583         :returns: True if the operation is completed
 584         """
 585         with nogil:
 586             ret = rbd_aio_is_complete(self.rbd_comp)
 587         return ret == 1
 588
 589     def wait_for_complete_and_cb(self):
 590         """
 591         Wait for an asynchronous operation to complete
 592
 593         This method waits for the callback to execute, if one was provided.
 594         It will also re-raise any exceptions raised by the callback. You
 595         should call this to "reap" asynchronous completions and ensure that
 596         any exceptions in the callbacks are handled, as an exception internal
 597         to this module may have occurred.
 598         """
 599         with nogil:
 600             rbd_aio_wait_for_complete(self.rbd_comp)
 601
 602         if self.exc_info:
 603             raise self.exc_info[0], self.exc_info[1], self.exc_info[2]
 604
 605     def get_return_value(self):
 606         """
 607         Get the return value of an asychronous operation
 608
 609         The return value is set when the operation is complete.
 610
 611         :returns: int - return value of the operation
 612         """
 613         with nogil:
 614             ret = rbd_aio_get_return_value(self.rbd_comp)
 615         return ret
 616
 617     def __dealloc__(self):
 618         """
 619         Release a completion
 620
 621         This is automatically called when the completion object is freed.
 622         """
 623         ref.Py_XDECREF(self.buf)
 624         self.buf = NULL
 625         if self.rbd_comp != NULL:
 626             with nogil:
 627                 rbd_aio_release(self.rbd_comp)
 628                 self.rbd_comp = NULL
 629
 630     cdef void _complete(self):
 631         try:
 632             self.__unpersist()
 633             if self.oncomplete:
 634                 self.oncomplete(self)
 635         # In the event that something raises an exception during the next 2
 636         # lines of code, we will not be able to catch it, and this may result
 637         # in the app not noticing a failed callback. However, this should only
 638         # happen in extreme circumstances (OOM, etc.). KeyboardInterrupt
 639         # should not be a problem because the callback thread from librbd
 640         # ought to have SIGINT blocked.
 641         except:
 642             self.exc_info = sys.exc_info()
 643
 644     cdef __persist(self):
 645         if self.oncomplete is not None and not self.persisted:
 646             # Increment our own reference count to make sure the completion
 647             # is not freed until the callback is called. The completion is
 648             # allowed to be freed if there is no callback.
 649             ref.Py_INCREF(self)
 650             self.persisted = True
 651
 652     cdef __unpersist(self):
 653         if self.persisted:
 654             ref.Py_DECREF(self)
 655             self.persisted = False
 656
 657
 658 class RBD(object):
 659     """
 660     This class wraps librbd CRUD functions.
 661     """
 662     def version(self):
 663         """
 664         Get the version number of the ``librbd`` C library.
 665
 666         :returns: a tuple of ``(major, minor, extra)`` components of the
 667                   librbd version
 668         """
 669         cdef int major = 0
 670         cdef int minor = 0
 671         cdef int extra = 0
 672         rbd_version(&major, &minor, &extra)
 673         return (major, minor, extra)
 674
 675     def create(self, ioctx, name, size, order=None, old_format=True,
 676                features=None, stripe_unit=None, stripe_count=None,
 677                data_pool=None):
 678         """
 679         Create an rbd image.
 680
 681         :param ioctx: the context in which to create the image
 682         :type ioctx: :class:`rados.Ioctx`
 683         :param name: what the image is called
 684         :type name: str
 685         :param size: how big the image is in bytes
 686         :type size: int
 687         :param order: the image is split into (2**order) byte objects
 688         :type order: int
 689         :param old_format: whether to create an old-style image that
 690                            is accessible by old clients, but can't
 691                            use more advanced features like layering.
 692         :type old_format: bool
 693         :param features: bitmask of features to enable
 694         :type features: int
 695         :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
 696         :type stripe_unit: int
 697         :param stripe_count: objects to stripe over before looping
 698         :type stripe_count: int
 699         :param data_pool: optional separate pool for data blocks
 700         :type data_pool: str
 701         :raises: :class:`ImageExists`
 702         :raises: :class:`TypeError`
 703         :raises: :class:`InvalidArgument`
 704         :raises: :class:`FunctionNotSupported`
 705         """
 706         name = cstr(name, 'name')
 707         cdef:
 708             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 709             char *_name = name
 710             uint64_t _size = size
 711             int _order = 0
 712             rbd_image_options_t opts
 713         if order is not None:
 714             _order = order
 715         if old_format:
 716             if (features or
 717                 ((stripe_unit is not None) and stripe_unit != 0) or
 718                 ((stripe_count is not None) and stripe_count != 0) or
 719                 data_pool):
 720                 raise InvalidArgument('format 1 images do not support feature '
 721                                       'masks, non-default striping, nor data '
 722                                       'pool')
 723             with nogil:
 724                 ret = rbd_create(_ioctx, _name, _size, &_order)
 725         else:
 726             rbd_image_options_create(&opts)
 727             try:
 728                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FORMAT,
 729                                              1 if old_format else 2)
 730                 if features is not None:
 731                     rbd_image_options_set_uint64(opts,
 732                                                  RBD_IMAGE_OPTION_FEATURES,
 733                                                  features)
 734                 if order is not None:
 735                     rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
 736                                                  _order)
 737                 if stripe_unit is not None:
 738                     rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
 739                                                  stripe_unit)
 740                 if stripe_count is not None:
 741                     rbd_image_options_set_uint64(opts,
 742                                                  RBD_IMAGE_OPTION_STRIPE_COUNT,
 743                                                  stripe_count)
 744                 if data_pool is not None:
 745                     rbd_image_options_set_string(opts,
 746                                                  RBD_IMAGE_OPTION_DATA_POOL,
 747                                                  data_pool)
 748                 with nogil:
 749                     ret = rbd_create4(_ioctx, _name, _size, opts)
 750             finally:
 751                 rbd_image_options_destroy(opts)
 752         if ret < 0:
 753             raise make_ex(ret, 'error creating image')
 754
 755     def clone(self, p_ioctx, p_name, p_snapname, c_ioctx, c_name,
 756               features=None, order=None, stripe_unit=None, stripe_count=None,
 757               data_pool=None):
 758         """
 759         Clone a parent rbd snapshot into a COW sparse child.
 760
 761         :param p_ioctx: the parent context that represents the parent snap
 762         :type ioctx: :class:`rados.Ioctx`
 763         :param p_name: the parent image name
 764         :type name: str
 765         :param p_snapname: the parent image snapshot name
 766         :type name: str
 767         :param c_ioctx: the child context that represents the new clone
 768         :type ioctx: :class:`rados.Ioctx`
 769         :param c_name: the clone (child) name
 770         :type name: str
 771         :param features: bitmask of features to enable; if set, must include layering
 772         :type features: int
 773         :param order: the image is split into (2**order) byte objects
 774         :type order: int
 775         :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
 776         :type stripe_unit: int
 777         :param stripe_count: objects to stripe over before looping
 778         :type stripe_count: int
 779         :param data_pool: optional separate pool for data blocks
 780         :type data_pool: str
 781         :raises: :class:`TypeError`
 782         :raises: :class:`InvalidArgument`
 783         :raises: :class:`ImageExists`
 784         :raises: :class:`FunctionNotSupported`
 785         :raises: :class:`ArgumentOutOfRange`
 786         """
 787         p_snapname = cstr(p_snapname, 'p_snapname')
 788         p_name = cstr(p_name, 'p_name')
 789         c_name = cstr(c_name, 'c_name')
 790         cdef:
 791             rados_ioctx_t _p_ioctx = convert_ioctx(p_ioctx)
 792             rados_ioctx_t _c_ioctx = convert_ioctx(c_ioctx)
 793             char *_p_name = p_name
 794             char *_p_snapname = p_snapname
 795             char *_c_name = c_name
 796             rbd_image_options_t opts
 797
 798         rbd_image_options_create(&opts)
 799         try:
 800             if features is not None:
 801                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
 802                                              features)
 803             if order is not None:
 804                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
 805                                              order)
 806             if stripe_unit is not None:
 807                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
 808                                              stripe_unit)
 809             if stripe_count is not None:
 810                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
 811                                              stripe_count)
 812             if data_pool is not None:
 813                 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
 814                                              data_pool)
 815             with nogil:
 816                 ret = rbd_clone3(_p_ioctx, _p_name, _p_snapname,
 817                                  _c_ioctx, _c_name, opts)
 818         finally:
 819             rbd_image_options_destroy(opts)
 820         if ret < 0:
 821             raise make_ex(ret, 'error creating clone')
 822
 823     def list(self, ioctx):
 824         """
 825         List image names.
 826
 827         :param ioctx: determines which RADOS pool is read
 828         :type ioctx: :class:`rados.Ioctx`
 829         :returns: list -- a list of image names
 830         """
 831         cdef:
 832             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 833             size_t size = 512
 834             char *c_names = NULL
 835         try:
 836             while True:
 837                 c_names = <char *>realloc_chk(c_names, size)
 838                 with nogil:
 839                     ret = rbd_list(_ioctx, c_names, &size)
 840                 if ret >= 0:
 841                     break
 842                 elif ret != -errno.ERANGE:
 843                     raise make_ex(ret, 'error listing images')
 844             return [decode_cstr(name) for name in c_names[:ret].split(b'\0')
 845                     if name]
 846         finally:
 847             free(c_names)
 848
 849     def remove(self, ioctx, name):
 850         """
 851         Delete an RBD image. This may take a long time, since it does
 852         not return until every object that comprises the image has
 853         been deleted. Note that all snapshots must be deleted before
 854         the image can be removed. If there are snapshots left,
 855         :class:`ImageHasSnapshots` is raised. If the image is still
 856         open, or the watch from a crashed client has not expired,
 857         :class:`ImageBusy` is raised.
 858
 859         :param ioctx: determines which RADOS pool the image is in
 860         :type ioctx: :class:`rados.Ioctx`
 861         :param name: the name of the image to remove
 862         :type name: str
 863         :raises: :class:`ImageNotFound`, :class:`ImageBusy`,
 864                  :class:`ImageHasSnapshots`
 865         """
 866         name = cstr(name, 'name')
 867         cdef:
 868             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 869             char *_name = name
 870         with nogil:
 871             ret = rbd_remove(_ioctx, _name)
 872         if ret != 0:
 873             raise make_ex(ret, 'error removing image')
 874
 875     def rename(self, ioctx, src, dest):
 876         """
 877         Rename an RBD image.
 878
 879         :param ioctx: determines which RADOS pool the image is in
 880         :type ioctx: :class:`rados.Ioctx`
 881         :param src: the current name of the image
 882         :type src: str
 883         :param dest: the new name of the image
 884         :type dest: str
 885         :raises: :class:`ImageNotFound`, :class:`ImageExists`
 886         """
 887         src = cstr(src, 'src')
 888         dest = cstr(dest, 'dest')
 889         cdef:
 890             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 891             char *_src = src
 892             char *_dest = dest
 893         with nogil:
 894             ret = rbd_rename(_ioctx, _src, _dest)
 895         if ret != 0:
 896             raise make_ex(ret, 'error renaming image')
 897
 898     def trash_move(self, ioctx, name, delay=0):
 899         """
 900         Move an RBD image to the trash.
 901         :param ioctx: determines which RADOS pool the image is in
 902         :type ioctx: :class:`rados.Ioctx`
 903         :param name: the name of the image to remove
 904         :type name: str
 905         :param delay: time delay in seconds before the image can be deleted
 906                       from trash
 907         :type delay: int
 908         :raises: :class:`ImageNotFound`
 909         """
 910         name = cstr(name, 'name')
 911         cdef:
 912             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 913             char *_name = name
 914             uint64_t _delay = delay
 915         with nogil:
 916             ret = rbd_trash_move(_ioctx, _name, _delay)
 917         if ret != 0:
 918             raise make_ex(ret, 'error moving image to trash')
 919
 920     def trash_remove(self, ioctx, image_id, force=False):
 921         """
 922         Delete an RBD image from trash. If image deferment time has not
 923         expired :class:`PermissionError` is raised.
 924         :param ioctx: determines which RADOS pool the image is in
 925         :type ioctx: :class:`rados.Ioctx`
 926         :param image_id: the id of the image to remove
 927         :type image_id: str
 928         :param force: force remove even if deferment time has not expired
 929         :type force: bool
 930         :raises: :class:`ImageNotFound`, :class:`PermissionError`
 931         """
 932         image_id = cstr(image_id, 'image_id')
 933         cdef:
 934             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 935             char *_image_id = image_id
 936             int _force = force
 937         with nogil:
 938             ret = rbd_trash_remove(_ioctx, _image_id, _force)
 939         if ret != 0:
 940             raise make_ex(ret, 'error deleting image from trash')
 941
 942     def trash_get(self, ioctx, image_id):
 943         """
 944         Retrieve RBD image info from trash
 945         :param ioctx: determines which RADOS pool the image is in
 946         :type ioctx: :class:`rados.Ioctx`
 947         :param image_id: the id of the image to restore
 948         :type image_id: str
 949         :returns: dict - contains the following keys:
 950
 951             * ``id`` (str) - image id
 952
 953             * ``name`` (str) - image name
 954
 955             * ``source`` (str) - source of deletion
 956
 957             * ``deletion_time`` (datetime) - time of deletion
 958
 959             * ``deferment_end_time`` (datetime) - time that an image is allowed
 960               to be removed from trash
 961
 962         :raises: :class:`ImageNotFound`
 963         """
 964         image_id = cstr(image_id, 'image_id')
 965         cdef:
 966             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
 967             char *_image_id = image_id
 968             rbd_trash_image_info_t c_info
 969         with nogil:
 970             ret = rbd_trash_get(_ioctx, _image_id, &c_info)
 971         if ret != 0:
 972             raise make_ex(ret, 'error restoring image from trash')
 973
 974         __source_string = ['USER', 'MIRRORING']
 975         info = {
 976             'id'          : decode_cstr(c_info.id),
 977             'name'        : decode_cstr(c_info.name),
 978             'source'      : __source_string[c_info.source],
 979             'deletion_time' : datetime.fromtimestamp(c_info.deletion_time),
 980             'deferment_end_time' : datetime.fromtimestamp(c_info.deferment_end_time)
 981             }
 982         rbd_trash_get_cleanup(&c_info)
 983         return info
 984
 985     def trash_list(self, ioctx):
 986         """
 987         List all entries from trash.
 988         :param ioctx: determines which RADOS pool the image is in
 989         :type ioctx: :class:`rados.Ioctx`
 990         :returns: :class:`TrashIterator`
 991         """
 992         return TrashIterator(ioctx)
 993
 994     def trash_restore(self, ioctx, image_id, name):
 995         """
 996         Restore an RBD image from trash.
 997         :param ioctx: determines which RADOS pool the image is in
 998         :type ioctx: :class:`rados.Ioctx`
 999         :param image_id: the id of the image to restore
1000         :type image_id: str
1001         :param name: the new name of the restored image
1002         :type name: str
1003         :raises: :class:`ImageNotFound`
1004         """
1005         image_id = cstr(image_id, 'image_id')
1006         name = cstr(name, 'name')
1007         cdef:
1008             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1009             char *_image_id = image_id
1010             char *_name = name
1011         with nogil:
1012             ret = rbd_trash_restore(_ioctx, _image_id, _name)
1013         if ret != 0:
1014             raise make_ex(ret, 'error restoring image from trash')
1015
1016     def mirror_mode_get(self, ioctx):
1017         """
1018         Get pool mirror mode.
1019
1020         :param ioctx: determines which RADOS pool is read
1021         :type ioctx: :class:`rados.Ioctx`
1022         :returns: int - pool mirror mode
1023         """
1024         cdef:
1025             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1026             rbd_mirror_mode_t mirror_mode
1027         with nogil:
1028             ret = rbd_mirror_mode_get(_ioctx, &mirror_mode)
1029         if ret != 0:
1030             raise make_ex(ret, 'error getting mirror mode')
1031         return mirror_mode
1032
1033     def mirror_mode_set(self, ioctx, mirror_mode):
1034         """
1035         Set pool mirror mode.
1036
1037         :param ioctx: determines which RADOS pool is written
1038         :type ioctx: :class:`rados.Ioctx`
1039         :param mirror_mode: mirror mode to set
1040         :type mirror_mode: int
1041         """
1042         cdef:
1043             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1044             rbd_mirror_mode_t _mirror_mode = mirror_mode
1045         with nogil:
1046             ret = rbd_mirror_mode_set(_ioctx, _mirror_mode)
1047         if ret != 0:
1048             raise make_ex(ret, 'error setting mirror mode')
1049
1050     def mirror_peer_add(self, ioctx, cluster_name, client_name):
1051         """
1052         Add mirror peer.
1053
1054         :param ioctx: determines which RADOS pool is used
1055         :type ioctx: :class:`rados.Ioctx`
1056         :param cluster_name: mirror peer cluster name
1057         :type cluster_name: str
1058         :param client_name: mirror peer client name
1059         :type client_name: str
1060         :returns: str - peer uuid
1061         """
1062         cluster_name = cstr(cluster_name, 'cluster_name')
1063         client_name = cstr(client_name, 'client_name')
1064         cdef:
1065             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1066             char *_uuid = NULL
1067             size_t _uuid_max_length = 512
1068             char *_cluster_name = cluster_name
1069             char *_client_name = client_name
1070         try:
1071             _uuid = <char *>realloc_chk(_uuid, _uuid_max_length)
1072             ret = rbd_mirror_peer_add(_ioctx, _uuid, _uuid_max_length,
1073                                       _cluster_name, _client_name)
1074             if ret != 0:
1075                 raise make_ex(ret, 'error adding mirror peer')
1076             return decode_cstr(_uuid)
1077         finally:
1078             free(_uuid)
1079
1080     def mirror_peer_remove(self, ioctx, uuid):
1081         """
1082         Remove mirror peer.
1083
1084         :param ioctx: determines which RADOS pool is used
1085         :type ioctx: :class:`rados.Ioctx`
1086         :param uuid: peer uuid
1087         :type uuid: str
1088         """
1089         uuid = cstr(uuid, 'uuid')
1090         cdef:
1091             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1092             char *_uuid = uuid
1093         with nogil:
1094             ret = rbd_mirror_peer_remove(_ioctx, _uuid)
1095         if ret != 0:
1096             raise make_ex(ret, 'error removing mirror peer')
1097
1098     def mirror_peer_list(self, ioctx):
1099         """
1100         Iterate over the peers of a pool.
1101
1102         :param ioctx: determines which RADOS pool is read
1103         :type ioctx: :class:`rados.Ioctx`
1104         :returns: :class:`MirrorPeerIterator`
1105         """
1106         return MirrorPeerIterator(ioctx)
1107
1108     def mirror_peer_set_client(self, ioctx, uuid, client_name):
1109         """
1110         Set mirror peer client name
1111
1112         :param ioctx: determines which RADOS pool is written
1113         :type ioctx: :class:`rados.Ioctx`
1114         :param uuid: uuid of the mirror peer
1115         :type uuid: str
1116         :param client_name: client name of the mirror peer to set
1117         :type client_name: str
1118         """
1119         uuid = cstr(uuid, 'uuid')
1120         client_name = cstr(client_name, 'client_name')
1121         cdef:
1122             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1123             char *_uuid = uuid
1124             char *_client_name = client_name
1125         with nogil:
1126             ret = rbd_mirror_peer_set_client(_ioctx, _uuid, _client_name)
1127         if ret != 0:
1128             raise make_ex(ret, 'error setting mirror peer client')
1129
1130     def mirror_peer_set_cluster(self, ioctx, uuid, cluster_name):
1131         """
1132         Set mirror peer cluster name
1133
1134         :param ioctx: determines which RADOS pool is written
1135         :type ioctx: :class:`rados.Ioctx`
1136         :param uuid: uuid of the mirror peer
1137         :type uuid: str
1138         :param cluster_name: cluster name of the mirror peer to set
1139         :type cluster_name: str
1140         """
1141         uuid = cstr(uuid, 'uuid')
1142         cluster_name = cstr(cluster_name, 'cluster_name')
1143         cdef:
1144             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1145             char *_uuid = uuid
1146             char *_cluster_name = cluster_name
1147         with nogil:
1148             ret = rbd_mirror_peer_set_cluster(_ioctx, _uuid, _cluster_name)
1149         if ret != 0:
1150             raise make_ex(ret, 'error setting mirror peer cluster')
1151
1152     def mirror_image_status_list(self, ioctx):
1153         """
1154         Iterate over the mirror image statuses of a pool.
1155
1156         :param ioctx: determines which RADOS pool is read
1157         :type ioctx: :class:`rados.Ioctx`
1158         :returns: :class:`MirrorImageStatus`
1159         """
1160         return MirrorImageStatusIterator(ioctx)
1161
1162     def mirror_image_status_summary(self, ioctx):
1163         """
1164         Get mirror image status summary of a pool.
1165
1166         :param ioctx: determines which RADOS pool is read
1167         :type ioctx: :class:`rados.Ioctx`
1168         :returns: list - a list of (state, count) tuples
1169         """
1170         cdef:
1171             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1172             rbd_mirror_image_status_state_t *states = NULL
1173             int *counts = NULL
1174             size_t maxlen = 32
1175         try:
1176             states = <rbd_mirror_image_status_state_t *>realloc_chk(states,
1177                 sizeof(rbd_mirror_image_status_state_t) * maxlen)
1178             counts = <int *>realloc_chk(counts, sizeof(int) * maxlen)
1179             with nogil:
1180                 ret = rbd_mirror_image_status_summary(_ioctx, states, counts,
1181                                                       &maxlen)
1182             if ret < 0:
1183                 raise make_ex(ret, 'error getting mirror image status summary')
1184             return [(states[i], counts[i]) for i in range(maxlen)]
1185         finally:
1186             free(states)
1187             free(counts)
1188
1189 cdef class MirrorPeerIterator(object):
1190     """
1191     Iterator over mirror peer info for a pool.
1192
1193     Yields a dictionary containing information about a peer.
1194
1195     Keys are:
1196
1197     * ``uuid`` (str) - uuid of the peer
1198
1199     * ``cluster_name`` (str) - cluster name of the peer
1200
1201     * ``client_name`` (str) - client name of the peer
1202     """
1203
1204     cdef:
1205         rbd_mirror_peer_t *peers
1206         int num_peers
1207
1208     def __init__(self, ioctx):
1209         cdef:
1210             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1211         self.peers = NULL
1212         self.num_peers = 10
1213         while True:
1214             self.peers = <rbd_mirror_peer_t *>realloc_chk(
1215                 self.peers, self.num_peers * sizeof(rbd_mirror_peer_t))
1216             with nogil:
1217                 ret = rbd_mirror_peer_list(_ioctx, self.peers, &self.num_peers)
1218             if ret < 0:
1219                 if ret == -errno.ERANGE:
1220                     continue
1221                 self.num_peers = 0
1222                 raise make_ex(ret, 'error listing peers')
1223             break
1224
1225     def __iter__(self):
1226         for i in range(self.num_peers):
1227             yield {
1228                 'uuid'         : decode_cstr(self.peers[i].uuid),
1229                 'cluster_name' : decode_cstr(self.peers[i].cluster_name),
1230                 'client_name'  : decode_cstr(self.peers[i].client_name),
1231                 }
1232
1233     def __dealloc__(self):
1234         if self.peers:
1235             rbd_mirror_peer_list_cleanup(self.peers, self.num_peers)
1236             free(self.peers)
1237
1238 cdef class MirrorImageStatusIterator(object):
1239     """
1240     Iterator over mirror image status for a pool.
1241
1242     Yields a dictionary containing mirror status of an image.
1243
1244     Keys are:
1245
1246         * ``name`` (str) - mirror image name
1247
1248         * `info` (dict) - mirror image info
1249
1250         * `state` (int) - mirror state
1251
1252         * `description` (str) - status description
1253
1254         * `last_update` (datetime) - last status update time
1255
1256         * ``up`` (bool) - is mirroring agent up
1257     """
1258
1259     cdef:
1260         rados_ioctx_t ioctx
1261         size_t max_read
1262         char *last_read
1263         char **image_ids
1264         rbd_mirror_image_status_t *images
1265         size_t size
1266
1267     def __init__(self, ioctx):
1268         self.ioctx = convert_ioctx(ioctx)
1269         self.max_read = 1024
1270         self.last_read = strdup("")
1271         self.image_ids = <char **>realloc_chk(NULL,
1272             sizeof(char *) * self.max_read)
1273         self.images = <rbd_mirror_image_status_t *>realloc_chk(NULL,
1274             sizeof(rbd_mirror_image_status_t) * self.max_read)
1275         self.size = 0
1276         self.get_next_chunk()
1277
1278     def __iter__(self):
1279         while self.size > 0:
1280             for i in range(self.size):
1281                 yield {
1282                     'name'        : decode_cstr(self.images[i].name),
1283                     'info'        : {
1284                         'global_id' : decode_cstr(self.images[i].info.global_id),
1285                         'state'     : self.images[i].info.state,
1286                         },
1287                     'state'       : self.images[i].state,
1288                     'description' : decode_cstr(self.images[i].description),
1289                     'last_update' : datetime.fromtimestamp(self.images[i].last_update),
1290                     'up'          : self.images[i].up,
1291                     }
1292             if self.size < self.max_read:
1293                 break
1294             self.get_next_chunk()
1295
1296     def __dealloc__(self):
1297         rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1298                                              self.size)
1299         if self.last_read:
1300             free(self.last_read)
1301         if self.image_ids:
1302             free(self.image_ids)
1303         if self.images:
1304             free(self.images)
1305
1306     def get_next_chunk(self):
1307         if self.size > 0:
1308             rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1309                                                  self.size)
1310             self.size = 0
1311         with nogil:
1312             ret = rbd_mirror_image_status_list(self.ioctx, self.last_read,
1313                                                self.max_read, self.image_ids,
1314                                                self.images, &self.size)
1315         if ret < 0:
1316             raise make_ex(ret, 'error listing mirror images status')
1317         if self.size > 0:
1318             free(self.last_read)
1319             last_read = decode_cstr(self.image_ids[self.size - 1])
1320             self.last_read = strdup(last_read)
1321         else:
1322             free(self.last_read)
1323             self.last_read = strdup("")
1324
1325 cdef int diff_iterate_cb(uint64_t offset, size_t length, int write, void *cb) \
1326     except? -9000 with gil:
1327     # Make sure that if we wound up with an exception from a previous callback,
1328     # we stop calling back (just in case librbd ever fails to bail out on the
1329     # first negative return, as older versions did)
1330     if exc.PyErr_Occurred():
1331         return -9000
1332     ret = (<object>cb)(offset, length, bool(write))
1333     if ret is None:
1334         return 0
1335     return ret
1336
1337
1338 cdef class Image(object):
1339     """
1340     This class represents an RBD image. It is used to perform I/O on
1341     the image and interact with snapshots.
1342
1343     **Note**: Any method of this class may raise :class:`ImageNotFound`
1344     if the image has been deleted.
1345     """
1346     cdef rbd_image_t image
1347     cdef bint closed
1348     cdef object name
1349     cdef object ioctx
1350     cdef rados_ioctx_t _ioctx
1351
1352     def __init__(self, ioctx, name, snapshot=None, read_only=False):
1353         """
1354         Open the image at the given snapshot.
1355         If a snapshot is specified, the image will be read-only, unless
1356         :func:`Image.set_snap` is called later.
1357
1358         If read-only mode is used, metadata for the :class:`Image`
1359         object (such as which snapshots exist) may become obsolete. See
1360         the C api for more details.
1361
1362         To clean up from opening the image, :func:`Image.close` should
1363         be called.  For ease of use, this is done automatically when
1364         an :class:`Image` is used as a context manager (see :pep:`343`).
1365
1366         :param ioctx: determines which RADOS pool the image is in
1367         :type ioctx: :class:`rados.Ioctx`
1368         :param name: the name of the image
1369         :type name: str
1370         :param snapshot: which snapshot to read from
1371         :type snaphshot: str
1372         :param read_only: whether to open the image in read-only mode
1373         :type read_only: bool
1374         """
1375         name = cstr(name, 'name')
1376         snapshot = cstr(snapshot, 'snapshot', opt=True)
1377         self.closed = True
1378         self.name = name
1379         # Keep around a reference to the ioctx, so it won't get deleted
1380         self.ioctx = ioctx
1381         cdef:
1382             rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1383             char *_name = name
1384             char *_snapshot = opt_str(snapshot)
1385         if read_only:
1386             with nogil:
1387                 ret = rbd_open_read_only(_ioctx, _name, &self.image, _snapshot)
1388         else:
1389             with nogil:
1390                 ret = rbd_open(_ioctx, _name, &self.image, _snapshot)
1391         if ret != 0:
1392             raise make_ex(ret, 'error opening image %s at snapshot %s' % (name, snapshot))
1393         self.closed = False
1394
1395     def __enter__(self):
1396         return self
1397
1398     def __exit__(self, type_, value, traceback):
1399         """
1400         Closes the image. See :func:`close`
1401         """
1402         self.close()
1403         return False
1404
1405     def __get_completion(self, oncomplete):
1406         """
1407         Constructs a completion to use with asynchronous operations
1408
1409         :param oncomplete: callback for the completion
1410
1411         :raises: :class:`Error`
1412         :returns: completion object
1413         """
1414
1415         completion_obj = Completion(self, oncomplete)
1416
1417         cdef:
1418             rbd_completion_t completion
1419             PyObject* p_completion_obj= <PyObject*>completion_obj
1420
1421         with nogil:
1422             ret = rbd_aio_create_completion(p_completion_obj, __aio_complete_cb,
1423                                             &completion)
1424         if ret < 0:
1425             raise make_ex(ret, "error getting a completion")
1426
1427         completion_obj.rbd_comp = completion
1428         return completion_obj
1429
1430     def close(self):
1431         """
1432         Release the resources used by this image object.
1433
1434         After this is called, this object should not be used.
1435         """
1436         if not self.closed:
1437             self.closed = True
1438             with nogil:
1439                 ret = rbd_close(self.image)
1440             if ret < 0:
1441                 raise make_ex(ret, 'error while closing image %s' % (
1442                               self.name,))
1443
1444     def __dealloc__(self):
1445         self.close()
1446
1447     def __repr__(self):
1448         return "rbd.Image(ioctx, %r)" % self.name
1449
1450     def resize(self, size):
1451         """
1452         Change the size of the image.
1453
1454         :param size: the new size of the image
1455         :type size: int
1456         """
1457         cdef uint64_t _size = size
1458         with nogil:
1459             ret = rbd_resize(self.image, _size)
1460         if ret < 0:
1461             raise make_ex(ret, 'error resizing image %s' % (self.name,))
1462
1463     def stat(self):
1464         """
1465         Get information about the image. Currently parent pool and
1466         parent name are always -1 and ''.
1467
1468         :returns: dict - contains the following keys:
1469
1470             * ``size`` (int) - the size of the image in bytes
1471
1472             * ``obj_size`` (int) - the size of each object that comprises the
1473               image
1474
1475             * ``num_objs`` (int) - the number of objects in the image
1476
1477             * ``order`` (int) - log_2(object_size)
1478
1479             * ``block_name_prefix`` (str) - the prefix of the RADOS objects used
1480               to store the image
1481
1482             * ``parent_pool`` (int) - deprecated
1483
1484             * ``parent_name``  (str) - deprecated
1485
1486             See also :meth:`format` and :meth:`features`.
1487
1488         """
1489         cdef rbd_image_info_t info
1490         with nogil:
1491             ret = rbd_stat(self.image, &info, sizeof(info))
1492         if ret != 0:
1493             raise make_ex(ret, 'error getting info for image %s' % (self.name,))
1494         return {
1495             'size'              : info.size,
1496             'obj_size'          : info.obj_size,
1497             'num_objs'          : info.num_objs,
1498             'order'             : info.order,
1499             'block_name_prefix' : decode_cstr(info.block_name_prefix),
1500             'parent_pool'       : info.parent_pool,
1501             'parent_name'       : info.parent_name
1502             }
1503
1504     def id(self):
1505         """
1506         Get the RBD v2 internal image id
1507
1508         :returns: str - image id
1509         """
1510         cdef:
1511             int ret = -errno.ERANGE
1512             size_t size = 32
1513             char *image_id = NULL
1514         try:
1515             while ret == -errno.ERANGE and size <= 4096:
1516                 image_id =  <char *>realloc_chk(image_id, size)
1517                 with nogil:
1518                     ret = rbd_get_id(self.image, image_id, size)
1519                 if ret == -errno.ERANGE:
1520                     size *= 2
1521
1522             if ret != 0:
1523                 raise make_ex(ret, 'error getting id for image %s' % (self.name,))
1524             return decode_cstr(image_id)
1525         finally:
1526             free(image_id)
1527
1528     def block_name_prefix(self):
1529         """
1530         Get the RBD block name prefix
1531
1532         :returns: str - block name prefix
1533         """
1534         cdef:
1535             int ret = -errno.ERANGE
1536             size_t size = 32
1537             char *prefix = NULL
1538         try:
1539             while ret == -errno.ERANGE and size <= 4096:
1540                 prefix =  <char *>realloc_chk(prefix, size)
1541                 with nogil:
1542                     ret = rbd_get_block_name_prefix(self.image, prefix, size)
1543                 if ret == -errno.ERANGE:
1544                     size *= 2
1545
1546             if ret != 0:
1547                 raise make_ex(ret, 'error getting block name prefix for image %s' % (self.name,))
1548             return decode_cstr(prefix)
1549         finally:
1550             free(prefix)
1551
1552     def parent_info(self):
1553         """
1554         Get information about a cloned image's parent (if any)
1555
1556         :returns: tuple - ``(pool name, image name, snapshot name)`` components
1557                   of the parent image
1558         :raises: :class:`ImageNotFound` if the image doesn't have a parent
1559         """
1560         cdef:
1561             int ret = -errno.ERANGE
1562             size_t size = 8
1563             char *pool = NULL
1564             char *name = NULL
1565             char *snapname = NULL
1566         try:
1567             while ret == -errno.ERANGE and size <= 4096:
1568                 pool = <char *>realloc_chk(pool, size)
1569                 name = <char *>realloc_chk(name, size)
1570                 snapname = <char *>realloc_chk(snapname, size)
1571                 with nogil:
1572                     ret = rbd_get_parent_info2(self.image, pool, size, name,
1573                                                size, NULL, 0, snapname, size)
1574                 if ret == -errno.ERANGE:
1575                     size *= 2
1576
1577             if ret != 0:
1578                 raise make_ex(ret, 'error getting parent info for image %s' % (self.name,))
1579             return (decode_cstr(pool), decode_cstr(name), decode_cstr(snapname))
1580         finally:
1581             free(pool)
1582             free(name)
1583             free(snapname)
1584
1585     def parent_id(self):
1586         """
1587         Get image id of a cloned image's parent (if any)
1588
1589         :returns: str - the parent id
1590         :raises: :class:`ImageNotFound` if the image doesn't have a parent
1591         """
1592         cdef:
1593             int ret = -errno.ERANGE
1594             size_t size = 32
1595             char *parent_id = NULL
1596         try:
1597             while ret == -errno.ERANGE and size <= 4096:
1598                 parent_id = <char *>realloc_chk(parent_id, size)
1599                 with nogil:
1600                     ret = rbd_get_parent_info2(self.image, NULL, 0, NULL, 0,
1601                                                parent_id, size, NULL, 0)
1602                 if ret == -errno.ERANGE:
1603                     size *= 2
1604
1605             if ret != 0:
1606                 raise make_ex(ret, 'error getting parent id for image %s' % (self.name,))
1607             return decode_cstr(parent_id)
1608         finally:
1609             free(parent_id)
1610
1611     def old_format(self):
1612         """
1613         Find out whether the image uses the old RBD format.
1614
1615         :returns: bool - whether the image uses the old RBD format
1616         """
1617         cdef uint8_t old
1618         with nogil:
1619             ret = rbd_get_old_format(self.image, &old)
1620         if ret != 0:
1621             raise make_ex(ret, 'error getting old_format for image %s' % (self.name))
1622         return old != 0
1623
1624     def size(self):
1625         """
1626         Get the size of the image. If open to a snapshot, returns the
1627         size of that snapshot.
1628
1629         :returns: the size of the image in bytes
1630         """
1631         cdef uint64_t image_size
1632         with nogil:
1633             ret = rbd_get_size(self.image, &image_size)
1634         if ret != 0:
1635             raise make_ex(ret, 'error getting size for image %s' % (self.name))
1636         return image_size
1637
1638     def features(self):
1639         """
1640         Get the features bitmask of the image.
1641
1642         :returns: int - the features bitmask of the image
1643         """
1644         cdef uint64_t features
1645         with nogil:
1646             ret = rbd_get_features(self.image, &features)
1647         if ret != 0:
1648             raise make_ex(ret, 'error getting features for image %s' % (self.name))
1649         return features
1650
1651     def update_features(self, features, enabled):
1652         """
1653         Update the features bitmask of the image by enabling/disabling
1654         a single feature.  The feature must support the ability to be
1655         dynamically enabled/disabled.
1656
1657         :param features: feature bitmask to enable/disable
1658         :type features: int
1659         :param enabled: whether to enable/disable the feature
1660         :type enabled: bool
1661         :raises: :class:`InvalidArgument`
1662         """
1663         cdef:
1664             uint64_t _features = features
1665             uint8_t _enabled = bool(enabled)
1666         with nogil:
1667             ret = rbd_update_features(self.image, _features, _enabled)
1668         if ret != 0:
1669             raise make_ex(ret, 'error updating features for image %s' %
1670                                (self.name))
1671
1672     def overlap(self):
1673         """
1674         Get the number of overlapping bytes between the image and its parent
1675         image. If open to a snapshot, returns the overlap between the snapshot
1676         and the parent image.
1677
1678         :returns: int - the overlap in bytes
1679         :raises: :class:`ImageNotFound` if the image doesn't have a parent
1680         """
1681         cdef uint64_t overlap
1682         with nogil:
1683             ret = rbd_get_overlap(self.image, &overlap)
1684         if ret != 0:
1685             raise make_ex(ret, 'error getting overlap for image %s' % (self.name))
1686         return overlap
1687
1688     def flags(self):
1689         """
1690         Get the flags bitmask of the image.
1691
1692         :returns: int - the flags bitmask of the image
1693         """
1694         cdef uint64_t flags
1695         with nogil:
1696             ret = rbd_get_flags(self.image, &flags)
1697         if ret != 0:
1698             raise make_ex(ret, 'error getting flags for image %s' % (self.name))
1699         return flags
1700
1701     def is_exclusive_lock_owner(self):
1702         """
1703         Get the status of the image exclusive lock.
1704
1705         :returns: bool - true if the image is exclusively locked
1706         """
1707         cdef int owner
1708         with nogil:
1709             ret = rbd_is_exclusive_lock_owner(self.image, &owner)
1710         if ret != 0:
1711             raise make_ex(ret, 'error getting lock status for image %s' % (self.name))
1712         return owner == 1
1713
1714     def copy(self, dest_ioctx, dest_name, features=None, order=None,
1715              stripe_unit=None, stripe_count=None, data_pool=None):
1716         """
1717         Copy the image to another location.
1718
1719         :param dest_ioctx: determines which pool to copy into
1720         :type dest_ioctx: :class:`rados.Ioctx`
1721         :param dest_name: the name of the copy
1722         :type dest_name: str
1723         :param features: bitmask of features to enable; if set, must include layering
1724         :type features: int
1725         :param order: the image is split into (2**order) byte objects
1726         :type order: int
1727         :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
1728         :type stripe_unit: int
1729         :param stripe_count: objects to stripe over before looping
1730         :type stripe_count: int
1731         :param data_pool: optional separate pool for data blocks
1732         :type data_pool: str
1733         :raises: :class:`TypeError`
1734         :raises: :class:`InvalidArgument`
1735         :raises: :class:`ImageExists`
1736         :raises: :class:`FunctionNotSupported`
1737         :raises: :class:`ArgumentOutOfRange`
1738         """
1739         dest_name = cstr(dest_name, 'dest_name')
1740         cdef:
1741             rados_ioctx_t _dest_ioctx = convert_ioctx(dest_ioctx)
1742             char *_dest_name = dest_name
1743             rbd_image_options_t opts
1744
1745         rbd_image_options_create(&opts)
1746         try:
1747             if features is not None:
1748                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
1749                                              features)
1750             if order is not None:
1751                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
1752                                              order)
1753             if stripe_unit is not None:
1754                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
1755                                              stripe_unit)
1756             if stripe_count is not None:
1757                 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
1758                                              stripe_count)
1759             if data_pool is not None:
1760                 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
1761                                              data_pool)
1762             with nogil:
1763                 ret = rbd_copy3(self.image, _dest_ioctx, _dest_name, opts)
1764         finally:
1765             rbd_image_options_destroy(opts)
1766         if ret < 0:
1767             raise make_ex(ret, 'error copying image %s to %s' % (self.name, dest_name))
1768
1769     def list_snaps(self):
1770         """
1771         Iterate over the snapshots of an image.
1772
1773         :returns: :class:`SnapIterator`
1774         """
1775         return SnapIterator(self)
1776
1777     def create_snap(self, name):
1778         """
1779         Create a snapshot of the image.
1780
1781         :param name: the name of the snapshot
1782         :type name: str
1783         :raises: :class:`ImageExists`
1784         """
1785         name = cstr(name, 'name')
1786         cdef char *_name = name
1787         with nogil:
1788             ret = rbd_snap_create(self.image, _name)
1789         if ret != 0:
1790             raise make_ex(ret, 'error creating snapshot %s from %s' % (name, self.name))
1791
1792     def rename_snap(self, srcname, dstname):
1793         """
1794         rename a snapshot of the image.
1795
1796         :param srcname: the src name of the snapshot
1797         :type srcname: str
1798         :param dstname: the dst name of the snapshot
1799         :type dstname: str
1800         :raises: :class:`ImageExists`
1801         """
1802         srcname = cstr(srcname, 'srcname')
1803         dstname = cstr(dstname, 'dstname')
1804         cdef:
1805             char *_srcname = srcname
1806             char *_dstname = dstname
1807         with nogil:
1808             ret = rbd_snap_rename(self.image, _srcname, _dstname)
1809         if ret != 0:
1810             raise make_ex(ret, 'error renaming snapshot of %s from %s to %s' % (self.name, srcname, dstname))
1811
1812     def remove_snap(self, name):
1813         """
1814         Delete a snapshot of the image.
1815
1816         :param name: the name of the snapshot
1817         :type name: str
1818         :raises: :class:`IOError`, :class:`ImageBusy`
1819         """
1820         name = cstr(name, 'name')
1821         cdef char *_name = name
1822         with nogil:
1823             ret = rbd_snap_remove(self.image, _name)
1824         if ret != 0:
1825             raise make_ex(ret, 'error removing snapshot %s from %s' % (name, self.name))
1826
1827     def remove_snap2(self, name, flags):
1828         """
1829         Delete a snapshot of the image.
1830
1831         :param name: the name of the snapshot
1832         :param flags: the flags for removal
1833         :type name: str
1834         :raises: :class:`IOError`, :class:`ImageBusy`
1835         """
1836         name = cstr(name, 'name')
1837         cdef:
1838             char *_name = name
1839             uint32_t _flags = flags
1840             librbd_progress_fn_t prog_cb = &no_op_progress_callback
1841         with nogil:
1842             ret = rbd_snap_remove2(self.image, _name, _flags, prog_cb, NULL)
1843         if ret != 0:
1844             raise make_ex(ret, 'error removing snapshot %s from %s with flags %llx' % (name, self.name, flags))
1845
1846     def rollback_to_snap(self, name):
1847         """
1848         Revert the image to its contents at a snapshot. This is a
1849         potentially expensive operation, since it rolls back each
1850         object individually.
1851
1852         :param name: the snapshot to rollback to
1853         :type name: str
1854         :raises: :class:`IOError`
1855         """
1856         name = cstr(name, 'name')
1857         cdef char *_name = name
1858         with nogil:
1859             ret = rbd_snap_rollback(self.image, _name)
1860         if ret != 0:
1861             raise make_ex(ret, 'error rolling back image %s to snapshot %s' % (self.name, name))
1862
1863     def protect_snap(self, name):
1864         """
1865         Mark a snapshot as protected. This means it can't be deleted
1866         until it is unprotected.
1867
1868         :param name: the snapshot to protect
1869         :type name: str
1870         :raises: :class:`IOError`, :class:`ImageNotFound`
1871         """
1872         name = cstr(name, 'name')
1873         cdef char *_name = name
1874         with nogil:
1875             ret = rbd_snap_protect(self.image, _name)
1876         if ret != 0:
1877             raise make_ex(ret, 'error protecting snapshot %s@%s' % (self.name, name))
1878
1879     def unprotect_snap(self, name):
1880         """
1881         Mark a snapshot unprotected. This allows it to be deleted if
1882         it was protected.
1883
1884         :param name: the snapshot to unprotect
1885         :type name: str
1886         :raises: :class:`IOError`, :class:`ImageNotFound`
1887         """
1888         name = cstr(name, 'name')
1889         cdef char *_name = name
1890         with nogil:
1891             ret = rbd_snap_unprotect(self.image, _name)
1892         if ret != 0:
1893             raise make_ex(ret, 'error unprotecting snapshot %s@%s' % (self.name, name))
1894
1895     def is_protected_snap(self, name):
1896         """
1897         Find out whether a snapshot is protected from deletion.
1898
1899         :param name: the snapshot to check
1900         :type name: str
1901         :returns: bool - whether the snapshot is protected
1902         :raises: :class:`IOError`, :class:`ImageNotFound`
1903         """
1904         name = cstr(name, 'name')
1905         cdef:
1906             char *_name = name
1907             int is_protected
1908         with nogil:
1909             ret = rbd_snap_is_protected(self.image, _name, &is_protected)
1910         if ret != 0:
1911             raise make_ex(ret, 'error checking if snapshot %s@%s is protected' % (self.name, name))
1912         return is_protected == 1
1913
1914     def get_snap_limit(self):
1915         """
1916         Get the snapshot limit for an image.
1917         """
1918
1919         cdef:
1920             uint64_t limit
1921         with nogil:
1922             ret = rbd_snap_get_limit(self.image, &limit)
1923         if ret != 0:
1924             raise make_ex(ret, 'error getting snapshot limit for %s' % self.name)
1925         return limit
1926
1927     def set_snap_limit(self, limit):
1928         """
1929         Set the snapshot limit for an image.
1930
1931         :param limit: the new limit to set
1932         """
1933
1934         cdef:
1935             uint64_t _limit = limit
1936         with nogil:
1937             ret = rbd_snap_set_limit(self.image, _limit)
1938         if ret != 0:
1939             raise make_ex(ret, 'error setting snapshot limit for %s' % self.name)
1940         return ret
1941
1942     def get_snap_timestamp(self, snap_id):
1943         """
1944         Get the snapshot timestamp for an image.
1945         :param snap_id: the snapshot id of a snap shot
1946         """
1947         cdef:
1948             timespec timestamp
1949             uint64_t _snap_id = snap_id
1950         with nogil:
1951             ret = rbd_snap_get_timestamp(self.image, _snap_id, &timestamp)
1952         if ret != 0:
1953             raise make_ex(ret, 'error getting snapshot timestamp for image: %s, snap_id: %d' % (self.name, snap_id))
1954         return datetime.fromtimestamp(timestamp.tv_sec)
1955
1956     def remove_snap_limit(self):
1957         """
1958         Remove the snapshot limit for an image, essentially setting
1959         the limit to the maximum size allowed by the implementation.
1960         """
1961         with nogil:
1962             ret = rbd_snap_set_limit(self.image, UINT64_MAX)
1963         if ret != 0:
1964             raise make_ex(ret, 'error removing snapshot limit for %s' % self.name)
1965         return ret
1966
1967     def set_snap(self, name):
1968         """
1969         Set the snapshot to read from. Writes will raise ReadOnlyImage
1970         while a snapshot is set. Pass None to unset the snapshot
1971         (reads come from the current image) , and allow writing again.
1972
1973         :param name: the snapshot to read from, or None to unset the snapshot
1974         :type name: str or None
1975         """
1976         name = cstr(name, 'name', opt=True)
1977         cdef char *_name = opt_str(name)
1978         with nogil:
1979             ret = rbd_snap_set(self.image, _name)
1980         if ret != 0:
1981             raise make_ex(ret, 'error setting image %s to snapshot %s' % (self.name, name))
1982
1983     def read(self, offset, length, fadvise_flags=0):
1984         """
1985         Read data from the image. Raises :class:`InvalidArgument` if
1986         part of the range specified is outside the image.
1987
1988         :param offset: the offset to start reading at
1989         :type offset: int
1990         :param length: how many bytes to read
1991         :type length: int
1992         :param fadvise_flags: fadvise flags for this read
1993         :type fadvise_flags: int
1994         :returns: str - the data read
1995         :raises: :class:`InvalidArgument`, :class:`IOError`
1996         """
1997
1998         # This usage of the Python API allows us to construct a string
1999         # that librbd directly reads into, avoiding an extra copy. Although
2000         # strings are normally immutable, this usage is explicitly supported
2001         # for freshly created string objects.
2002         cdef:
2003             char *ret_buf
2004             uint64_t _offset = offset
2005             size_t _length = length
2006             int _fadvise_flags = fadvise_flags
2007             PyObject* ret_s = NULL
2008         ret_s = PyBytes_FromStringAndSize(NULL, length)
2009         try:
2010             ret_buf = PyBytes_AsString(ret_s)
2011             with nogil:
2012                 ret = rbd_read2(self.image, _offset, _length, ret_buf,
2013                                 _fadvise_flags)
2014             if ret < 0:
2015                 raise make_ex(ret, 'error reading %s %ld~%ld' % (self.name, offset, length))
2016
2017             if ret != <ssize_t>length:
2018                 _PyBytes_Resize(&ret_s, ret)
2019
2020             return <object>ret_s
2021         finally:
2022             # We DECREF unconditionally: the cast to object above will have
2023             # INCREFed if necessary. This also takes care of exceptions,
2024             # including if _PyString_Resize fails (that will free the string
2025             # itself and set ret_s to NULL, hence XDECREF).
2026             ref.Py_XDECREF(ret_s)
2027
2028     def diff_iterate(self, offset, length, from_snapshot, iterate_cb,
2029                      include_parent = True, whole_object = False):
2030         """
2031         Iterate over the changed extents of an image.
2032
2033         This will call iterate_cb with three arguments:
2034
2035         (offset, length, exists)
2036
2037         where the changed extent starts at offset bytes, continues for
2038         length bytes, and is full of data (if exists is True) or zeroes
2039         (if exists is False).
2040
2041         If from_snapshot is None, it is interpreted as the beginning
2042         of time and this generates all allocated extents.
2043
2044         The end version is whatever is currently selected (via set_snap)
2045         for the image.
2046
2047         iterate_cb may raise an exception, which will abort the diff and will be
2048         propagated to the caller.
2049
2050         Raises :class:`InvalidArgument` if from_snapshot is after
2051         the currently set snapshot.
2052
2053         Raises :class:`ImageNotFound` if from_snapshot is not the name
2054         of a snapshot of the image.
2055
2056         :param offset: start offset in bytes
2057         :type offset: int
2058         :param length: size of region to report on, in bytes
2059         :type length: int
2060         :param from_snapshot: starting snapshot name, or None
2061         :type from_snapshot: str or None
2062         :param iterate_cb: function to call for each extent
2063         :type iterate_cb: function acception arguments for offset,
2064                            length, and exists
2065         :param include_parent: True if full history diff should include parent
2066         :type include_parent: bool
2067         :param whole_object: True if diff extents should cover whole object
2068         :type whole_object: bool
2069         :raises: :class:`InvalidArgument`, :class:`IOError`,
2070                  :class:`ImageNotFound`
2071         """
2072         from_snapshot = cstr(from_snapshot, 'from_snapshot', opt=True)
2073         cdef:
2074             char *_from_snapshot = opt_str(from_snapshot)
2075             uint64_t _offset = offset, _length = length
2076             uint8_t _include_parent = include_parent
2077             uint8_t _whole_object = whole_object
2078         with nogil:
2079             ret = rbd_diff_iterate2(self.image, _from_snapshot, _offset,
2080                                     _length, _include_parent, _whole_object,
2081                                     &diff_iterate_cb, <void *>iterate_cb)
2082         if ret < 0:
2083             msg = 'error generating diff from snapshot %s' % from_snapshot
2084             raise make_ex(ret, msg)
2085
2086     def write(self, data, offset, fadvise_flags=0):
2087         """
2088         Write data to the image. Raises :class:`InvalidArgument` if
2089         part of the write would fall outside the image.
2090
2091         :param data: the data to be written
2092         :type data: bytes
2093         :param offset: where to start writing data
2094         :type offset: int
2095         :param fadvise_flags: fadvise flags for this write
2096         :type fadvise_flags: int
2097         :returns: int - the number of bytes written
2098         :raises: :class:`IncompleteWriteError`, :class:`LogicError`,
2099                  :class:`InvalidArgument`, :class:`IOError`
2100         """
2101         if not isinstance(data, bytes):
2102             raise TypeError('data must be a byte string')
2103         cdef:
2104             uint64_t _offset = offset, length = len(data)
2105             char *_data = data
2106             int _fadvise_flags = fadvise_flags
2107         with nogil:
2108             ret = rbd_write2(self.image, _offset, length, _data, _fadvise_flags)
2109
2110         if ret == <ssize_t>length:
2111             return ret
2112         elif ret < 0:
2113             raise make_ex(ret, "error writing to %s" % (self.name,))
2114         elif ret < <ssize_t>length:
2115             raise IncompleteWriteError("Wrote only %ld out of %ld bytes" % (ret, length))
2116         else:
2117             raise LogicError("logic error: rbd_write(%s) \
2118 returned %d, but %d was the maximum number of bytes it could have \
2119 written." % (self.name, ret, length))
2120
2121     def discard(self, offset, length):
2122         """
2123         Trim the range from the image. It will be logically filled
2124         with zeroes.
2125         """
2126         cdef uint64_t _offset = offset, _length = length
2127         with nogil:
2128             ret = rbd_discard(self.image, _offset, _length)
2129         if ret < 0:
2130             msg = 'error discarding region %d~%d' % (offset, length)
2131             raise make_ex(ret, msg)
2132
2133     def flush(self):
2134         """
2135         Block until all writes are fully flushed if caching is enabled.
2136         """
2137         with nogil:
2138             ret = rbd_flush(self.image)
2139         if ret < 0:
2140             raise make_ex(ret, 'error flushing image')
2141
2142     def invalidate_cache(self):
2143         """
2144         Drop any cached data for the image.
2145         """
2146         with nogil:
2147             ret = rbd_invalidate_cache(self.image)
2148         if ret < 0:
2149             raise make_ex(ret, 'error invalidating cache')
2150
2151     def stripe_unit(self):
2152         """
2153         Return the stripe unit used for the image.
2154         """
2155         cdef uint64_t stripe_unit
2156         with nogil:
2157             ret = rbd_get_stripe_unit(self.image, &stripe_unit)
2158         if ret != 0:
2159             raise make_ex(ret, 'error getting stripe unit for image %s' % (self.name))
2160         return stripe_unit
2161
2162     def stripe_count(self):
2163         """
2164         Return the stripe count used for the image.
2165         """
2166         cdef uint64_t stripe_count
2167         with nogil:
2168             ret = rbd_get_stripe_count(self.image, &stripe_count)
2169         if ret != 0:
2170             raise make_ex(ret, 'error getting stripe count for image %s' % (self.name))
2171         return stripe_count
2172
2173     def create_timestamp(self):
2174         """
2175         Return the create timestamp for the image.
2176         """
2177         cdef:
2178             timespec timestamp
2179         with nogil:
2180             ret = rbd_get_create_timestamp(self.image, &timestamp)
2181         if ret != 0:
2182             raise make_ex(ret, 'error getting create timestamp for image: %s' % (self.name))
2183         return datetime.fromtimestamp(timestamp.tv_sec)
2184
2185     def flatten(self):
2186         """
2187         Flatten clone image (copy all blocks from parent to child)
2188         """
2189         with nogil:
2190             ret = rbd_flatten(self.image)
2191         if ret < 0:
2192             raise make_ex(ret, "error flattening %s" % self.name)
2193
2194     def rebuild_object_map(self):
2195         """
2196         Rebuild the object map for the image HEAD or currently set snapshot
2197         """
2198         cdef librbd_progress_fn_t prog_cb = &no_op_progress_callback
2199         with nogil:
2200             ret = rbd_rebuild_object_map(self.image, prog_cb, NULL)
2201         if ret < 0:
2202             raise make_ex(ret, "error rebuilding object map %s" % self.name)
2203
2204     def list_children(self):
2205         """
2206         List children of the currently set snapshot (set via set_snap()).
2207
2208         :returns: list - a list of (pool name, image name) tuples
2209         """
2210         cdef:
2211             size_t pools_size = 512, images_size = 512
2212             char *c_pools = NULL
2213             char *c_images = NULL
2214         try:
2215             while True:
2216                 c_pools = <char *>realloc_chk(c_pools, pools_size)
2217                 c_images = <char *>realloc_chk(c_images, images_size)
2218                 with nogil:
2219                     ret = rbd_list_children(self.image, c_pools, &pools_size,
2220                                             c_images, &images_size)
2221                 if ret >= 0:
2222                     break
2223                 elif ret != -errno.ERANGE:
2224                     raise make_ex(ret, 'error listing images')
2225             if ret == 0:
2226                 return []
2227             pools = map(decode_cstr, c_pools[:pools_size - 1].split(b'\0'))
2228             images = map(decode_cstr, c_images[:images_size - 1].split(b'\0'))
2229             return list(zip(pools, images))
2230         finally:
2231             free(c_pools)
2232             free(c_images)
2233
2234     def list_lockers(self):
2235         """
2236         List clients that have locked the image and information
2237         about the lock.
2238
2239         :returns: dict - contains the following keys:
2240
2241                   * ``tag`` - the tag associated with the lock (every
2242                     additional locker must use the same tag)
2243                   * ``exclusive`` - boolean indicating whether the
2244                      lock is exclusive or shared
2245                   * ``lockers`` - a list of (client, cookie, address)
2246                     tuples
2247         """
2248         cdef:
2249             size_t clients_size = 512, cookies_size = 512
2250             size_t addrs_size = 512, tag_size = 512
2251             int exclusive = 0
2252             char *c_clients = NULL
2253             char *c_cookies = NULL
2254             char *c_addrs = NULL
2255             char *c_tag = NULL
2256
2257         try:
2258             while True:
2259                 c_clients = <char *>realloc_chk(c_clients, clients_size)
2260                 c_cookies = <char *>realloc_chk(c_cookies, cookies_size)
2261                 c_addrs = <char *>realloc_chk(c_addrs, addrs_size)
2262                 c_tag = <char *>realloc_chk(c_tag, tag_size)
2263                 with nogil:
2264                     ret = rbd_list_lockers(self.image, &exclusive,
2265                                            c_tag, &tag_size,
2266                                            c_clients, &clients_size,
2267                                            c_cookies, &cookies_size,
2268                                            c_addrs, &addrs_size)
2269                 if ret >= 0:
2270                     break
2271                 elif ret != -errno.ERANGE:
2272                     raise make_ex(ret, 'error listing images')
2273             if ret == 0:
2274                 return []
2275             clients = map(decode_cstr, c_clients[:clients_size - 1].split(b'\0'))
2276             cookies = map(decode_cstr, c_cookies[:cookies_size - 1].split(b'\0'))
2277             addrs = map(decode_cstr, c_addrs[:addrs_size - 1].split(b'\0'))
2278             return {
2279                 'tag'       : decode_cstr(c_tag),
2280                 'exclusive' : exclusive == 1,
2281                 'lockers'   : list(zip(clients, cookies, addrs)),
2282                 }
2283         finally:
2284             free(c_clients)
2285             free(c_cookies)
2286             free(c_addrs)
2287             free(c_tag)
2288
2289     def lock_acquire(self, lock_mode):
2290         """
2291         Acquire a managed lock on the image.
2292
2293         :param lock_mode: lock mode to set
2294         :type lock_mode: int
2295         :raises: :class:`ImageBusy` if the lock could not be acquired
2296         """
2297         cdef:
2298             rbd_lock_mode_t _lock_mode = lock_mode
2299         with nogil:
2300             ret = rbd_lock_acquire(self.image, _lock_mode)
2301         if ret < 0:
2302             raise make_ex(ret, 'error acquiring lock on image')
2303
2304     def lock_release(self):
2305         """
2306         Release a managed lock on the image that was previously acquired.
2307         """
2308         with nogil:
2309             ret = rbd_lock_release(self.image)
2310         if ret < 0:
2311             raise make_ex(ret, 'error releasing lock on image')
2312
2313     def lock_get_owners(self):
2314         """
2315         Iterate over the lock owners of an image.
2316
2317         :returns: :class:`LockOwnerIterator`
2318         """
2319         return LockOwnerIterator(self)
2320
2321     def lock_break(self, lock_mode, lock_owner):
2322         """
2323         Break the image lock held by a another client.
2324
2325         :param lock_owner: the owner of the lock to break
2326         :type lock_owner: str
2327         """
2328         lock_owner = cstr(lock_owner, 'lock_owner')
2329         cdef:
2330             rbd_lock_mode_t _lock_mode = lock_mode
2331             char *_lock_owner = lock_owner
2332         with nogil:
2333             ret = rbd_lock_break(self.image, _lock_mode, _lock_owner)
2334         if ret < 0:
2335             raise make_ex(ret, 'error breaking lock on image')
2336
2337     def lock_exclusive(self, cookie):
2338         """
2339         Take an exclusive lock on the image.
2340
2341         :raises: :class:`ImageBusy` if a different client or cookie locked it
2342                  :class:`ImageExists` if the same client and cookie locked it
2343         """
2344         cookie = cstr(cookie, 'cookie')
2345         cdef char *_cookie = cookie
2346         with nogil:
2347             ret = rbd_lock_exclusive(self.image, _cookie)
2348         if ret < 0:
2349             raise make_ex(ret, 'error acquiring exclusive lock on image')
2350
2351     def lock_shared(self, cookie, tag):
2352         """
2353         Take a shared lock on the image. The tag must match
2354         that of the existing lockers, if any.
2355
2356         :raises: :class:`ImageBusy` if a different client or cookie locked it
2357                  :class:`ImageExists` if the same client and cookie locked it
2358         """
2359         cookie = cstr(cookie, 'cookie')
2360         tag = cstr(tag, 'tag')
2361         cdef:
2362             char *_cookie = cookie
2363             char *_tag = tag
2364         with nogil:
2365             ret = rbd_lock_shared(self.image, _cookie, _tag)
2366         if ret < 0:
2367             raise make_ex(ret, 'error acquiring shared lock on image')
2368
2369     def unlock(self, cookie):
2370         """
2371         Release a lock on the image that was locked by this rados client.
2372         """
2373         cookie = cstr(cookie, 'cookie')
2374         cdef char *_cookie = cookie
2375         with nogil:
2376             ret = rbd_unlock(self.image, _cookie)
2377         if ret < 0:
2378             raise make_ex(ret, 'error unlocking image')
2379
2380     def break_lock(self, client, cookie):
2381         """
2382         Release a lock held by another rados client.
2383         """
2384         client = cstr(client, 'client')
2385         cookie = cstr(cookie, 'cookie')
2386         cdef:
2387             char *_client = client
2388             char *_cookie = cookie
2389         with nogil:
2390             ret = rbd_break_lock(self.image, _client, _cookie)
2391         if ret < 0:
2392             raise make_ex(ret, 'error unlocking image')
2393
2394     def mirror_image_enable(self):
2395         """
2396         Enable mirroring for the image.
2397         """
2398         with nogil:
2399             ret = rbd_mirror_image_enable(self.image)
2400         if ret < 0:
2401             raise make_ex(ret, 'error enabling mirroring for image %s'
2402                           % (self.name,))
2403
2404     def mirror_image_disable(self, force):
2405         """
2406         Disable mirroring for the image.
2407
2408         :param force: force disabling
2409         :type force: bool
2410         """
2411         cdef bint c_force = force
2412         with nogil:
2413             ret = rbd_mirror_image_disable(self.image, c_force)
2414         if ret < 0:
2415             raise make_ex(ret, 'error disabling mirroring for image %s' %
2416                           (self.name,))
2417
2418     def mirror_image_promote(self, force):
2419         """
2420         Promote the image to primary for mirroring.
2421
2422         :param force: force promoting
2423         :type force: bool
2424         """
2425         cdef bint c_force = force
2426         with nogil:
2427             ret = rbd_mirror_image_promote(self.image, c_force)
2428         if ret < 0:
2429             raise make_ex(ret, 'error promoting image %s to primary' %
2430                           (self.name,))
2431
2432     def mirror_image_demote(self):
2433         """
2434         Demote the image to secondary for mirroring.
2435         """
2436         with nogil:
2437             ret = rbd_mirror_image_demote(self.image)
2438         if ret < 0:
2439             raise make_ex(ret, 'error demoting image %s to secondary' %
2440                           (self.name,))
2441
2442     def mirror_image_resync(self):
2443         """
2444         Flag the image to resync.
2445         """
2446         with nogil:
2447             ret = rbd_mirror_image_resync(self.image)
2448         if ret < 0:
2449             raise make_ex(ret, 'error to resync image %s' % (self.name,))
2450
2451     def mirror_image_get_info(self):
2452         """
2453         Get mirror info for the image.
2454
2455         :returns: dict - contains the following keys:
2456
2457             * ``global_id`` (str) - image global id
2458
2459             * ``state`` (int) - mirror state
2460
2461             * ``primary`` (bool) - is image primary
2462         """
2463         cdef rbd_mirror_image_info_t c_info
2464         with nogil:
2465             ret = rbd_mirror_image_get_info(self.image, &c_info, sizeof(c_info))
2466         if ret != 0:
2467             raise make_ex(ret, 'error getting mirror info for image %s' %
2468                           (self.name,))
2469         info = {
2470             'global_id' : decode_cstr(c_info.global_id),
2471             'state'     : int(c_info.state),
2472             'primary'   : c_info.primary,
2473             }
2474         free(c_info.global_id)
2475         return info
2476
2477     def mirror_image_get_status(self):
2478         """
2479         Get mirror status for the image.
2480
2481         :returns: dict - contains the following keys:
2482
2483             * ``name`` (str) - mirror image name
2484
2485             * `info` (dict) - mirror image info
2486
2487             * ``state`` (int) - status mirror state
2488
2489             * ``description`` (str) - status description
2490
2491             * ``last_update`` (datetime) - last status update time
2492
2493             * ``up`` (bool) - is mirroring agent up
2494         """
2495         cdef rbd_mirror_image_status_t c_status
2496         with nogil:
2497             ret = rbd_mirror_image_get_status(self.image, &c_status,
2498                                               sizeof(c_status))
2499         if ret != 0:
2500             raise make_ex(ret, 'error getting mirror status for image %s' %
2501                           (self.name,))
2502         status = {
2503             'name'      : decode_cstr(c_status.name),
2504             'info'      : {
2505                 'global_id' : decode_cstr(c_status.info.global_id),
2506                 'state'     : int(c_status.info.state),
2507                 'primary'   : c_status.info.primary,
2508                 },
2509             'state'       : c_status.state,
2510             'description' : decode_cstr(c_status.description),
2511             'last_update' : datetime.fromtimestamp(c_status.last_update),
2512             'up'          : c_status.up,
2513             }
2514         free(c_status.name)
2515         free(c_status.info.global_id)
2516         free(c_status.description)
2517         return status
2518
2519     def aio_read(self, offset, length, oncomplete, fadvise_flags=0):
2520         """
2521         Asynchronously read data from the image
2522
2523         Raises :class:`InvalidArgument` if part of the range specified is
2524         outside the image.
2525
2526         oncomplete will be called with the returned read value as
2527         well as the completion:
2528
2529         oncomplete(completion, data_read)
2530
2531         :param offset: the offset to start reading at
2532         :type offset: int
2533         :param length: how many bytes to read
2534         :type length: int
2535         :param oncomplete: what to do when the read is complete
2536         :type oncomplete: completion
2537         :param fadvise_flags: fadvise flags for this read
2538         :type fadvise_flags: int
2539         :returns: :class:`Completion` - the completion object
2540         :raises: :class:`InvalidArgument`, :class:`IOError`
2541         """
2542
2543         cdef:
2544             char *ret_buf
2545             uint64_t _offset = offset
2546             size_t _length = length
2547             int _fadvise_flags = fadvise_flags
2548             Completion completion
2549
2550         def oncomplete_(completion_v):
2551             cdef Completion _completion_v = completion_v
2552             return_value = _completion_v.get_return_value()
2553             if return_value > 0 and return_value != length:
2554                 _PyBytes_Resize(&_completion_v.buf, return_value)
2555             return oncomplete(_completion_v, <object>_completion_v.buf if return_value >= 0 else None)
2556
2557         completion = self.__get_completion(oncomplete_)
2558         completion.buf = PyBytes_FromStringAndSize(NULL, length)
2559         ret_buf = PyBytes_AsString(completion.buf)
2560         try:
2561             completion.__persist()
2562             with nogil:
2563                 ret = rbd_aio_read2(self.image, _offset, _length, ret_buf,
2564                                     completion.rbd_comp, _fadvise_flags)
2565             if ret < 0:
2566                 raise make_ex(ret, 'error reading %s %ld~%ld' %
2567                               (self.name, offset, length))
2568         except:
2569             completion.__unpersist()
2570             raise
2571
2572         return completion
2573
2574     def aio_write(self, data, offset, oncomplete, fadvise_flags=0):
2575         """
2576         Asynchronously write data to the image
2577
2578         Raises :class:`InvalidArgument` if part of the write would fall outside
2579         the image.
2580
2581         oncomplete will be called with the completion:
2582
2583         oncomplete(completion)
2584
2585         :param data: the data to be written
2586         :type data: bytes
2587         :param offset: the offset to start writing at
2588         :type offset: int
2589         :param oncomplete: what to do when the write is complete
2590         :type oncomplete: completion
2591         :param fadvise_flags: fadvise flags for this write
2592         :type fadvise_flags: int
2593         :returns: :class:`Completion` - the completion object
2594         :raises: :class:`InvalidArgument`, :class:`IOError`
2595         """
2596
2597         cdef:
2598             uint64_t _offset = offset
2599             char *_data = data
2600             size_t _length = len(data)
2601             int _fadvise_flags = fadvise_flags
2602             Completion completion
2603
2604         completion = self.__get_completion(oncomplete)
2605         try:
2606             completion.__persist()
2607             with nogil:
2608                 ret = rbd_aio_write2(self.image, _offset, _length, _data,
2609                                      completion.rbd_comp, _fadvise_flags)
2610             if ret < 0:
2611                 raise make_ex(ret, 'error writing %s %ld~%ld' %
2612                               (self.name, offset, _length))
2613         except:
2614             completion.__unpersist()
2615             raise
2616
2617         return completion
2618
2619     def aio_discard(self, offset, length, oncomplete):
2620         """
2621         Asynchronously trim the range from the image. It will be logically
2622         filled with zeroes.
2623         """
2624
2625         cdef:
2626             uint64_t _offset = offset
2627             size_t _length = length
2628             Completion completion
2629
2630         completion = self.__get_completion(oncomplete)
2631         try:
2632             completion.__persist()
2633             with nogil:
2634                 ret = rbd_aio_discard(self.image, _offset, _length,
2635                                      completion.rbd_comp)
2636             if ret < 0:
2637                 raise make_ex(ret, 'error discarding %s %ld~%ld' %
2638                               (self.name, offset, _length))
2639         except:
2640             completion.__unpersist()
2641             raise
2642
2643         return completion
2644
2645     def aio_flush(self, oncomplete):
2646         """
2647         Asyncronously wait until all writes are fully flushed if caching is
2648         enabled.
2649         """
2650
2651         cdef Completion completion = self.__get_completion(oncomplete)
2652         try:
2653             completion.__persist()
2654             with nogil:
2655                 ret = rbd_aio_flush(self.image, completion.rbd_comp)
2656             if ret < 0:
2657                 raise make_ex(ret, 'error flushing')
2658         except:
2659             completion.__unpersist()
2660             raise
2661
2662         return completion
2663
2664     def metadata_get(self, key):
2665         """
2666         Get image metadata for the given key.
2667
2668         :param key: metadata key
2669         :type key: str
2670         :returns: str - image id
2671         """
2672         key = cstr(key, 'key')
2673         cdef:
2674             char *_key = key
2675             size_t size = 4096
2676             char *value = NULL
2677             int ret
2678         try:
2679             while True:
2680                 value = <char *>realloc_chk(value, size)
2681                 with nogil:
2682                     ret = rbd_metadata_get(self.image, _key, value, &size)
2683                 if ret != -errno.ERANGE:
2684                     break
2685             if ret != 0:
2686                 raise make_ex(ret, 'error getting metadata %s for image %s' %
2687                               (self.key, self.name,))
2688             return decode_cstr(value)
2689         finally:
2690             free(value)
2691
2692     def metadata_set(self, key, value):
2693         """
2694         Set image metadata for the given key.
2695
2696         :param key: metadata key
2697         :type key: str
2698         :param value: metadata value
2699         :type value: str
2700         """
2701         key = cstr(key, 'key')
2702         value = cstr(value, 'value')
2703         cdef:
2704             char *_key = key
2705             char *_value = value
2706         with nogil:
2707             ret = rbd_metadata_set(self.image, _key, _value)
2708
2709         if ret != 0:
2710             raise make_ex(ret, 'error setting metadata %s for image %s' %
2711                           (self.key, self.name,))
2712
2713
2714     def metadata_remove(self, key):
2715         """
2716         Remove image metadata for the given key.
2717
2718         :param key: metadata key
2719         :type key: str
2720         """
2721         key = cstr(key, 'key')
2722         cdef:
2723             char *_key = key
2724         with nogil:
2725             ret = rbd_metadata_remove(self.image, _key)
2726
2727         if ret != 0:
2728             raise make_ex(ret, 'error removing metadata %s for image %s' %
2729                           (self.key, self.name,))
2730
2731     def metadata_list(self):
2732         """
2733         List image metadata.
2734
2735         :returns: :class:`MetadataIterator`
2736         """
2737         return MetadataIterator(self)
2738
2739 cdef class LockOwnerIterator(object):
2740     """
2741     Iterator over managed lock owners for an image
2742
2743     Yields a dictionary containing information about the image's lock
2744
2745     Keys are:
2746
2747     * ``mode`` (int) - active lock mode
2748
2749     * ``owner`` (str) - lock owner name
2750     """
2751
2752     cdef:
2753         rbd_lock_mode_t lock_mode
2754         char **lock_owners
2755         size_t num_lock_owners
2756         object image
2757
2758     def __init__(self, Image image):
2759         self.image = image
2760         self.lock_owners = NULL
2761         self.num_lock_owners = 8
2762         while True:
2763             self.lock_owners = <char**>realloc_chk(self.lock_owners,
2764                                                    self.num_lock_owners *
2765                                                    sizeof(char*))
2766             with nogil:
2767                 ret = rbd_lock_get_owners(image.image, &self.lock_mode,
2768                                           self.lock_owners,
2769                                           &self.num_lock_owners)
2770             if ret >= 0:
2771                 break
2772             elif ret != -errno.ERANGE:
2773                 raise make_ex(ret, 'error listing lock owners for image %s' % (image.name,))
2774
2775     def __iter__(self):
2776         for i in range(self.num_lock_owners):
2777             yield {
2778                 'mode'  : int(self.lock_mode),
2779                 'owner' : decode_cstr(self.lock_owners[i]),
2780                 }
2781
2782     def __dealloc__(self):
2783         if self.lock_owners:
2784             rbd_lock_get_owners_cleanup(self.lock_owners, self.num_lock_owners)
2785             free(self.lock_owners)
2786
2787 cdef class MetadataIterator(object):
2788     """
2789     Iterator over metadata list for an image.
2790
2791     Yields ``(key, value)`` tuple.
2792
2793     * ``key`` (str) - metadata key
2794     * ``value`` (str) - metadata value
2795     """
2796
2797     cdef:
2798         object image_name
2799         rbd_image_t image
2800         char *last_read
2801         uint64_t max_read
2802         object next_chunk
2803
2804     def __init__(self, Image image):
2805         self.image_name = image.name
2806         self.image = image.image
2807         self.last_read = strdup("")
2808         self.max_read = 32
2809         self.get_next_chunk()
2810
2811     def __iter__(self):
2812         while len(self.next_chunk) > 0:
2813             for pair in self.next_chunk:
2814                 yield pair
2815             if len(self.next_chunk) < self.max_read:
2816                 break
2817             self.get_next_chunk()
2818
2819     def __dealloc__(self):
2820         if self.last_read:
2821             free(self.last_read)
2822
2823     def get_next_chunk(self):
2824         cdef:
2825             char *c_keys = NULL
2826             size_t keys_size = 4096
2827             char *c_vals = NULL
2828             size_t vals_size = 4096
2829         try:
2830             while True:
2831                 c_keys = <char *>realloc_chk(c_keys, keys_size)
2832                 c_vals = <char *>realloc_chk(c_vals, vals_size)
2833                 with nogil:
2834                     ret = rbd_metadata_list(self.image, self.last_read,
2835                                             self.max_read, c_keys, &keys_size,
2836                                             c_vals, &vals_size)
2837                 if ret >= 0:
2838                     break
2839                 elif ret != -errno.ERANGE:
2840                     raise make_ex(ret, 'error listing metadata for image %s' %
2841                                   (self.image_name,))
2842             keys = [decode_cstr(key) for key in
2843                         c_keys[:keys_size].split(b'\0') if key]
2844             vals = [decode_cstr(val) for val in
2845                         c_vals[:vals_size].split(b'\0') if val]
2846             if len(keys) > 0:
2847                 free(self.last_read)
2848                 self.last_read = strdup(keys[-1])
2849             self.next_chunk = zip(keys, vals)
2850         finally:
2851             free(c_keys)
2852             free(c_vals)
2853
2854 cdef class SnapIterator(object):
2855     """
2856     Iterator over snapshot info for an image.
2857
2858     Yields a dictionary containing information about a snapshot.
2859
2860     Keys are:
2861
2862     * ``id`` (int) - numeric identifier of the snapshot
2863
2864     * ``size`` (int) - size of the image at the time of snapshot (in bytes)
2865
2866     * ``name`` (str) - name of the snapshot
2867     """
2868
2869     cdef rbd_snap_info_t *snaps
2870     cdef int num_snaps
2871     cdef object image
2872
2873     def __init__(self, Image image):
2874         self.image = image
2875         self.snaps = NULL
2876         self.num_snaps = 10
2877         while True:
2878             self.snaps = <rbd_snap_info_t*>realloc_chk(self.snaps,
2879                                                        self.num_snaps *
2880                                                        sizeof(rbd_snap_info_t))
2881             with nogil:
2882                 ret = rbd_snap_list(image.image, self.snaps, &self.num_snaps)
2883             if ret >= 0:
2884                 self.num_snaps = ret
2885                 break
2886             elif ret != -errno.ERANGE:
2887                 raise make_ex(ret, 'error listing snapshots for image %s' % (image.name,))
2888
2889     def __iter__(self):
2890         for i in range(self.num_snaps):
2891             yield {
2892                 'id'   : self.snaps[i].id,
2893                 'size' : self.snaps[i].size,
2894                 'name' : decode_cstr(self.snaps[i].name),
2895                 }
2896
2897     def __dealloc__(self):
2898         if self.snaps:
2899             rbd_snap_list_end(self.snaps)
2900             free(self.snaps)
2901
2902 cdef class TrashIterator(object):
2903     """
2904     Iterator over trash entries.
2905
2906     Yields a dictionary containing trash info of an image.
2907
2908     Keys are:
2909
2910         * `id` (str) - image id
2911
2912         * `name` (str) - image name
2913
2914         * `source` (str) - source of deletion
2915
2916         * `deletion_time` (datetime) - time of deletion
2917
2918         * `deferment_end_time` (datetime) - time that an image is allowed to be
2919                                             removed from trash
2920     """
2921
2922     cdef:
2923         rados_ioctx_t ioctx
2924         size_t num_entries
2925         rbd_trash_image_info_t *entries
2926
2927     def __init__(self, ioctx):
2928         self.ioctx = convert_ioctx(ioctx)
2929         self.num_entries = 1024
2930         self.entries = NULL
2931         while True:
2932             self.entries = <rbd_trash_image_info_t*>realloc_chk(self.entries,
2933                                                                 self.num_entries *
2934                                                                 sizeof(rbd_trash_image_info_t))
2935             with nogil:
2936                 ret = rbd_trash_list(self.ioctx, self.entries, &self.num_entries)
2937             if ret >= 0:
2938                 self.num_entries = ret
2939                 break
2940             elif ret != -errno.ERANGE:
2941                 raise make_ex(ret, 'error listing trash entries')
2942
2943     __source_string = ['USER', 'MIRRORING']
2944
2945     def __iter__(self):
2946         for i in range(self.num_entries):
2947             yield {
2948                 'id'          : decode_cstr(self.entries[i].id),
2949                 'name'        : decode_cstr(self.entries[i].name),
2950                 'source'      : TrashIterator.__source_string[self.entries[i].source],
2951                 'deletion_time' : datetime.fromtimestamp(self.entries[i].deletion_time),
2952                 'deferment_end_time' : datetime.fromtimestamp(self.entries[i].deferment_end_time)
2953                 }
2954
2955     def __dealloc__(self):
2956         rbd_trash_list_cleanup(self.entries, self.num_entries)
2957         if self.entries:
2958             free(self.entries)
2959