1 # cython: embedsignature=True
3 This module is a thin wrapper around librbd.
5 It currently provides all the synchronous methods of librbd that do
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
14 # Copyright 2011 Josh Durgin
15 # Copyright 2015 Hector Martin <marcan@marcan.st>
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
26 from collections import Iterable
27 from datetime import datetime
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
41 cdef extern from "time.h":
42 ctypedef long int time_t
47 cdef extern from "limits.h":
48 cdef uint64_t INT64_MAX
50 cdef extern from "rbd/librbd.h" nogil:
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"
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"
67 _RBD_FLAG_OBJECT_MAP_INVALID "RBD_FLAG_OBJECT_MAP_INVALID"
68 _RBD_FLAG_FAST_DIFF_INVALID "RBD_FLAG_FAST_DIFF_INVALID"
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"
77 RBD_MAX_BLOCK_NAME_SIZE
78 RBD_MAX_IMAGE_NAME_SIZE
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
85 ctypedef struct rbd_image_info_t:
90 char block_name_prefix[RBD_MAX_BLOCK_NAME_SIZE]
92 char parent_name[RBD_MAX_IMAGE_NAME_SIZE]
94 ctypedef struct rbd_snap_info_t:
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"
104 ctypedef struct rbd_mirror_peer_t:
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"
114 ctypedef struct rbd_mirror_image_info_t:
116 rbd_mirror_image_state_t state
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"
128 ctypedef struct rbd_mirror_image_status_t:
130 rbd_mirror_image_info_t info
131 rbd_mirror_image_status_state_t state
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"
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"
144 ctypedef struct rbd_trash_image_info_t:
147 rbd_trash_image_source_t source
149 time_t deferment_end_time
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)
154 void rbd_version(int *major, int *minor, int *extra)
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,
160 int rbd_image_options_set_uint64(rbd_image_options_t opts, int optname,
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,
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)
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,
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)
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,
188 void rbd_trash_list_cleanup(rbd_trash_image_info_t *trash_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)
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,
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,
210 void rbd_mirror_image_status_list_cleanup(char **image_ids,
211 rbd_mirror_image_status_t *images,
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)
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,
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,
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,
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,
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,
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,
280 int rbd_unlock(rbd_image_t image, const char *cookie)
281 int rbd_break_lock(rbd_image_t image, const char *client,
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,
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
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 *)
302 void *arg) except? -9000
304 int rbd_flush(rbd_image_t image)
305 int rbd_invalidate_cache(rbd_image_t image)
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,
315 int rbd_mirror_image_get_status(rbd_image_t image,
316 rbd_mirror_image_status_t *mirror_image_status,
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,
326 int rbd_aio_create_completion(void *cb_arg, rbd_callback_t complete_cb,
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)
334 int rbd_metadata_get(rbd_image_t image, const char *key, char *value,
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,
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
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
357 RBD_FLAG_OBJECT_MAP_INVALID = _RBD_FLAG_OBJECT_MAP_INVALID
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
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
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
375 RBD_LOCK_MODE_EXCLUSIVE = _RBD_LOCK_MODE_EXCLUSIVE
376 RBD_LOCK_MODE_SHARED = _RBD_LOCK_MODE_SHARED
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
385 class Error(Exception):
389 class OSError(Error):
390 """ `OSError` class, derived from `Error` """
391 def __init__(self, message, errno=None):
392 super(OSError, self).__init__(message)
396 msg = super(OSError, self).__str__()
397 if self.errno is None:
399 return '[errno {0}] {1}'.format(self.errno, msg)
401 def __reduce__(self):
402 return (self.__class__, (self.message, self.errno))
404 class PermissionError(OSError):
408 class ImageNotFound(OSError):
412 class ImageExists(OSError):
416 class IOError(OSError):
420 class NoSpace(OSError):
424 class IncompleteWriteError(OSError):
428 class InvalidArgument(OSError):
432 class LogicError(Error):
436 class ReadOnlyImage(OSError):
440 class ImageBusy(OSError):
444 class ImageHasSnapshots(OSError):
448 class FunctionNotSupported(OSError):
452 class ArgumentOutOfRange(OSError):
456 class ConnectionShutdown(OSError):
460 class Timeout(OSError):
463 class DiskQuotaExceeded(OSError):
467 cdef errno_to_exception = {
468 errno.EPERM : PermissionError,
469 errno.ENOENT : ImageNotFound,
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,
484 cdef make_ex(ret, msg):
486 Translate a librbd return code into an exception.
488 :param ret: the return code
490 :param msg: the error message to use
492 :returns: a subclass of :class:`Error`
495 if ret in errno_to_exception:
496 return errno_to_exception[ret](msg, errno=ret)
498 return OSError(msg, errno=ret)
501 cdef rados_ioctx_t convert_ioctx(rados.Ioctx ioctx) except? NULL:
502 return <rados_ioctx_t>ioctx.io
504 cdef int no_op_progress_callback(uint64_t offset, uint64_t total, void* ptr) nogil:
507 def cstr(val, name, encoding="utf-8", opt=False):
509 Create a byte string from a Python string
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
516 :raises: :class:`InvalidArgument`
518 if opt and val is None:
520 if isinstance(val, bytes):
522 elif isinstance(val, unicode):
523 return val.encode(encoding)
525 raise InvalidArgument('%s must be a string' % name)
527 def decode_cstr(val, encoding="utf-8"):
529 Decode a byte string into a Python string.
531 :param bytes val: byte string
532 :rtype: unicode or None
537 return val.decode(encoding)
540 cdef char* opt_str(s) except? NULL:
545 cdef void* realloc_chk(void* ptr, size_t size) except NULL:
546 cdef void *ret = realloc(ptr, size)
548 raise MemoryError("realloc failed")
551 cdef class Completion
553 cdef void __aio_complete_cb(rbd_completion_t completion, void *args) with gil:
555 Callback to oncomplete() for asynchronous operations
557 cdef Completion cb = <Completion>args
561 cdef class Completion(object):
562 """completion object"""
567 rbd_completion_t rbd_comp
572 def __cinit__(self, image, object oncomplete):
573 self.oncomplete = oncomplete
575 self.persisted = False
577 def is_complete(self):
579 Has an asynchronous operation completed?
581 This does not imply that the callback has finished.
583 :returns: True if the operation is completed
586 ret = rbd_aio_is_complete(self.rbd_comp)
589 def wait_for_complete_and_cb(self):
591 Wait for an asynchronous operation to complete
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.
600 rbd_aio_wait_for_complete(self.rbd_comp)
603 raise self.exc_info[0], self.exc_info[1], self.exc_info[2]
605 def get_return_value(self):
607 Get the return value of an asychronous operation
609 The return value is set when the operation is complete.
611 :returns: int - return value of the operation
614 ret = rbd_aio_get_return_value(self.rbd_comp)
617 def __dealloc__(self):
621 This is automatically called when the completion object is freed.
623 ref.Py_XDECREF(self.buf)
625 if self.rbd_comp != NULL:
627 rbd_aio_release(self.rbd_comp)
630 cdef void _complete(self):
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.
642 self.exc_info = sys.exc_info()
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.
650 self.persisted = True
652 cdef __unpersist(self):
655 self.persisted = False
660 This class wraps librbd CRUD functions.
664 Get the version number of the ``librbd`` C library.
666 :returns: a tuple of ``(major, minor, extra)`` components of the
672 rbd_version(&major, &minor, &extra)
673 return (major, minor, extra)
675 def create(self, ioctx, name, size, order=None, old_format=True,
676 features=None, stripe_unit=None, stripe_count=None,
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
685 :param size: how big the image is in bytes
687 :param order: the image is split into (2**order) byte objects
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
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
701 :raises: :class:`ImageExists`
702 :raises: :class:`TypeError`
703 :raises: :class:`InvalidArgument`
704 :raises: :class:`FunctionNotSupported`
706 name = cstr(name, 'name')
708 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
710 uint64_t _size = size
712 rbd_image_options_t opts
713 if order is not None:
717 ((stripe_unit is not None) and stripe_unit != 0) or
718 ((stripe_count is not None) and stripe_count != 0) or
720 raise InvalidArgument('format 1 images do not support feature '
721 'masks, non-default striping, nor data '
724 ret = rbd_create(_ioctx, _name, _size, &_order)
726 rbd_image_options_create(&opts)
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,
734 if order is not None:
735 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
737 if stripe_unit is not None:
738 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
740 if stripe_count is not None:
741 rbd_image_options_set_uint64(opts,
742 RBD_IMAGE_OPTION_STRIPE_COUNT,
744 if data_pool is not None:
745 rbd_image_options_set_string(opts,
746 RBD_IMAGE_OPTION_DATA_POOL,
749 ret = rbd_create4(_ioctx, _name, _size, opts)
751 rbd_image_options_destroy(opts)
753 raise make_ex(ret, 'error creating image')
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,
759 Clone a parent rbd snapshot into a COW sparse child.
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
765 :param p_snapname: the parent image snapshot name
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
771 :param features: bitmask of features to enable; if set, must include layering
773 :param order: the image is split into (2**order) byte objects
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
781 :raises: :class:`TypeError`
782 :raises: :class:`InvalidArgument`
783 :raises: :class:`ImageExists`
784 :raises: :class:`FunctionNotSupported`
785 :raises: :class:`ArgumentOutOfRange`
787 p_snapname = cstr(p_snapname, 'p_snapname')
788 p_name = cstr(p_name, 'p_name')
789 c_name = cstr(c_name, 'c_name')
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
798 rbd_image_options_create(&opts)
800 if features is not None:
801 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
803 if order is not None:
804 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
806 if stripe_unit is not None:
807 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
809 if stripe_count is not None:
810 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
812 if data_pool is not None:
813 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
816 ret = rbd_clone3(_p_ioctx, _p_name, _p_snapname,
817 _c_ioctx, _c_name, opts)
819 rbd_image_options_destroy(opts)
821 raise make_ex(ret, 'error creating clone')
823 def list(self, ioctx):
827 :param ioctx: determines which RADOS pool is read
828 :type ioctx: :class:`rados.Ioctx`
829 :returns: list -- a list of image names
832 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
837 c_names = <char *>realloc_chk(c_names, size)
839 ret = rbd_list(_ioctx, c_names, &size)
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')
849 def remove(self, ioctx, name):
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.
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
863 :raises: :class:`ImageNotFound`, :class:`ImageBusy`,
864 :class:`ImageHasSnapshots`
866 name = cstr(name, 'name')
868 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
871 ret = rbd_remove(_ioctx, _name)
873 raise make_ex(ret, 'error removing image')
875 def rename(self, ioctx, src, dest):
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
883 :param dest: the new name of the image
885 :raises: :class:`ImageNotFound`, :class:`ImageExists`
887 src = cstr(src, 'src')
888 dest = cstr(dest, 'dest')
890 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
894 ret = rbd_rename(_ioctx, _src, _dest)
896 raise make_ex(ret, 'error renaming image')
898 def trash_move(self, ioctx, name, delay=0):
900 Moves 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
905 :param delay: time delay in seconds before the image can be deleted
908 :raises: :class:`ImageNotFound`
910 name = cstr(name, 'name')
912 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
914 uint64_t _delay = delay
916 ret = rbd_trash_move(_ioctx, _name, _delay)
918 raise make_ex(ret, 'error moving image to trash')
920 def trash_remove(self, ioctx, image_id, force=False):
922 Deletes 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
928 :param force: force remove even if deferment time has not expired
930 :raises: :class:`ImageNotFound`, :class:`PermissionError`
932 image_id = cstr(image_id, 'image_id')
934 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
935 char *_image_id = image_id
938 ret = rbd_trash_remove(_ioctx, _image_id, _force)
940 raise make_ex(ret, 'error deleting image from trash')
942 def trash_get(self, ioctx, image_id):
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
949 :returns: dict - contains the following keys:
951 * ``id`` (str) - image id
953 * ``name`` (str) - image name
955 * ``source`` (str) - source of deletion
957 * ``deletion_time`` (datetime) - time of deletion
959 * ``deferment_end_time`` (datetime) - time that an image is allowed
960 to be removed from trash
962 :raises: :class:`ImageNotFound`
964 image_id = cstr(image_id, 'image_id')
966 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
967 char *_image_id = image_id
968 rbd_trash_image_info_t c_info
970 ret = rbd_trash_get(_ioctx, _image_id, &c_info)
972 raise make_ex(ret, 'error restoring image from trash')
974 __source_string = ['USER', 'MIRRORING']
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)
982 rbd_trash_get_cleanup(&c_info)
985 def trash_list(self, ioctx):
987 Lists 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`
992 return TrashIterator(ioctx)
994 def trash_restore(self, ioctx, image_id, name):
996 Restores 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
1001 :param name: the new name of the restored image
1003 :raises: :class:`ImageNotFound`
1005 image_id = cstr(image_id, 'image_id')
1006 name = cstr(name, 'name')
1008 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1009 char *_image_id = image_id
1012 ret = rbd_trash_restore(_ioctx, _image_id, _name)
1014 raise make_ex(ret, 'error restoring image from trash')
1016 def mirror_mode_get(self, ioctx):
1018 Get pool mirror mode.
1020 :param ioctx: determines which RADOS pool is read
1021 :type ioctx: :class:`rados.Ioctx`
1022 :returns: int - pool mirror mode
1025 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1026 rbd_mirror_mode_t mirror_mode
1028 ret = rbd_mirror_mode_get(_ioctx, &mirror_mode)
1030 raise make_ex(ret, 'error getting mirror mode')
1033 def mirror_mode_set(self, ioctx, mirror_mode):
1035 Set pool mirror mode.
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
1043 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1044 rbd_mirror_mode_t _mirror_mode = mirror_mode
1046 ret = rbd_mirror_mode_set(_ioctx, _mirror_mode)
1048 raise make_ex(ret, 'error setting mirror mode')
1050 def mirror_peer_add(self, ioctx, cluster_name, client_name):
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
1062 cluster_name = cstr(cluster_name, 'cluster_name')
1063 client_name = cstr(client_name, 'client_name')
1065 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1067 size_t _uuid_max_length = 512
1068 char *_cluster_name = cluster_name
1069 char *_client_name = client_name
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)
1075 raise make_ex(ret, 'error adding mirror peer')
1076 return decode_cstr(_uuid)
1080 def mirror_peer_remove(self, ioctx, uuid):
1084 :param ioctx: determines which RADOS pool is used
1085 :type ioctx: :class:`rados.Ioctx`
1086 :param uuid: peer uuid
1089 uuid = cstr(uuid, 'uuid')
1091 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1094 ret = rbd_mirror_peer_remove(_ioctx, _uuid)
1096 raise make_ex(ret, 'error removing mirror peer')
1098 def mirror_peer_list(self, ioctx):
1100 Iterate over the peers of a pool.
1102 :param ioctx: determines which RADOS pool is read
1103 :type ioctx: :class:`rados.Ioctx`
1104 :returns: :class:`MirrorPeerIterator`
1106 return MirrorPeerIterator(ioctx)
1108 def mirror_peer_set_client(self, ioctx, uuid, client_name):
1110 Set mirror peer client name
1112 :param ioctx: determines which RADOS pool is written
1113 :type ioctx: :class:`rados.Ioctx`
1114 :param uuid: uuid of the mirror peer
1116 :param client_name: client name of the mirror peer to set
1117 :type client_name: str
1119 uuid = cstr(uuid, 'uuid')
1120 client_name = cstr(client_name, 'client_name')
1122 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1124 char *_client_name = client_name
1126 ret = rbd_mirror_peer_set_client(_ioctx, _uuid, _client_name)
1128 raise make_ex(ret, 'error setting mirror peer client')
1130 def mirror_peer_set_cluster(self, ioctx, uuid, cluster_name):
1132 Set mirror peer cluster name
1134 :param ioctx: determines which RADOS pool is written
1135 :type ioctx: :class:`rados.Ioctx`
1136 :param uuid: uuid of the mirror peer
1138 :param cluster_name: cluster name of the mirror peer to set
1139 :type cluster_name: str
1141 uuid = cstr(uuid, 'uuid')
1142 cluster_name = cstr(cluster_name, 'cluster_name')
1144 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1146 char *_cluster_name = cluster_name
1148 ret = rbd_mirror_peer_set_cluster(_ioctx, _uuid, _cluster_name)
1150 raise make_ex(ret, 'error setting mirror peer cluster')
1152 def mirror_image_status_list(self, ioctx):
1154 Iterate over the mirror image statuses of a pool.
1156 :param ioctx: determines which RADOS pool is read
1157 :type ioctx: :class:`rados.Ioctx`
1158 :returns: :class:`MirrorImageStatus`
1160 return MirrorImageStatusIterator(ioctx)
1162 def mirror_image_status_summary(self, ioctx):
1164 Get mirror image status summary of a pool.
1166 :param ioctx: determines which RADOS pool is read
1167 :type ioctx: :class:`rados.Ioctx`
1168 :returns: list - a list of (state, count) tuples
1171 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1172 rbd_mirror_image_status_state_t *states = NULL
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)
1180 ret = rbd_mirror_image_status_summary(_ioctx, states, counts,
1183 raise make_ex(ret, 'error getting mirror image status summary')
1184 return [(states[i], counts[i]) for i in range(maxlen)]
1189 cdef class MirrorPeerIterator(object):
1191 Iterator over mirror peer info for a pool.
1193 Yields a dictionary containing information about a peer.
1197 * ``uuid`` (str) - uuid of the peer
1199 * ``cluster_name`` (str) - cluster name of the peer
1201 * ``client_name`` (str) - client name of the peer
1205 rbd_mirror_peer_t *peers
1208 def __init__(self, ioctx):
1210 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1214 self.peers = <rbd_mirror_peer_t *>realloc_chk(
1215 self.peers, self.num_peers * sizeof(rbd_mirror_peer_t))
1217 ret = rbd_mirror_peer_list(_ioctx, self.peers, &self.num_peers)
1219 if ret == -errno.ERANGE:
1222 raise make_ex(ret, 'error listing peers')
1226 for i in range(self.num_peers):
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),
1233 def __dealloc__(self):
1235 rbd_mirror_peer_list_cleanup(self.peers, self.num_peers)
1238 cdef class MirrorImageStatusIterator(object):
1240 Iterator over mirror image status for a pool.
1242 Yields a dictionary containing mirror status of an image.
1246 * ``name`` (str) - mirror image name
1248 * `info` (dict) - mirror image info
1250 * `state` (int) - mirror state
1252 * `description` (str) - status description
1254 * `last_update` (datetime) - last status update time
1256 * ``up`` (bool) - is mirroring agent up
1264 rbd_mirror_image_status_t *images
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)
1276 self.get_next_chunk()
1279 while self.size > 0:
1280 for i in range(self.size):
1282 'name' : decode_cstr(self.images[i].name),
1284 'global_id' : decode_cstr(self.images[i].info.global_id),
1285 'state' : self.images[i].info.state,
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,
1292 if self.size < self.max_read:
1294 self.get_next_chunk()
1296 def __dealloc__(self):
1297 rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1300 free(self.last_read)
1302 free(self.image_ids)
1306 def get_next_chunk(self):
1308 rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1312 ret = rbd_mirror_image_status_list(self.ioctx, self.last_read,
1313 self.max_read, self.image_ids,
1314 self.images, &self.size)
1316 raise make_ex(ret, 'error listing mirror images status')
1318 free(self.last_read)
1319 last_read = decode_cstr(self.image_ids[self.size - 1])
1320 self.last_read = strdup(last_read)
1322 free(self.last_read)
1323 self.last_read = strdup("")
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():
1332 ret = (<object>cb)(offset, length, bool(write))
1338 cdef class Image(object):
1340 This class represents an RBD image. It is used to perform I/O on
1341 the image and interact with snapshots.
1343 **Note**: Any method of this class may raise :class:`ImageNotFound`
1344 if the image has been deleted.
1346 cdef rbd_image_t image
1350 cdef rados_ioctx_t _ioctx
1352 def __init__(self, ioctx, name, snapshot=None, read_only=False):
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.
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.
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`).
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
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
1375 name = cstr(name, 'name')
1376 snapshot = cstr(snapshot, 'snapshot', opt=True)
1379 # Keep around a reference to the ioctx, so it won't get deleted
1382 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1384 char *_snapshot = opt_str(snapshot)
1387 ret = rbd_open_read_only(_ioctx, _name, &self.image, _snapshot)
1390 ret = rbd_open(_ioctx, _name, &self.image, _snapshot)
1392 raise make_ex(ret, 'error opening image %s at snapshot %s' % (name, snapshot))
1395 def __enter__(self):
1398 def __exit__(self, type_, value, traceback):
1400 Closes the image. See :func:`close`
1405 def __get_completion(self, oncomplete):
1407 Constructs a completion to use with asynchronous operations
1409 :param oncomplete: callback for the completion
1411 :raises: :class:`Error`
1412 :returns: completion object
1415 completion_obj = Completion(self, oncomplete)
1418 rbd_completion_t completion
1419 PyObject* p_completion_obj= <PyObject*>completion_obj
1422 ret = rbd_aio_create_completion(p_completion_obj, __aio_complete_cb,
1425 raise make_ex(ret, "error getting a completion")
1427 completion_obj.rbd_comp = completion
1428 return completion_obj
1432 Release the resources used by this image object.
1434 After this is called, this object should not be used.
1439 ret = rbd_close(self.image)
1441 raise make_ex(ret, 'error while closing image %s' % (
1444 def __dealloc__(self):
1448 return "rbd.Image(ioctx, %r)" % self.name
1450 def resize(self, size):
1452 Change the size of the image.
1454 :param size: the new size of the image
1457 cdef uint64_t _size = size
1459 ret = rbd_resize(self.image, _size)
1461 raise make_ex(ret, 'error resizing image %s' % (self.name,))
1465 Get information about the image. Currently parent pool and
1466 parent name are always -1 and ''.
1468 :returns: dict - contains the following keys:
1470 * ``size`` (int) - the size of the image in bytes
1472 * ``obj_size`` (int) - the size of each object that comprises the
1475 * ``num_objs`` (int) - the number of objects in the image
1477 * ``order`` (int) - log_2(object_size)
1479 * ``block_name_prefix`` (str) - the prefix of the RADOS objects used
1482 * ``parent_pool`` (int) - deprecated
1484 * ``parent_name`` (str) - deprecated
1486 See also :meth:`format` and :meth:`features`.
1489 cdef rbd_image_info_t info
1491 ret = rbd_stat(self.image, &info, sizeof(info))
1493 raise make_ex(ret, 'error getting info for image %s' % (self.name,))
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
1506 Get the RBD v2 internal image id
1508 :returns: str - image id
1511 int ret = -errno.ERANGE
1513 char *image_id = NULL
1515 while ret == -errno.ERANGE and size <= 4096:
1516 image_id = <char *>realloc_chk(image_id, size)
1518 ret = rbd_get_id(self.image, image_id, size)
1519 if ret == -errno.ERANGE:
1523 raise make_ex(ret, 'error getting id for image %s' % (self.name,))
1524 return decode_cstr(image_id)
1528 def block_name_prefix(self):
1530 Get the RBD block name prefix
1532 :returns: str - block name prefix
1535 int ret = -errno.ERANGE
1539 while ret == -errno.ERANGE and size <= 4096:
1540 prefix = <char *>realloc_chk(prefix, size)
1542 ret = rbd_get_block_name_prefix(self.image, prefix, size)
1543 if ret == -errno.ERANGE:
1547 raise make_ex(ret, 'error getting block name prefix for image %s' % (self.name,))
1548 return decode_cstr(prefix)
1552 def parent_info(self):
1554 Get information about a cloned image's parent (if any)
1556 :returns: tuple - ``(pool name, image name, snapshot name)`` components
1558 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1561 int ret = -errno.ERANGE
1565 char *snapname = NULL
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)
1572 ret = rbd_get_parent_info2(self.image, pool, size, name,
1573 size, NULL, 0, snapname, size)
1574 if ret == -errno.ERANGE:
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))
1585 def parent_id(self):
1587 Get image id of a cloned image's parent (if any)
1589 :returns: str - the parent id
1590 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1593 int ret = -errno.ERANGE
1595 char *parent_id = NULL
1597 while ret == -errno.ERANGE and size <= 4096:
1598 parent_id = <char *>realloc_chk(parent_id, size)
1600 ret = rbd_get_parent_info2(self.image, NULL, 0, NULL, 0,
1601 parent_id, size, NULL, 0)
1602 if ret == -errno.ERANGE:
1606 raise make_ex(ret, 'error getting parent id for image %s' % (self.name,))
1607 return decode_cstr(parent_id)
1611 def old_format(self):
1613 Find out whether the image uses the old RBD format.
1615 :returns: bool - whether the image uses the old RBD format
1619 ret = rbd_get_old_format(self.image, &old)
1621 raise make_ex(ret, 'error getting old_format for image %s' % (self.name))
1626 Get the size of the image. If open to a snapshot, returns the
1627 size of that snapshot.
1629 :returns: the size of the image in bytes
1631 cdef uint64_t image_size
1633 ret = rbd_get_size(self.image, &image_size)
1635 raise make_ex(ret, 'error getting size for image %s' % (self.name))
1640 Gets the features bitmask of the image.
1642 :returns: int - the features bitmask of the image
1644 cdef uint64_t features
1646 ret = rbd_get_features(self.image, &features)
1648 raise make_ex(ret, 'error getting features for image %s' % (self.name))
1651 def update_features(self, features, enabled):
1653 Updates 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.
1657 :param features: feature bitmask to enable/disable
1659 :param enabled: whether to enable/disable the feature
1661 :raises: :class:`InvalidArgument`
1664 uint64_t _features = features
1665 uint8_t _enabled = bool(enabled)
1667 ret = rbd_update_features(self.image, _features, _enabled)
1669 raise make_ex(ret, 'error updating features for image %s' %
1674 Gets 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.
1678 :returns: int - the overlap in bytes
1679 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1681 cdef uint64_t overlap
1683 ret = rbd_get_overlap(self.image, &overlap)
1685 raise make_ex(ret, 'error getting overlap for image %s' % (self.name))
1690 Gets the flags bitmask of the image.
1692 :returns: int - the flags bitmask of the image
1696 ret = rbd_get_flags(self.image, &flags)
1698 raise make_ex(ret, 'error getting flags for image %s' % (self.name))
1701 def is_exclusive_lock_owner(self):
1703 Gets the status of the image exclusive lock.
1705 :returns: bool - true if the image is exclusively locked
1709 ret = rbd_is_exclusive_lock_owner(self.image, &owner)
1711 raise make_ex(ret, 'error getting lock status for image %s' % (self.name))
1714 def copy(self, dest_ioctx, dest_name, features=None, order=None,
1715 stripe_unit=None, stripe_count=None, data_pool=None):
1717 Copy the image to another location.
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
1725 :param order: the image is split into (2**order) byte objects
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`
1739 dest_name = cstr(dest_name, 'dest_name')
1741 rados_ioctx_t _dest_ioctx = convert_ioctx(dest_ioctx)
1742 char *_dest_name = dest_name
1743 rbd_image_options_t opts
1745 rbd_image_options_create(&opts)
1747 if features is not None:
1748 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
1750 if order is not None:
1751 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
1753 if stripe_unit is not None:
1754 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
1756 if stripe_count is not None:
1757 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
1759 if data_pool is not None:
1760 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
1763 ret = rbd_copy3(self.image, _dest_ioctx, _dest_name, opts)
1765 rbd_image_options_destroy(opts)
1767 raise make_ex(ret, 'error copying image %s to %s' % (self.name, dest_name))
1769 def list_snaps(self):
1771 Iterate over the snapshots of an image.
1773 :returns: :class:`SnapIterator`
1775 return SnapIterator(self)
1777 def create_snap(self, name):
1779 Create a snapshot of the image.
1781 :param name: the name of the snapshot
1783 :raises: :class:`ImageExists`
1785 name = cstr(name, 'name')
1786 cdef char *_name = name
1788 ret = rbd_snap_create(self.image, _name)
1790 raise make_ex(ret, 'error creating snapshot %s from %s' % (name, self.name))
1792 def rename_snap(self, srcname, dstname):
1794 rename a snapshot of the image.
1796 :param srcname: the src name of the snapshot
1798 :param dstname: the dst name of the snapshot
1800 :raises: :class:`ImageExists`
1802 srcname = cstr(srcname, 'srcname')
1803 dstname = cstr(dstname, 'dstname')
1805 char *_srcname = srcname
1806 char *_dstname = dstname
1808 ret = rbd_snap_rename(self.image, _srcname, _dstname)
1810 raise make_ex(ret, 'error renaming snapshot of %s from %s to %s' % (self.name, srcname, dstname))
1812 def remove_snap(self, name):
1814 Delete a snapshot of the image.
1816 :param name: the name of the snapshot
1818 :raises: :class:`IOError`, :class:`ImageBusy`
1820 name = cstr(name, 'name')
1821 cdef char *_name = name
1823 ret = rbd_snap_remove(self.image, _name)
1825 raise make_ex(ret, 'error removing snapshot %s from %s' % (name, self.name))
1827 def remove_snap2(self, name, flags):
1829 Delete a snapshot of the image.
1831 :param name: the name of the snapshot
1832 :param flags: the flags for removal
1834 :raises: :class:`IOError`, :class:`ImageBusy`
1836 name = cstr(name, 'name')
1839 uint32_t _flags = flags
1840 librbd_progress_fn_t prog_cb = &no_op_progress_callback
1842 ret = rbd_snap_remove2(self.image, _name, _flags, prog_cb, NULL)
1844 raise make_ex(ret, 'error removing snapshot %s from %s with flags %llx' % (name, self.name, flags))
1846 def rollback_to_snap(self, name):
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.
1852 :param name: the snapshot to rollback to
1854 :raises: :class:`IOError`
1856 name = cstr(name, 'name')
1857 cdef char *_name = name
1859 ret = rbd_snap_rollback(self.image, _name)
1861 raise make_ex(ret, 'error rolling back image %s to snapshot %s' % (self.name, name))
1863 def protect_snap(self, name):
1865 Mark a snapshot as protected. This means it can't be deleted
1866 until it is unprotected.
1868 :param name: the snapshot to protect
1870 :raises: :class:`IOError`, :class:`ImageNotFound`
1872 name = cstr(name, 'name')
1873 cdef char *_name = name
1875 ret = rbd_snap_protect(self.image, _name)
1877 raise make_ex(ret, 'error protecting snapshot %s@%s' % (self.name, name))
1879 def unprotect_snap(self, name):
1881 Mark a snapshot unprotected. This allows it to be deleted if
1884 :param name: the snapshot to unprotect
1886 :raises: :class:`IOError`, :class:`ImageNotFound`
1888 name = cstr(name, 'name')
1889 cdef char *_name = name
1891 ret = rbd_snap_unprotect(self.image, _name)
1893 raise make_ex(ret, 'error unprotecting snapshot %s@%s' % (self.name, name))
1895 def is_protected_snap(self, name):
1897 Find out whether a snapshot is protected from deletion.
1899 :param name: the snapshot to check
1901 :returns: bool - whether the snapshot is protected
1902 :raises: :class:`IOError`, :class:`ImageNotFound`
1904 name = cstr(name, 'name')
1909 ret = rbd_snap_is_protected(self.image, _name, &is_protected)
1911 raise make_ex(ret, 'error checking if snapshot %s@%s is protected' % (self.name, name))
1912 return is_protected == 1
1914 def get_snap_limit(self):
1916 Get the snapshot limit for an image.
1922 ret = rbd_snap_get_limit(self.image, &limit)
1924 raise make_ex(ret, 'error getting snapshot limit for %s' % self.name)
1927 def set_snap_limit(self, limit):
1929 Set the snapshot limit for an image.
1931 :param limit: the new limit to set
1935 uint64_t _limit = limit
1937 ret = rbd_snap_set_limit(self.image, _limit)
1939 raise make_ex(ret, 'error setting snapshot limit for %s' % self.name)
1942 def get_snap_timestamp(self, snap_id):
1944 Get the snapshot timestamp for an image.
1945 :param snap_id: the snapshot id of a snap shot
1949 uint64_t _snap_id = snap_id
1951 ret = rbd_snap_get_timestamp(self.image, _snap_id, ×tamp)
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)
1956 def remove_snap_limit(self):
1958 Remove the snapshot limit for an image, essentially setting
1959 the limit to the maximum size allowed by the implementation.
1962 ret = rbd_snap_set_limit(self.image, UINT64_MAX)
1964 raise make_ex(ret, 'error removing snapshot limit for %s' % self.name)
1967 def set_snap(self, name):
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.
1973 :param name: the snapshot to read from, or None to unset the snapshot
1974 :type name: str or None
1976 name = cstr(name, 'name', opt=True)
1977 cdef char *_name = opt_str(name)
1979 ret = rbd_snap_set(self.image, _name)
1981 raise make_ex(ret, 'error setting image %s to snapshot %s' % (self.name, name))
1983 def read(self, offset, length, fadvise_flags=0):
1985 Read data from the image. Raises :class:`InvalidArgument` if
1986 part of the range specified is outside the image.
1988 :param offset: the offset to start reading at
1990 :param length: how many bytes to read
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`
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.
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)
2010 ret_buf = PyBytes_AsString(ret_s)
2012 ret = rbd_read2(self.image, _offset, _length, ret_buf,
2015 raise make_ex(ret, 'error reading %s %ld~%ld' % (self.name, offset, length))
2017 if ret != <ssize_t>length:
2018 _PyBytes_Resize(&ret_s, ret)
2020 return <object>ret_s
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)
2028 def diff_iterate(self, offset, length, from_snapshot, iterate_cb,
2029 include_parent = True, whole_object = False):
2031 Iterate over the changed extents of an image.
2033 This will call iterate_cb with three arguments:
2035 (offset, length, exists)
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).
2041 If from_snapshot is None, it is interpreted as the beginning
2042 of time and this generates all allocated extents.
2044 The end version is whatever is currently selected (via set_snap)
2047 iterate_cb may raise an exception, which will abort the diff and will be
2048 propagated to the caller.
2050 Raises :class:`InvalidArgument` if from_snapshot is after
2051 the currently set snapshot.
2053 Raises :class:`ImageNotFound` if from_snapshot is not the name
2054 of a snapshot of the image.
2056 :param offset: start offset in bytes
2058 :param length: size of region to report on, in bytes
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,
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`
2072 from_snapshot = cstr(from_snapshot, 'from_snapshot', opt=True)
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
2079 ret = rbd_diff_iterate2(self.image, _from_snapshot, _offset,
2080 _length, _include_parent, _whole_object,
2081 &diff_iterate_cb, <void *>iterate_cb)
2083 msg = 'error generating diff from snapshot %s' % from_snapshot
2084 raise make_ex(ret, msg)
2086 def write(self, data, offset, fadvise_flags=0):
2088 Write data to the image. Raises :class:`InvalidArgument` if
2089 part of the write would fall outside the image.
2091 :param data: the data to be written
2093 :param offset: where to start writing data
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`
2101 if not isinstance(data, bytes):
2102 raise TypeError('data must be a byte string')
2104 uint64_t _offset = offset, length = len(data)
2106 int _fadvise_flags = fadvise_flags
2108 ret = rbd_write2(self.image, _offset, length, _data, _fadvise_flags)
2110 if ret == <ssize_t>length:
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))
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))
2121 def discard(self, offset, length):
2123 Trim the range from the image. It will be logically filled
2126 cdef uint64_t _offset = offset, _length = length
2128 ret = rbd_discard(self.image, _offset, _length)
2130 msg = 'error discarding region %d~%d' % (offset, length)
2131 raise make_ex(ret, msg)
2135 Block until all writes are fully flushed if caching is enabled.
2138 ret = rbd_flush(self.image)
2140 raise make_ex(ret, 'error flushing image')
2142 def invalidate_cache(self):
2144 Drop any cached data for the image.
2147 ret = rbd_invalidate_cache(self.image)
2149 raise make_ex(ret, 'error invalidating cache')
2151 def stripe_unit(self):
2153 Returns the stripe unit used for the image.
2155 cdef uint64_t stripe_unit
2157 ret = rbd_get_stripe_unit(self.image, &stripe_unit)
2159 raise make_ex(ret, 'error getting stripe unit for image %s' % (self.name))
2162 def stripe_count(self):
2164 Returns the stripe count used for the image.
2166 cdef uint64_t stripe_count
2168 ret = rbd_get_stripe_count(self.image, &stripe_count)
2170 raise make_ex(ret, 'error getting stripe count for image %s' % (self.name))
2173 def create_timestamp(self):
2175 Returns the create timestamp for the image.
2180 ret = rbd_get_create_timestamp(self.image, ×tamp)
2182 raise make_ex(ret, 'error getting create timestamp for image: %s' % (self.name))
2183 return datetime.fromtimestamp(timestamp.tv_sec)
2187 Flatten clone image (copy all blocks from parent to child)
2190 ret = rbd_flatten(self.image)
2192 raise make_ex(ret, "error flattening %s" % self.name)
2194 def rebuild_object_map(self):
2196 Rebuilds the object map for the image HEAD or currently set snapshot
2198 cdef librbd_progress_fn_t prog_cb = &no_op_progress_callback
2200 ret = rbd_rebuild_object_map(self.image, prog_cb, NULL)
2202 raise make_ex(ret, "error rebuilding object map %s" % self.name)
2204 def list_children(self):
2206 List children of the currently set snapshot (set via set_snap()).
2208 :returns: list - a list of (pool name, image name) tuples
2211 size_t pools_size = 512, images_size = 512
2212 char *c_pools = NULL
2213 char *c_images = NULL
2216 c_pools = <char *>realloc_chk(c_pools, pools_size)
2217 c_images = <char *>realloc_chk(c_images, images_size)
2219 ret = rbd_list_children(self.image, c_pools, &pools_size,
2220 c_images, &images_size)
2223 elif ret != -errno.ERANGE:
2224 raise make_ex(ret, 'error listing images')
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))
2234 def list_lockers(self):
2236 List clients that have locked the image and information
2239 :returns: dict - contains the following keys:
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)
2249 size_t clients_size = 512, cookies_size = 512
2250 size_t addrs_size = 512, tag_size = 512
2252 char *c_clients = NULL
2253 char *c_cookies = NULL
2254 char *c_addrs = NULL
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)
2264 ret = rbd_list_lockers(self.image, &exclusive,
2266 c_clients, &clients_size,
2267 c_cookies, &cookies_size,
2268 c_addrs, &addrs_size)
2271 elif ret != -errno.ERANGE:
2272 raise make_ex(ret, 'error listing images')
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'))
2279 'tag' : decode_cstr(c_tag),
2280 'exclusive' : exclusive == 1,
2281 'lockers' : list(zip(clients, cookies, addrs)),
2289 def lock_acquire(self, lock_mode):
2291 Acquire a managed lock on the image.
2293 :param lock_mode: lock mode to set
2294 :type lock_mode: int
2295 :raises: :class:`ImageBusy` if the lock could not be acquired
2298 rbd_lock_mode_t _lock_mode = lock_mode
2300 ret = rbd_lock_acquire(self.image, _lock_mode)
2302 raise make_ex(ret, 'error acquiring lock on image')
2304 def lock_release(self):
2306 Release a managed lock on the image that was previously acquired.
2309 ret = rbd_lock_release(self.image)
2311 raise make_ex(ret, 'error releasing lock on image')
2313 def lock_get_owners(self):
2315 Iterate over the lock owners of an image.
2317 :returns: :class:`LockOwnerIterator`
2319 return LockOwnerIterator(self)
2321 def lock_break(self, lock_mode, lock_owner):
2323 Break the image lock held by a another client.
2325 :param lock_owner: the owner of the lock to break
2326 :type lock_owner: str
2328 lock_owner = cstr(lock_owner, 'lock_owner')
2330 rbd_lock_mode_t _lock_mode = lock_mode
2331 char *_lock_owner = lock_owner
2333 ret = rbd_lock_break(self.image, _lock_mode, _lock_owner)
2335 raise make_ex(ret, 'error breaking lock on image')
2337 def lock_exclusive(self, cookie):
2339 Take an exclusive lock on the image.
2341 :raises: :class:`ImageBusy` if a different client or cookie locked it
2342 :class:`ImageExists` if the same client and cookie locked it
2344 cookie = cstr(cookie, 'cookie')
2345 cdef char *_cookie = cookie
2347 ret = rbd_lock_exclusive(self.image, _cookie)
2349 raise make_ex(ret, 'error acquiring exclusive lock on image')
2351 def lock_shared(self, cookie, tag):
2353 Take a shared lock on the image. The tag must match
2354 that of the existing lockers, if any.
2356 :raises: :class:`ImageBusy` if a different client or cookie locked it
2357 :class:`ImageExists` if the same client and cookie locked it
2359 cookie = cstr(cookie, 'cookie')
2360 tag = cstr(tag, 'tag')
2362 char *_cookie = cookie
2365 ret = rbd_lock_shared(self.image, _cookie, _tag)
2367 raise make_ex(ret, 'error acquiring shared lock on image')
2369 def unlock(self, cookie):
2371 Release a lock on the image that was locked by this rados client.
2373 cookie = cstr(cookie, 'cookie')
2374 cdef char *_cookie = cookie
2376 ret = rbd_unlock(self.image, _cookie)
2378 raise make_ex(ret, 'error unlocking image')
2380 def break_lock(self, client, cookie):
2382 Release a lock held by another rados client.
2384 client = cstr(client, 'client')
2385 cookie = cstr(cookie, 'cookie')
2387 char *_client = client
2388 char *_cookie = cookie
2390 ret = rbd_break_lock(self.image, _client, _cookie)
2392 raise make_ex(ret, 'error unlocking image')
2394 def mirror_image_enable(self):
2396 Enable mirroring for the image.
2399 ret = rbd_mirror_image_enable(self.image)
2401 raise make_ex(ret, 'error enabling mirroring for image %s'
2404 def mirror_image_disable(self, force):
2406 Disable mirroring for the image.
2408 :param force: force disabling
2411 cdef bint c_force = force
2413 ret = rbd_mirror_image_disable(self.image, c_force)
2415 raise make_ex(ret, 'error disabling mirroring for image %s' %
2418 def mirror_image_promote(self, force):
2420 Promote the image to primary for mirroring.
2422 :param force: force promoting
2425 cdef bint c_force = force
2427 ret = rbd_mirror_image_promote(self.image, c_force)
2429 raise make_ex(ret, 'error promoting image %s to primary' %
2432 def mirror_image_demote(self):
2434 Demote the image to secondary for mirroring.
2437 ret = rbd_mirror_image_demote(self.image)
2439 raise make_ex(ret, 'error demoting image %s to secondary' %
2442 def mirror_image_resync(self):
2444 Flag the image to resync.
2447 ret = rbd_mirror_image_resync(self.image)
2449 raise make_ex(ret, 'error to resync image %s' % (self.name,))
2451 def mirror_image_get_info(self):
2453 Get mirror info for the image.
2455 :returns: dict - contains the following keys:
2457 * ``global_id`` (str) - image global id
2459 * ``state`` (int) - mirror state
2461 * ``primary`` (bool) - is image primary
2463 cdef rbd_mirror_image_info_t c_info
2465 ret = rbd_mirror_image_get_info(self.image, &c_info, sizeof(c_info))
2467 raise make_ex(ret, 'error getting mirror info for image %s' %
2470 'global_id' : decode_cstr(c_info.global_id),
2471 'state' : int(c_info.state),
2472 'primary' : c_info.primary,
2474 free(c_info.global_id)
2477 def mirror_image_get_status(self):
2479 Get mirror status for the image.
2481 :returns: dict - contains the following keys:
2483 * ``name`` (str) - mirror image name
2485 * `info` (dict) - mirror image info
2487 * ``state`` (int) - status mirror state
2489 * ``description`` (str) - status description
2491 * ``last_update`` (datetime) - last status update time
2493 * ``up`` (bool) - is mirroring agent up
2495 cdef rbd_mirror_image_status_t c_status
2497 ret = rbd_mirror_image_get_status(self.image, &c_status,
2500 raise make_ex(ret, 'error getting mirror status for image %s' %
2503 'name' : decode_cstr(c_status.name),
2505 'global_id' : decode_cstr(c_status.info.global_id),
2506 'state' : int(c_status.info.state),
2507 'primary' : c_status.info.primary,
2509 'state' : c_status.state,
2510 'description' : decode_cstr(c_status.description),
2511 'last_update' : datetime.fromtimestamp(c_status.last_update),
2515 free(c_status.info.global_id)
2516 free(c_status.description)
2519 def aio_read(self, offset, length, oncomplete, fadvise_flags=0):
2521 Asynchronously read data from the image
2523 Raises :class:`InvalidArgument` if part of the range specified is
2526 oncomplete will be called with the returned read value as
2527 well as the completion:
2529 oncomplete(completion, data_read)
2531 :param offset: the offset to start reading at
2533 :param length: how many bytes to read
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`
2545 uint64_t _offset = offset
2546 size_t _length = length
2547 int _fadvise_flags = fadvise_flags
2548 Completion completion
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)
2557 completion = self.__get_completion(oncomplete_)
2558 completion.buf = PyBytes_FromStringAndSize(NULL, length)
2559 ret_buf = PyBytes_AsString(completion.buf)
2561 completion.__persist()
2563 ret = rbd_aio_read2(self.image, _offset, _length, ret_buf,
2564 completion.rbd_comp, _fadvise_flags)
2566 raise make_ex(ret, 'error reading %s %ld~%ld' %
2567 (self.name, offset, length))
2569 completion.__unpersist()
2574 def aio_write(self, data, offset, oncomplete, fadvise_flags=0):
2576 Asynchronously write data to the image
2578 Raises :class:`InvalidArgument` if part of the write would fall outside
2581 oncomplete will be called with the completion:
2583 oncomplete(completion)
2585 :param data: the data to be written
2587 :param offset: the offset to start writing at
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`
2598 uint64_t _offset = offset
2600 size_t _length = len(data)
2601 int _fadvise_flags = fadvise_flags
2602 Completion completion
2604 completion = self.__get_completion(oncomplete)
2606 completion.__persist()
2608 ret = rbd_aio_write2(self.image, _offset, _length, _data,
2609 completion.rbd_comp, _fadvise_flags)
2611 raise make_ex(ret, 'error writing %s %ld~%ld' %
2612 (self.name, offset, _length))
2614 completion.__unpersist()
2619 def aio_discard(self, offset, length, oncomplete):
2621 Asynchronously trim the range from the image. It will be logically
2626 uint64_t _offset = offset
2627 size_t _length = length
2628 Completion completion
2630 completion = self.__get_completion(oncomplete)
2632 completion.__persist()
2634 ret = rbd_aio_discard(self.image, _offset, _length,
2635 completion.rbd_comp)
2637 raise make_ex(ret, 'error discarding %s %ld~%ld' %
2638 (self.name, offset, _length))
2640 completion.__unpersist()
2645 def aio_flush(self, oncomplete):
2647 Asyncronously wait until all writes are fully flushed if caching is
2651 cdef Completion completion = self.__get_completion(oncomplete)
2653 completion.__persist()
2655 ret = rbd_aio_flush(self.image, completion.rbd_comp)
2657 raise make_ex(ret, 'error flushing')
2659 completion.__unpersist()
2664 def metadata_get(self, key):
2666 Get image metadata for the given key.
2668 :param key: metadata key
2670 :returns: str - image id
2672 key = cstr(key, 'key')
2680 value = <char *>realloc_chk(value, size)
2682 ret = rbd_metadata_get(self.image, _key, value, &size)
2683 if ret != -errno.ERANGE:
2686 raise make_ex(ret, 'error getting metadata %s for image %s' %
2687 (self.key, self.name,))
2688 return decode_cstr(value)
2692 def metadata_set(self, key, value):
2694 Set image metadata for the given key.
2696 :param key: metadata key
2698 :param value: metadata value
2701 key = cstr(key, 'key')
2702 value = cstr(value, 'value')
2705 char *_value = value
2707 ret = rbd_metadata_set(self.image, _key, _value)
2710 raise make_ex(ret, 'error setting metadata %s for image %s' %
2711 (self.key, self.name,))
2714 def metadata_remove(self, key):
2716 Remove image metadata for the given key.
2718 :param key: metadata key
2721 key = cstr(key, 'key')
2725 ret = rbd_metadata_remove(self.image, _key)
2728 raise make_ex(ret, 'error removing metadata %s for image %s' %
2729 (self.key, self.name,))
2731 def metadata_list(self):
2733 List image metadata.
2735 :returns: :class:`MetadataIterator`
2737 return MetadataIterator(self)
2739 cdef class LockOwnerIterator(object):
2741 Iterator over managed lock owners for an image
2743 Yields a dictionary containing information about the image's lock
2747 * ``mode`` (int) - active lock mode
2749 * ``owner`` (str) - lock owner name
2753 rbd_lock_mode_t lock_mode
2755 size_t num_lock_owners
2758 def __init__(self, Image image):
2760 self.lock_owners = NULL
2761 self.num_lock_owners = 8
2763 self.lock_owners = <char**>realloc_chk(self.lock_owners,
2764 self.num_lock_owners *
2767 ret = rbd_lock_get_owners(image.image, &self.lock_mode,
2769 &self.num_lock_owners)
2772 elif ret != -errno.ERANGE:
2773 raise make_ex(ret, 'error listing lock owners for image %s' % (image.name,))
2776 for i in range(self.num_lock_owners):
2778 'mode' : int(self.lock_mode),
2779 'owner' : decode_cstr(self.lock_owners[i]),
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)
2787 cdef class MetadataIterator(object):
2789 Iterator over metadata list for an image.
2791 Yields ``(key, value)`` tuple.
2793 * ``key`` (str) - metadata key
2794 * ``value`` (str) - metadata value
2804 def __init__(self, Image image):
2805 self.image_name = image.name
2806 self.image = image.image
2807 self.last_read = strdup("")
2809 self.get_next_chunk()
2812 while len(self.next_chunk) > 0:
2813 for pair in self.next_chunk:
2815 if len(self.next_chunk) < self.max_read:
2817 self.get_next_chunk()
2819 def __dealloc__(self):
2821 free(self.last_read)
2823 def get_next_chunk(self):
2826 size_t keys_size = 4096
2828 size_t vals_size = 4096
2831 c_keys = <char *>realloc_chk(c_keys, keys_size)
2832 c_vals = <char *>realloc_chk(c_vals, vals_size)
2834 ret = rbd_metadata_list(self.image, self.last_read,
2835 self.max_read, c_keys, &keys_size,
2839 elif ret != -errno.ERANGE:
2840 raise make_ex(ret, 'error listing metadata for image %s' %
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]
2847 free(self.last_read)
2848 self.last_read = strdup(keys[-1])
2849 self.next_chunk = zip(keys, vals)
2854 cdef class SnapIterator(object):
2856 Iterator over snapshot info for an image.
2858 Yields a dictionary containing information about a snapshot.
2862 * ``id`` (int) - numeric identifier of the snapshot
2864 * ``size`` (int) - size of the image at the time of snapshot (in bytes)
2866 * ``name`` (str) - name of the snapshot
2869 cdef rbd_snap_info_t *snaps
2873 def __init__(self, Image image):
2878 self.snaps = <rbd_snap_info_t*>realloc_chk(self.snaps,
2880 sizeof(rbd_snap_info_t))
2882 ret = rbd_snap_list(image.image, self.snaps, &self.num_snaps)
2884 self.num_snaps = ret
2886 elif ret != -errno.ERANGE:
2887 raise make_ex(ret, 'error listing snapshots for image %s' % (image.name,))
2890 for i in range(self.num_snaps):
2892 'id' : self.snaps[i].id,
2893 'size' : self.snaps[i].size,
2894 'name' : decode_cstr(self.snaps[i].name),
2897 def __dealloc__(self):
2899 rbd_snap_list_end(self.snaps)
2902 cdef class TrashIterator(object):
2904 Iterator over trash entries.
2906 Yields a dictionary containing trash info of an image.
2910 * `id` (str) - image id
2912 * `name` (str) - image name
2914 * `source` (str) - source of deletion
2916 * `deletion_time` (datetime) - time of deletion
2918 * `deferment_end_time` (datetime) - time that an image is allowed to be
2925 rbd_trash_image_info_t *entries
2927 def __init__(self, ioctx):
2928 self.ioctx = convert_ioctx(ioctx)
2929 self.num_entries = 1024
2932 self.entries = <rbd_trash_image_info_t*>realloc_chk(self.entries,
2934 sizeof(rbd_trash_image_info_t))
2936 ret = rbd_trash_list(self.ioctx, self.entries, &self.num_entries)
2938 self.num_entries = ret
2940 elif ret != -errno.ERANGE:
2941 raise make_ex(ret, 'error listing trash entries')
2943 __source_string = ['USER', 'MIRRORING']
2946 for i in range(self.num_entries):
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)
2955 def __dealloc__(self):
2956 rbd_trash_list_cleanup(self.entries, self.num_entries)