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_overlap(rbd_image_t image, uint64_t *overlap)
232 int rbd_get_id(rbd_image_t image, char *id, size_t id_len)
233 int rbd_get_block_name_prefix(rbd_image_t image, char *prefix,
235 int rbd_get_parent_info2(rbd_image_t image,
236 char *parent_poolname, size_t ppoolnamelen,
237 char *parent_name, size_t pnamelen,
238 char *parent_id, size_t pidlen,
239 char *parent_snapname, size_t psnapnamelen)
240 int rbd_get_flags(rbd_image_t image, uint64_t *flags)
241 ssize_t rbd_read2(rbd_image_t image, uint64_t ofs, size_t len,
242 char *buf, int op_flags)
243 ssize_t rbd_write2(rbd_image_t image, uint64_t ofs, size_t len,
244 const char *buf, int op_flags)
245 int rbd_discard(rbd_image_t image, uint64_t ofs, uint64_t len)
246 int rbd_copy3(rbd_image_t src, rados_ioctx_t dest_io_ctx,
247 const char *destname, rbd_image_options_t dest_opts)
248 int rbd_snap_list(rbd_image_t image, rbd_snap_info_t *snaps,
250 void rbd_snap_list_end(rbd_snap_info_t *snaps)
251 int rbd_snap_create(rbd_image_t image, const char *snapname)
252 int rbd_snap_remove(rbd_image_t image, const char *snapname)
253 int rbd_snap_remove2(rbd_image_t image, const char *snapname, uint32_t flags,
254 librbd_progress_fn_t cb, void *cbdata)
255 int rbd_snap_rollback(rbd_image_t image, const char *snapname)
256 int rbd_snap_rename(rbd_image_t image, const char *snapname,
257 const char* dstsnapsname)
258 int rbd_snap_protect(rbd_image_t image, const char *snap_name)
259 int rbd_snap_unprotect(rbd_image_t image, const char *snap_name)
260 int rbd_snap_is_protected(rbd_image_t image, const char *snap_name,
262 int rbd_snap_get_limit(rbd_image_t image, uint64_t *limit)
263 int rbd_snap_set_limit(rbd_image_t image, uint64_t limit)
264 int rbd_snap_get_timestamp(rbd_image_t image, uint64_t snap_id, timespec *timestamp)
265 int rbd_snap_set(rbd_image_t image, const char *snapname)
266 int rbd_flatten(rbd_image_t image)
267 int rbd_rebuild_object_map(rbd_image_t image, librbd_progress_fn_t cb,
269 ssize_t rbd_list_children(rbd_image_t image, char *pools, size_t *pools_len,
270 char *images, size_t *images_len)
271 ssize_t rbd_list_lockers(rbd_image_t image, int *exclusive,
272 char *tag, size_t *tag_len,
273 char *clients, size_t *clients_len,
274 char *cookies, size_t *cookies_len,
275 char *addrs, size_t *addrs_len)
276 int rbd_lock_exclusive(rbd_image_t image, const char *cookie)
277 int rbd_lock_shared(rbd_image_t image, const char *cookie,
279 int rbd_unlock(rbd_image_t image, const char *cookie)
280 int rbd_break_lock(rbd_image_t image, const char *client,
283 int rbd_is_exclusive_lock_owner(rbd_image_t image, int *is_owner)
284 int rbd_lock_acquire(rbd_image_t image, rbd_lock_mode_t lock_mode)
285 int rbd_lock_release(rbd_image_t image)
286 int rbd_lock_get_owners(rbd_image_t image, rbd_lock_mode_t *lock_mode,
287 char **lock_owners, size_t *max_lock_owners)
288 void rbd_lock_get_owners_cleanup(char **lock_owners,
289 size_t lock_owner_count)
290 int rbd_lock_break(rbd_image_t image, rbd_lock_mode_t lock_mode,
293 # We use -9000 to propagate Python exceptions. We use except? to make sure
294 # things still work as intended if -9000 happens to be a valid errno value
296 int rbd_diff_iterate2(rbd_image_t image, const char *fromsnapname,
297 uint64_t ofs, uint64_t len,
298 uint8_t include_parent, uint8_t whole_object,
299 int (*cb)(uint64_t, size_t, int, void *)
301 void *arg) except? -9000
303 int rbd_flush(rbd_image_t image)
304 int rbd_invalidate_cache(rbd_image_t image)
306 int rbd_mirror_image_enable(rbd_image_t image)
307 int rbd_mirror_image_disable(rbd_image_t image, bint force)
308 int rbd_mirror_image_promote(rbd_image_t image, bint force)
309 int rbd_mirror_image_demote(rbd_image_t image)
310 int rbd_mirror_image_resync(rbd_image_t image)
311 int rbd_mirror_image_get_info(rbd_image_t image,
312 rbd_mirror_image_info_t *mirror_image_info,
314 int rbd_mirror_image_get_status(rbd_image_t image,
315 rbd_mirror_image_status_t *mirror_image_status,
318 int rbd_aio_write2(rbd_image_t image, uint64_t off, size_t len,
319 const char *buf, rbd_completion_t c, int op_flags)
320 int rbd_aio_read2(rbd_image_t image, uint64_t off, size_t len,
321 char *buf, rbd_completion_t c, int op_flags)
322 int rbd_aio_discard(rbd_image_t image, uint64_t off, uint64_t len,
325 int rbd_aio_create_completion(void *cb_arg, rbd_callback_t complete_cb,
327 int rbd_aio_is_complete(rbd_completion_t c)
328 int rbd_aio_wait_for_complete(rbd_completion_t c)
329 ssize_t rbd_aio_get_return_value(rbd_completion_t c)
330 void rbd_aio_release(rbd_completion_t c)
331 int rbd_aio_flush(rbd_image_t image, rbd_completion_t c)
333 int rbd_metadata_get(rbd_image_t image, const char *key, char *value,
335 int rbd_metadata_set(rbd_image_t image, const char *key, const char *value)
336 int rbd_metadata_remove(rbd_image_t image, const char *key)
337 int rbd_metadata_list(rbd_image_t image, const char *start, uint64_t max,
338 char *keys, size_t *key_len, char *values,
341 RBD_FEATURE_LAYERING = _RBD_FEATURE_LAYERING
342 RBD_FEATURE_STRIPINGV2 = _RBD_FEATURE_STRIPINGV2
343 RBD_FEATURE_EXCLUSIVE_LOCK = _RBD_FEATURE_EXCLUSIVE_LOCK
344 RBD_FEATURE_OBJECT_MAP = _RBD_FEATURE_OBJECT_MAP
345 RBD_FEATURE_FAST_DIFF = _RBD_FEATURE_FAST_DIFF
346 RBD_FEATURE_DEEP_FLATTEN = _RBD_FEATURE_DEEP_FLATTEN
347 RBD_FEATURE_JOURNALING = _RBD_FEATURE_JOURNALING
348 RBD_FEATURE_DATA_POOL = _RBD_FEATURE_DATA_POOL
350 RBD_FEATURES_INCOMPATIBLE = _RBD_FEATURES_INCOMPATIBLE
351 RBD_FEATURES_RW_INCOMPATIBLE = _RBD_FEATURES_RW_INCOMPATIBLE
352 RBD_FEATURES_MUTABLE = _RBD_FEATURES_MUTABLE
353 RBD_FEATURES_SINGLE_CLIENT = _RBD_FEATURES_SINGLE_CLIENT
354 RBD_FEATURES_ALL = _RBD_FEATURES_ALL
356 RBD_FLAG_OBJECT_MAP_INVALID = _RBD_FLAG_OBJECT_MAP_INVALID
358 RBD_MIRROR_MODE_DISABLED = _RBD_MIRROR_MODE_DISABLED
359 RBD_MIRROR_MODE_IMAGE = _RBD_MIRROR_MODE_IMAGE
360 RBD_MIRROR_MODE_POOL = _RBD_MIRROR_MODE_POOL
362 RBD_MIRROR_IMAGE_DISABLING = _RBD_MIRROR_IMAGE_DISABLING
363 RBD_MIRROR_IMAGE_ENABLED = _RBD_MIRROR_IMAGE_ENABLED
364 RBD_MIRROR_IMAGE_DISABLED = _RBD_MIRROR_IMAGE_DISABLED
366 MIRROR_IMAGE_STATUS_STATE_UNKNOWN = _MIRROR_IMAGE_STATUS_STATE_UNKNOWN
367 MIRROR_IMAGE_STATUS_STATE_ERROR = _MIRROR_IMAGE_STATUS_STATE_ERROR
368 MIRROR_IMAGE_STATUS_STATE_SYNCING = _MIRROR_IMAGE_STATUS_STATE_SYNCING
369 MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY = _MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY
370 MIRROR_IMAGE_STATUS_STATE_REPLAYING = _MIRROR_IMAGE_STATUS_STATE_REPLAYING
371 MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY = _MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY
372 MIRROR_IMAGE_STATUS_STATE_STOPPED = _MIRROR_IMAGE_STATUS_STATE_STOPPED
374 RBD_LOCK_MODE_EXCLUSIVE = _RBD_LOCK_MODE_EXCLUSIVE
375 RBD_LOCK_MODE_SHARED = _RBD_LOCK_MODE_SHARED
377 RBD_IMAGE_OPTION_FORMAT = _RBD_IMAGE_OPTION_FORMAT
378 RBD_IMAGE_OPTION_FEATURES = _RBD_IMAGE_OPTION_FEATURES
379 RBD_IMAGE_OPTION_ORDER = _RBD_IMAGE_OPTION_ORDER
380 RBD_IMAGE_OPTION_STRIPE_UNIT = _RBD_IMAGE_OPTION_STRIPE_UNIT
381 RBD_IMAGE_OPTION_STRIPE_COUNT = _RBD_IMAGE_OPTION_STRIPE_COUNT
382 RBD_IMAGE_OPTION_DATA_POOL = _RBD_IMAGE_OPTION_DATA_POOL
384 class Error(Exception):
388 class OSError(Error):
389 """ `OSError` class, derived from `Error` """
390 def __init__(self, errno, strerror):
392 self.strerror = strerror
395 return '[Errno {0}] {1}'.format(self.errno, self.strerror)
398 class PermissionError(OSError):
402 class ImageNotFound(OSError):
406 class ImageExists(OSError):
410 class IOError(OSError):
414 class NoSpace(OSError):
418 class IncompleteWriteError(OSError):
422 class InvalidArgument(OSError):
426 class LogicError(Error):
430 class ReadOnlyImage(OSError):
434 class ImageBusy(OSError):
438 class ImageHasSnapshots(OSError):
442 class FunctionNotSupported(OSError):
446 class ArgumentOutOfRange(OSError):
450 class ConnectionShutdown(OSError):
454 class Timeout(OSError):
457 class DiskQuotaExceeded(OSError):
461 cdef errno_to_exception = {
462 errno.EPERM : PermissionError,
463 errno.ENOENT : ImageNotFound,
465 errno.ENOSPC : NoSpace,
466 errno.EEXIST : ImageExists,
467 errno.EINVAL : InvalidArgument,
468 errno.EROFS : ReadOnlyImage,
469 errno.EBUSY : ImageBusy,
470 errno.ENOTEMPTY : ImageHasSnapshots,
471 errno.ENOSYS : FunctionNotSupported,
472 errno.EDOM : ArgumentOutOfRange,
473 errno.ESHUTDOWN : ConnectionShutdown,
474 errno.ETIMEDOUT : Timeout,
475 errno.EDQUOT : DiskQuotaExceeded,
478 cdef make_ex(ret, msg):
480 Translate a librbd return code into an exception.
482 :param ret: the return code
484 :param msg: the error message to use
486 :returns: a subclass of :class:`Error`
489 if ret in errno_to_exception:
490 return errno_to_exception[ret](ret, msg)
492 return Error(ret, msg + (": error code %d" % ret))
495 cdef rados_ioctx_t convert_ioctx(rados.Ioctx ioctx) except? NULL:
496 return <rados_ioctx_t>ioctx.io
498 cdef int no_op_progress_callback(uint64_t offset, uint64_t total, void* ptr) nogil:
501 def cstr(val, name, encoding="utf-8", opt=False):
503 Create a byte string from a Python string
505 :param basestring val: Python string
506 :param str name: Name of the string parameter, for exceptions
507 :param str encoding: Encoding to use
508 :param bool opt: If True, None is allowed
510 :raises: :class:`InvalidArgument`
512 if opt and val is None:
514 if isinstance(val, bytes):
516 elif isinstance(val, unicode):
517 return val.encode(encoding)
519 raise InvalidArgument('%s must be a string' % name)
521 def decode_cstr(val, encoding="utf-8"):
523 Decode a byte string into a Python string.
525 :param bytes val: byte string
526 :rtype: unicode or None
531 return val.decode(encoding)
534 cdef char* opt_str(s) except? NULL:
539 cdef void* realloc_chk(void* ptr, size_t size) except NULL:
540 cdef void *ret = realloc(ptr, size)
542 raise MemoryError("realloc failed")
545 cdef class Completion
547 cdef void __aio_complete_cb(rbd_completion_t completion, void *args) with gil:
549 Callback to oncomplete() for asynchronous operations
551 cdef Completion cb = <Completion>args
555 cdef class Completion(object):
556 """completion object"""
561 rbd_completion_t rbd_comp
566 def __cinit__(self, image, object oncomplete):
567 self.oncomplete = oncomplete
569 self.persisted = False
571 def is_complete(self):
573 Has an asynchronous operation completed?
575 This does not imply that the callback has finished.
577 :returns: True if the operation is completed
580 ret = rbd_aio_is_complete(self.rbd_comp)
583 def wait_for_complete_and_cb(self):
585 Wait for an asynchronous operation to complete
587 This method waits for the callback to execute, if one was provided.
588 It will also re-raise any exceptions raised by the callback. You
589 should call this to "reap" asynchronous completions and ensure that
590 any exceptions in the callbacks are handled, as an exception internal
591 to this module may have occurred.
594 rbd_aio_wait_for_complete(self.rbd_comp)
597 raise self.exc_info[0], self.exc_info[1], self.exc_info[2]
599 def get_return_value(self):
601 Get the return value of an asychronous operation
603 The return value is set when the operation is complete.
605 :returns: int - return value of the operation
608 ret = rbd_aio_get_return_value(self.rbd_comp)
611 def __dealloc__(self):
615 This is automatically called when the completion object is freed.
617 ref.Py_XDECREF(self.buf)
619 if self.rbd_comp != NULL:
621 rbd_aio_release(self.rbd_comp)
624 cdef void _complete(self):
628 self.oncomplete(self)
629 # In the event that something raises an exception during the next 2
630 # lines of code, we will not be able to catch it, and this may result
631 # in the app not noticing a failed callback. However, this should only
632 # happen in extreme circumstances (OOM, etc.). KeyboardInterrupt
633 # should not be a problem because the callback thread from librbd
634 # ought to have SIGINT blocked.
636 self.exc_info = sys.exc_info()
638 cdef __persist(self):
639 if self.oncomplete is not None and not self.persisted:
640 # Increment our own reference count to make sure the completion
641 # is not freed until the callback is called. The completion is
642 # allowed to be freed if there is no callback.
644 self.persisted = True
646 cdef __unpersist(self):
649 self.persisted = False
654 This class wraps librbd CRUD functions.
658 Get the version number of the ``librbd`` C library.
660 :returns: a tuple of ``(major, minor, extra)`` components of the
666 rbd_version(&major, &minor, &extra)
667 return (major, minor, extra)
669 def create(self, ioctx, name, size, order=None, old_format=True,
670 features=None, stripe_unit=None, stripe_count=None,
675 :param ioctx: the context in which to create the image
676 :type ioctx: :class:`rados.Ioctx`
677 :param name: what the image is called
679 :param size: how big the image is in bytes
681 :param order: the image is split into (2**order) byte objects
683 :param old_format: whether to create an old-style image that
684 is accessible by old clients, but can't
685 use more advanced features like layering.
686 :type old_format: bool
687 :param features: bitmask of features to enable
689 :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
690 :type stripe_unit: int
691 :param stripe_count: objects to stripe over before looping
692 :type stripe_count: int
693 :param data_pool: optional separate pool for data blocks
695 :raises: :class:`ImageExists`
696 :raises: :class:`TypeError`
697 :raises: :class:`InvalidArgument`
698 :raises: :class:`FunctionNotSupported`
700 name = cstr(name, 'name')
702 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
704 uint64_t _size = size
706 rbd_image_options_t opts
707 if order is not None:
711 ((stripe_unit is not None) and stripe_unit != 0) or
712 ((stripe_count is not None) and stripe_count != 0) or
714 raise InvalidArgument('format 1 images do not support feature '
715 'masks, non-default striping, nor data '
718 ret = rbd_create(_ioctx, _name, _size, &_order)
720 rbd_image_options_create(&opts)
722 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FORMAT,
723 1 if old_format else 2)
724 if features is not None:
725 rbd_image_options_set_uint64(opts,
726 RBD_IMAGE_OPTION_FEATURES,
728 if order is not None:
729 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
731 if stripe_unit is not None:
732 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
734 if stripe_count is not None:
735 rbd_image_options_set_uint64(opts,
736 RBD_IMAGE_OPTION_STRIPE_COUNT,
738 if data_pool is not None:
739 rbd_image_options_set_string(opts,
740 RBD_IMAGE_OPTION_DATA_POOL,
743 ret = rbd_create4(_ioctx, _name, _size, opts)
745 rbd_image_options_destroy(opts)
747 raise make_ex(ret, 'error creating image')
749 def clone(self, p_ioctx, p_name, p_snapname, c_ioctx, c_name,
750 features=None, order=None, stripe_unit=None, stripe_count=None,
753 Clone a parent rbd snapshot into a COW sparse child.
755 :param p_ioctx: the parent context that represents the parent snap
756 :type ioctx: :class:`rados.Ioctx`
757 :param p_name: the parent image name
759 :param p_snapname: the parent image snapshot name
761 :param c_ioctx: the child context that represents the new clone
762 :type ioctx: :class:`rados.Ioctx`
763 :param c_name: the clone (child) name
765 :param features: bitmask of features to enable; if set, must include layering
767 :param order: the image is split into (2**order) byte objects
769 :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
770 :type stripe_unit: int
771 :param stripe_count: objects to stripe over before looping
772 :type stripe_count: int
773 :param data_pool: optional separate pool for data blocks
775 :raises: :class:`TypeError`
776 :raises: :class:`InvalidArgument`
777 :raises: :class:`ImageExists`
778 :raises: :class:`FunctionNotSupported`
779 :raises: :class:`ArgumentOutOfRange`
781 p_snapname = cstr(p_snapname, 'p_snapname')
782 p_name = cstr(p_name, 'p_name')
783 c_name = cstr(c_name, 'c_name')
785 rados_ioctx_t _p_ioctx = convert_ioctx(p_ioctx)
786 rados_ioctx_t _c_ioctx = convert_ioctx(c_ioctx)
787 char *_p_name = p_name
788 char *_p_snapname = p_snapname
789 char *_c_name = c_name
790 rbd_image_options_t opts
792 rbd_image_options_create(&opts)
794 if features is not None:
795 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
797 if order is not None:
798 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
800 if stripe_unit is not None:
801 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
803 if stripe_count is not None:
804 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
806 if data_pool is not None:
807 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
810 ret = rbd_clone3(_p_ioctx, _p_name, _p_snapname,
811 _c_ioctx, _c_name, opts)
813 rbd_image_options_destroy(opts)
815 raise make_ex(ret, 'error creating clone')
817 def list(self, ioctx):
821 :param ioctx: determines which RADOS pool is read
822 :type ioctx: :class:`rados.Ioctx`
823 :returns: list -- a list of image names
826 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
831 c_names = <char *>realloc_chk(c_names, size)
833 ret = rbd_list(_ioctx, c_names, &size)
836 elif ret != -errno.ERANGE:
837 raise make_ex(ret, 'error listing images')
838 return [decode_cstr(name) for name in c_names[:ret].split(b'\0')
843 def remove(self, ioctx, name):
845 Delete an RBD image. This may take a long time, since it does
846 not return until every object that comprises the image has
847 been deleted. Note that all snapshots must be deleted before
848 the image can be removed. If there are snapshots left,
849 :class:`ImageHasSnapshots` is raised. If the image is still
850 open, or the watch from a crashed client has not expired,
851 :class:`ImageBusy` is raised.
853 :param ioctx: determines which RADOS pool the image is in
854 :type ioctx: :class:`rados.Ioctx`
855 :param name: the name of the image to remove
857 :raises: :class:`ImageNotFound`, :class:`ImageBusy`,
858 :class:`ImageHasSnapshots`
860 name = cstr(name, 'name')
862 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
865 ret = rbd_remove(_ioctx, _name)
867 raise make_ex(ret, 'error removing image')
869 def rename(self, ioctx, src, dest):
873 :param ioctx: determines which RADOS pool the image is in
874 :type ioctx: :class:`rados.Ioctx`
875 :param src: the current name of the image
877 :param dest: the new name of the image
879 :raises: :class:`ImageNotFound`, :class:`ImageExists`
881 src = cstr(src, 'src')
882 dest = cstr(dest, 'dest')
884 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
888 ret = rbd_rename(_ioctx, _src, _dest)
890 raise make_ex(ret, 'error renaming image')
892 def trash_move(self, ioctx, name, delay=0):
894 Moves an RBD image to the trash.
895 :param ioctx: determines which RADOS pool the image is in
896 :type ioctx: :class:`rados.Ioctx`
897 :param name: the name of the image to remove
899 :param delay: time delay in seconds before the image can be deleted
902 :raises: :class:`ImageNotFound`
904 name = cstr(name, 'name')
906 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
908 uint64_t _delay = delay
910 ret = rbd_trash_move(_ioctx, _name, _delay)
912 raise make_ex(ret, 'error moving image to trash')
914 def trash_remove(self, ioctx, image_id, force=False):
916 Deletes an RBD image from trash. If image deferment time has not
917 expired :class:`PermissionError` is raised.
918 :param ioctx: determines which RADOS pool the image is in
919 :type ioctx: :class:`rados.Ioctx`
920 :param image_id: the id of the image to remove
922 :param force: force remove even if deferment time has not expired
924 :raises: :class:`ImageNotFound`, :class:`PermissionError`
926 image_id = cstr(image_id, 'image_id')
928 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
929 char *_image_id = image_id
932 ret = rbd_trash_remove(_ioctx, _image_id, _force)
934 raise make_ex(ret, 'error deleting image from trash')
936 def trash_get(self, ioctx, image_id):
938 Retrieve RBD image info from trash
939 :param ioctx: determines which RADOS pool the image is in
940 :type ioctx: :class:`rados.Ioctx`
941 :param image_id: the id of the image to restore
943 :returns: dict - contains the following keys:
945 * ``id`` (str) - image id
947 * ``name`` (str) - image name
949 * ``source`` (str) - source of deletion
951 * ``deletion_time`` (datetime) - time of deletion
953 * ``deferment_end_time`` (datetime) - time that an image is allowed
954 to be removed from trash
956 :raises: :class:`ImageNotFound`
958 image_id = cstr(image_id, 'image_id')
960 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
961 char *_image_id = image_id
962 rbd_trash_image_info_t c_info
964 ret = rbd_trash_get(_ioctx, _image_id, &c_info)
966 raise make_ex(ret, 'error restoring image from trash')
968 __source_string = ['USER', 'MIRRORING']
970 'id' : decode_cstr(c_info.id),
971 'name' : decode_cstr(c_info.name),
972 'source' : __source_string[c_info.source],
973 'deletion_time' : datetime.fromtimestamp(c_info.deletion_time),
974 'deferment_end_time' : datetime.fromtimestamp(c_info.deferment_end_time)
976 rbd_trash_get_cleanup(&c_info)
979 def trash_list(self, ioctx):
981 Lists all entries from trash.
982 :param ioctx: determines which RADOS pool the image is in
983 :type ioctx: :class:`rados.Ioctx`
984 :returns: :class:`TrashIterator`
986 return TrashIterator(ioctx)
988 def trash_restore(self, ioctx, image_id, name):
990 Restores an RBD image from trash.
991 :param ioctx: determines which RADOS pool the image is in
992 :type ioctx: :class:`rados.Ioctx`
993 :param image_id: the id of the image to restore
995 :param name: the new name of the restored image
997 :raises: :class:`ImageNotFound`
999 image_id = cstr(image_id, 'image_id')
1000 name = cstr(name, 'name')
1002 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1003 char *_image_id = image_id
1006 ret = rbd_trash_restore(_ioctx, _image_id, _name)
1008 raise make_ex(ret, 'error restoring image from trash')
1010 def mirror_mode_get(self, ioctx):
1012 Get pool mirror mode.
1014 :param ioctx: determines which RADOS pool is read
1015 :type ioctx: :class:`rados.Ioctx`
1016 :returns: int - pool mirror mode
1019 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1020 rbd_mirror_mode_t mirror_mode
1022 ret = rbd_mirror_mode_get(_ioctx, &mirror_mode)
1024 raise make_ex(ret, 'error getting mirror mode')
1027 def mirror_mode_set(self, ioctx, mirror_mode):
1029 Set pool mirror mode.
1031 :param ioctx: determines which RADOS pool is written
1032 :type ioctx: :class:`rados.Ioctx`
1033 :param mirror_mode: mirror mode to set
1034 :type mirror_mode: int
1037 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1038 rbd_mirror_mode_t _mirror_mode = mirror_mode
1040 ret = rbd_mirror_mode_set(_ioctx, _mirror_mode)
1042 raise make_ex(ret, 'error setting mirror mode')
1044 def mirror_peer_add(self, ioctx, cluster_name, client_name):
1048 :param ioctx: determines which RADOS pool is used
1049 :type ioctx: :class:`rados.Ioctx`
1050 :param cluster_name: mirror peer cluster name
1051 :type cluster_name: str
1052 :param client_name: mirror peer client name
1053 :type client_name: str
1054 :returns: str - peer uuid
1056 cluster_name = cstr(cluster_name, 'cluster_name')
1057 client_name = cstr(client_name, 'client_name')
1059 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1061 size_t _uuid_max_length = 512
1062 char *_cluster_name = cluster_name
1063 char *_client_name = client_name
1065 _uuid = <char *>realloc_chk(_uuid, _uuid_max_length)
1066 ret = rbd_mirror_peer_add(_ioctx, _uuid, _uuid_max_length,
1067 _cluster_name, _client_name)
1069 raise make_ex(ret, 'error adding mirror peer')
1070 return decode_cstr(_uuid)
1074 def mirror_peer_remove(self, ioctx, uuid):
1078 :param ioctx: determines which RADOS pool is used
1079 :type ioctx: :class:`rados.Ioctx`
1080 :param uuid: peer uuid
1083 uuid = cstr(uuid, 'uuid')
1085 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1088 ret = rbd_mirror_peer_remove(_ioctx, _uuid)
1090 raise make_ex(ret, 'error removing mirror peer')
1092 def mirror_peer_list(self, ioctx):
1094 Iterate over the peers of a pool.
1096 :param ioctx: determines which RADOS pool is read
1097 :type ioctx: :class:`rados.Ioctx`
1098 :returns: :class:`MirrorPeerIterator`
1100 return MirrorPeerIterator(ioctx)
1102 def mirror_peer_set_client(self, ioctx, uuid, client_name):
1104 Set mirror peer client name
1106 :param ioctx: determines which RADOS pool is written
1107 :type ioctx: :class:`rados.Ioctx`
1108 :param uuid: uuid of the mirror peer
1110 :param client_name: client name of the mirror peer to set
1111 :type client_name: str
1113 uuid = cstr(uuid, 'uuid')
1114 client_name = cstr(client_name, 'client_name')
1116 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1118 char *_client_name = client_name
1120 ret = rbd_mirror_peer_set_client(_ioctx, _uuid, _client_name)
1122 raise make_ex(ret, 'error setting mirror peer client')
1124 def mirror_peer_set_cluster(self, ioctx, uuid, cluster_name):
1126 Set mirror peer cluster name
1128 :param ioctx: determines which RADOS pool is written
1129 :type ioctx: :class:`rados.Ioctx`
1130 :param uuid: uuid of the mirror peer
1132 :param cluster_name: cluster name of the mirror peer to set
1133 :type cluster_name: str
1135 uuid = cstr(uuid, 'uuid')
1136 cluster_name = cstr(cluster_name, 'cluster_name')
1138 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1140 char *_cluster_name = cluster_name
1142 ret = rbd_mirror_peer_set_cluster(_ioctx, _uuid, _cluster_name)
1144 raise make_ex(ret, 'error setting mirror peer cluster')
1146 def mirror_image_status_list(self, ioctx):
1148 Iterate over the mirror image statuses of a pool.
1150 :param ioctx: determines which RADOS pool is read
1151 :type ioctx: :class:`rados.Ioctx`
1152 :returns: :class:`MirrorImageStatus`
1154 return MirrorImageStatusIterator(ioctx)
1156 def mirror_image_status_summary(self, ioctx):
1158 Get mirror image status summary of a pool.
1160 :param ioctx: determines which RADOS pool is read
1161 :type ioctx: :class:`rados.Ioctx`
1162 :returns: list - a list of (state, count) tuples
1165 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1166 rbd_mirror_image_status_state_t *states = NULL
1170 states = <rbd_mirror_image_status_state_t *>realloc_chk(states,
1171 sizeof(rbd_mirror_image_status_state_t) * maxlen)
1172 counts = <int *>realloc_chk(counts, sizeof(int) * maxlen)
1174 ret = rbd_mirror_image_status_summary(_ioctx, states, counts,
1177 raise make_ex(ret, 'error getting mirror image status summary')
1178 return [(states[i], counts[i]) for i in range(maxlen)]
1183 cdef class MirrorPeerIterator(object):
1185 Iterator over mirror peer info for a pool.
1187 Yields a dictionary containing information about a peer.
1191 * ``uuid`` (str) - uuid of the peer
1193 * ``cluster_name`` (str) - cluster name of the peer
1195 * ``client_name`` (str) - client name of the peer
1199 rbd_mirror_peer_t *peers
1202 def __init__(self, ioctx):
1204 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1208 self.peers = <rbd_mirror_peer_t *>realloc_chk(
1209 self.peers, self.num_peers * sizeof(rbd_mirror_peer_t))
1211 ret = rbd_mirror_peer_list(_ioctx, self.peers, &self.num_peers)
1213 if ret == -errno.ERANGE:
1216 raise make_ex(ret, 'error listing peers')
1220 for i in range(self.num_peers):
1222 'uuid' : decode_cstr(self.peers[i].uuid),
1223 'cluster_name' : decode_cstr(self.peers[i].cluster_name),
1224 'client_name' : decode_cstr(self.peers[i].client_name),
1227 def __dealloc__(self):
1229 rbd_mirror_peer_list_cleanup(self.peers, self.num_peers)
1232 cdef class MirrorImageStatusIterator(object):
1234 Iterator over mirror image status for a pool.
1236 Yields a dictionary containing mirror status of an image.
1240 * ``name`` (str) - mirror image name
1242 * `info` (dict) - mirror image info
1244 * `state` (int) - mirror state
1246 * `description` (str) - status description
1248 * `last_update` (datetime) - last status update time
1250 * ``up`` (bool) - is mirroring agent up
1258 rbd_mirror_image_status_t *images
1261 def __init__(self, ioctx):
1262 self.ioctx = convert_ioctx(ioctx)
1263 self.max_read = 1024
1264 self.last_read = strdup("")
1265 self.image_ids = <char **>realloc_chk(NULL,
1266 sizeof(char *) * self.max_read)
1267 self.images = <rbd_mirror_image_status_t *>realloc_chk(NULL,
1268 sizeof(rbd_mirror_image_status_t) * self.max_read)
1270 self.get_next_chunk()
1273 while self.size > 0:
1274 for i in range(self.size):
1276 'name' : decode_cstr(self.images[i].name),
1278 'global_id' : decode_cstr(self.images[i].info.global_id),
1279 'state' : self.images[i].info.state,
1281 'state' : self.images[i].state,
1282 'description' : decode_cstr(self.images[i].description),
1283 'last_update' : datetime.fromtimestamp(self.images[i].last_update),
1284 'up' : self.images[i].up,
1286 if self.size < self.max_read:
1288 self.get_next_chunk()
1290 def __dealloc__(self):
1291 rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1294 free(self.last_read)
1296 free(self.image_ids)
1300 def get_next_chunk(self):
1302 rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1306 ret = rbd_mirror_image_status_list(self.ioctx, self.last_read,
1307 self.max_read, self.image_ids,
1308 self.images, &self.size)
1310 raise make_ex(ret, 'error listing mirror images status')
1312 free(self.last_read)
1313 last_read = decode_cstr(self.image_ids[self.size - 1])
1314 self.last_read = strdup(last_read)
1316 free(self.last_read)
1317 self.last_read = strdup("")
1319 cdef int diff_iterate_cb(uint64_t offset, size_t length, int write, void *cb) \
1320 except? -9000 with gil:
1321 # Make sure that if we wound up with an exception from a previous callback,
1322 # we stop calling back (just in case librbd ever fails to bail out on the
1323 # first negative return, as older versions did)
1324 if exc.PyErr_Occurred():
1326 ret = (<object>cb)(offset, length, bool(write))
1332 cdef class Image(object):
1334 This class represents an RBD image. It is used to perform I/O on
1335 the image and interact with snapshots.
1337 **Note**: Any method of this class may raise :class:`ImageNotFound`
1338 if the image has been deleted.
1340 cdef rbd_image_t image
1344 cdef rados_ioctx_t _ioctx
1346 def __init__(self, ioctx, name, snapshot=None, read_only=False):
1348 Open the image at the given snapshot.
1349 If a snapshot is specified, the image will be read-only, unless
1350 :func:`Image.set_snap` is called later.
1352 If read-only mode is used, metadata for the :class:`Image`
1353 object (such as which snapshots exist) may become obsolete. See
1354 the C api for more details.
1356 To clean up from opening the image, :func:`Image.close` should
1357 be called. For ease of use, this is done automatically when
1358 an :class:`Image` is used as a context manager (see :pep:`343`).
1360 :param ioctx: determines which RADOS pool the image is in
1361 :type ioctx: :class:`rados.Ioctx`
1362 :param name: the name of the image
1364 :param snapshot: which snapshot to read from
1365 :type snaphshot: str
1366 :param read_only: whether to open the image in read-only mode
1367 :type read_only: bool
1369 name = cstr(name, 'name')
1370 snapshot = cstr(snapshot, 'snapshot', opt=True)
1373 # Keep around a reference to the ioctx, so it won't get deleted
1376 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1378 char *_snapshot = opt_str(snapshot)
1381 ret = rbd_open_read_only(_ioctx, _name, &self.image, _snapshot)
1384 ret = rbd_open(_ioctx, _name, &self.image, _snapshot)
1386 raise make_ex(ret, 'error opening image %s at snapshot %s' % (name, snapshot))
1389 def __enter__(self):
1392 def __exit__(self, type_, value, traceback):
1394 Closes the image. See :func:`close`
1399 def __get_completion(self, oncomplete):
1401 Constructs a completion to use with asynchronous operations
1403 :param oncomplete: callback for the completion
1405 :raises: :class:`Error`
1406 :returns: completion object
1409 completion_obj = Completion(self, oncomplete)
1412 rbd_completion_t completion
1413 PyObject* p_completion_obj= <PyObject*>completion_obj
1416 ret = rbd_aio_create_completion(p_completion_obj, __aio_complete_cb,
1419 raise make_ex(ret, "error getting a completion")
1421 completion_obj.rbd_comp = completion
1422 return completion_obj
1426 Release the resources used by this image object.
1428 After this is called, this object should not be used.
1433 ret = rbd_close(self.image)
1435 raise make_ex(ret, 'error while closing image %s' % (
1438 def __dealloc__(self):
1442 return "rbd.Image(ioctx, %r)" % self.name
1444 def resize(self, size):
1446 Change the size of the image.
1448 :param size: the new size of the image
1451 cdef uint64_t _size = size
1453 ret = rbd_resize(self.image, _size)
1455 raise make_ex(ret, 'error resizing image %s' % (self.name,))
1459 Get information about the image. Currently parent pool and
1460 parent name are always -1 and ''.
1462 :returns: dict - contains the following keys:
1464 * ``size`` (int) - the size of the image in bytes
1466 * ``obj_size`` (int) - the size of each object that comprises the
1469 * ``num_objs`` (int) - the number of objects in the image
1471 * ``order`` (int) - log_2(object_size)
1473 * ``block_name_prefix`` (str) - the prefix of the RADOS objects used
1476 * ``parent_pool`` (int) - deprecated
1478 * ``parent_name`` (str) - deprecated
1480 See also :meth:`format` and :meth:`features`.
1483 cdef rbd_image_info_t info
1485 ret = rbd_stat(self.image, &info, sizeof(info))
1487 raise make_ex(ret, 'error getting info for image %s' % (self.name,))
1490 'obj_size' : info.obj_size,
1491 'num_objs' : info.num_objs,
1492 'order' : info.order,
1493 'block_name_prefix' : decode_cstr(info.block_name_prefix),
1494 'parent_pool' : info.parent_pool,
1495 'parent_name' : info.parent_name
1500 Get the RBD v2 internal image id
1502 :returns: str - image id
1505 int ret = -errno.ERANGE
1507 char *image_id = NULL
1509 while ret == -errno.ERANGE and size <= 4096:
1510 image_id = <char *>realloc_chk(image_id, size)
1512 ret = rbd_get_id(self.image, image_id, size)
1513 if ret == -errno.ERANGE:
1517 raise make_ex(ret, 'error getting id for image %s' % (self.name,))
1518 return decode_cstr(image_id)
1522 def block_name_prefix(self):
1524 Get the RBD block name prefix
1526 :returns: str - block name prefix
1529 int ret = -errno.ERANGE
1533 while ret == -errno.ERANGE and size <= 4096:
1534 prefix = <char *>realloc_chk(prefix, size)
1536 ret = rbd_get_block_name_prefix(self.image, prefix, size)
1537 if ret == -errno.ERANGE:
1541 raise make_ex(ret, 'error getting block name prefix for image %s' % (self.name,))
1542 return decode_cstr(prefix)
1546 def parent_info(self):
1548 Get information about a cloned image's parent (if any)
1550 :returns: tuple - ``(pool name, image name, snapshot name)`` components
1552 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1555 int ret = -errno.ERANGE
1559 char *snapname = NULL
1561 while ret == -errno.ERANGE and size <= 4096:
1562 pool = <char *>realloc_chk(pool, size)
1563 name = <char *>realloc_chk(name, size)
1564 snapname = <char *>realloc_chk(snapname, size)
1566 ret = rbd_get_parent_info2(self.image, pool, size, name,
1567 size, NULL, 0, snapname, size)
1568 if ret == -errno.ERANGE:
1572 raise make_ex(ret, 'error getting parent info for image %s' % (self.name,))
1573 return (decode_cstr(pool), decode_cstr(name), decode_cstr(snapname))
1579 def parent_id(self):
1581 Get image id of a cloned image's parent (if any)
1583 :returns: str - the parent id
1584 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1587 int ret = -errno.ERANGE
1589 char *parent_id = NULL
1591 while ret == -errno.ERANGE and size <= 4096:
1592 parent_id = <char *>realloc_chk(parent_id, size)
1594 ret = rbd_get_parent_info2(self.image, NULL, 0, NULL, 0,
1595 parent_id, size, NULL, 0)
1596 if ret == -errno.ERANGE:
1600 raise make_ex(ret, 'error getting parent id for image %s' % (self.name,))
1601 return decode_cstr(parent_id)
1605 def old_format(self):
1607 Find out whether the image uses the old RBD format.
1609 :returns: bool - whether the image uses the old RBD format
1613 ret = rbd_get_old_format(self.image, &old)
1615 raise make_ex(ret, 'error getting old_format for image %s' % (self.name))
1620 Get the size of the image. If open to a snapshot, returns the
1621 size of that snapshot.
1623 :returns: the size of the image in bytes
1625 cdef uint64_t image_size
1627 ret = rbd_get_size(self.image, &image_size)
1629 raise make_ex(ret, 'error getting size for image %s' % (self.name))
1634 Gets the features bitmask of the image.
1636 :returns: int - the features bitmask of the image
1638 cdef uint64_t features
1640 ret = rbd_get_features(self.image, &features)
1642 raise make_ex(ret, 'error getting features for image %s' % (self.name))
1645 def update_features(self, features, enabled):
1647 Updates the features bitmask of the image by enabling/disabling
1648 a single feature. The feature must support the ability to be
1649 dynamically enabled/disabled.
1651 :param features: feature bitmask to enable/disable
1653 :param enabled: whether to enable/disable the feature
1655 :raises: :class:`InvalidArgument`
1658 uint64_t _features = features
1659 uint8_t _enabled = bool(enabled)
1661 ret = rbd_update_features(self.image, _features, _enabled)
1663 raise make_ex(ret, 'error updating features for image %s' %
1668 Gets the number of overlapping bytes between the image and its parent
1669 image. If open to a snapshot, returns the overlap between the snapshot
1670 and the parent image.
1672 :returns: int - the overlap in bytes
1673 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1675 cdef uint64_t overlap
1677 ret = rbd_get_overlap(self.image, &overlap)
1679 raise make_ex(ret, 'error getting overlap for image %s' % (self.name))
1684 Gets the flags bitmask of the image.
1686 :returns: int - the flags bitmask of the image
1690 ret = rbd_get_flags(self.image, &flags)
1692 raise make_ex(ret, 'error getting flags for image %s' % (self.name))
1695 def is_exclusive_lock_owner(self):
1697 Gets the status of the image exclusive lock.
1699 :returns: bool - true if the image is exclusively locked
1703 ret = rbd_is_exclusive_lock_owner(self.image, &owner)
1705 raise make_ex(ret, 'error getting lock status for image %s' % (self.name))
1708 def copy(self, dest_ioctx, dest_name, features=None, order=None,
1709 stripe_unit=None, stripe_count=None, data_pool=None):
1711 Copy the image to another location.
1713 :param dest_ioctx: determines which pool to copy into
1714 :type dest_ioctx: :class:`rados.Ioctx`
1715 :param dest_name: the name of the copy
1716 :type dest_name: str
1717 :param features: bitmask of features to enable; if set, must include layering
1719 :param order: the image is split into (2**order) byte objects
1721 :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
1722 :type stripe_unit: int
1723 :param stripe_count: objects to stripe over before looping
1724 :type stripe_count: int
1725 :param data_pool: optional separate pool for data blocks
1726 :type data_pool: str
1727 :raises: :class:`TypeError`
1728 :raises: :class:`InvalidArgument`
1729 :raises: :class:`ImageExists`
1730 :raises: :class:`FunctionNotSupported`
1731 :raises: :class:`ArgumentOutOfRange`
1733 dest_name = cstr(dest_name, 'dest_name')
1735 rados_ioctx_t _dest_ioctx = convert_ioctx(dest_ioctx)
1736 char *_dest_name = dest_name
1737 rbd_image_options_t opts
1739 rbd_image_options_create(&opts)
1741 if features is not None:
1742 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
1744 if order is not None:
1745 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
1747 if stripe_unit is not None:
1748 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
1750 if stripe_count is not None:
1751 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
1753 if data_pool is not None:
1754 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
1757 ret = rbd_copy3(self.image, _dest_ioctx, _dest_name, opts)
1759 rbd_image_options_destroy(opts)
1761 raise make_ex(ret, 'error copying image %s to %s' % (self.name, dest_name))
1763 def list_snaps(self):
1765 Iterate over the snapshots of an image.
1767 :returns: :class:`SnapIterator`
1769 return SnapIterator(self)
1771 def create_snap(self, name):
1773 Create a snapshot of the image.
1775 :param name: the name of the snapshot
1777 :raises: :class:`ImageExists`
1779 name = cstr(name, 'name')
1780 cdef char *_name = name
1782 ret = rbd_snap_create(self.image, _name)
1784 raise make_ex(ret, 'error creating snapshot %s from %s' % (name, self.name))
1786 def rename_snap(self, srcname, dstname):
1788 rename a snapshot of the image.
1790 :param srcname: the src name of the snapshot
1792 :param dstname: the dst name of the snapshot
1794 :raises: :class:`ImageExists`
1796 srcname = cstr(srcname, 'srcname')
1797 dstname = cstr(dstname, 'dstname')
1799 char *_srcname = srcname
1800 char *_dstname = dstname
1802 ret = rbd_snap_rename(self.image, _srcname, _dstname)
1804 raise make_ex(ret, 'error renaming snapshot of %s from %s to %s' % (self.name, srcname, dstname))
1806 def remove_snap(self, name):
1808 Delete a snapshot of the image.
1810 :param name: the name of the snapshot
1812 :raises: :class:`IOError`, :class:`ImageBusy`
1814 name = cstr(name, 'name')
1815 cdef char *_name = name
1817 ret = rbd_snap_remove(self.image, _name)
1819 raise make_ex(ret, 'error removing snapshot %s from %s' % (name, self.name))
1821 def remove_snap2(self, name, flags):
1823 Delete a snapshot of the image.
1825 :param name: the name of the snapshot
1826 :param flags: the flags for removal
1828 :raises: :class:`IOError`, :class:`ImageBusy`
1830 name = cstr(name, 'name')
1833 uint32_t _flags = flags
1834 librbd_progress_fn_t prog_cb = &no_op_progress_callback
1836 ret = rbd_snap_remove2(self.image, _name, _flags, prog_cb, NULL)
1838 raise make_ex(ret, 'error removing snapshot %s from %s with flags %llx' % (name, self.name, flags))
1840 def rollback_to_snap(self, name):
1842 Revert the image to its contents at a snapshot. This is a
1843 potentially expensive operation, since it rolls back each
1844 object individually.
1846 :param name: the snapshot to rollback to
1848 :raises: :class:`IOError`
1850 name = cstr(name, 'name')
1851 cdef char *_name = name
1853 ret = rbd_snap_rollback(self.image, _name)
1855 raise make_ex(ret, 'error rolling back image %s to snapshot %s' % (self.name, name))
1857 def protect_snap(self, name):
1859 Mark a snapshot as protected. This means it can't be deleted
1860 until it is unprotected.
1862 :param name: the snapshot to protect
1864 :raises: :class:`IOError`, :class:`ImageNotFound`
1866 name = cstr(name, 'name')
1867 cdef char *_name = name
1869 ret = rbd_snap_protect(self.image, _name)
1871 raise make_ex(ret, 'error protecting snapshot %s@%s' % (self.name, name))
1873 def unprotect_snap(self, name):
1875 Mark a snapshot unprotected. This allows it to be deleted if
1878 :param name: the snapshot to unprotect
1880 :raises: :class:`IOError`, :class:`ImageNotFound`
1882 name = cstr(name, 'name')
1883 cdef char *_name = name
1885 ret = rbd_snap_unprotect(self.image, _name)
1887 raise make_ex(ret, 'error unprotecting snapshot %s@%s' % (self.name, name))
1889 def is_protected_snap(self, name):
1891 Find out whether a snapshot is protected from deletion.
1893 :param name: the snapshot to check
1895 :returns: bool - whether the snapshot is protected
1896 :raises: :class:`IOError`, :class:`ImageNotFound`
1898 name = cstr(name, 'name')
1903 ret = rbd_snap_is_protected(self.image, _name, &is_protected)
1905 raise make_ex(ret, 'error checking if snapshot %s@%s is protected' % (self.name, name))
1906 return is_protected == 1
1908 def get_snap_limit(self):
1910 Get the snapshot limit for an image.
1916 ret = rbd_snap_get_limit(self.image, &limit)
1918 raise make_ex(ret, 'error getting snapshot limit for %s' % self.name)
1921 def set_snap_limit(self, limit):
1923 Set the snapshot limit for an image.
1925 :param limit: the new limit to set
1929 uint64_t _limit = limit
1931 ret = rbd_snap_set_limit(self.image, _limit)
1933 raise make_ex(ret, 'error setting snapshot limit for %s' % self.name)
1936 def get_snap_timestamp(self, snap_id):
1938 Get the snapshot timestamp for an image.
1939 :param snap_id: the snapshot id of a snap shot
1943 uint64_t _snap_id = snap_id
1945 ret = rbd_snap_get_timestamp(self.image, _snap_id, ×tamp)
1947 raise make_ex(ret, 'error getting snapshot timestamp for image: %s, snap_id: %d' % (self.name, snap_id))
1948 return datetime.fromtimestamp(timestamp.tv_sec)
1950 def remove_snap_limit(self):
1952 Remove the snapshot limit for an image, essentially setting
1953 the limit to the maximum size allowed by the implementation.
1956 ret = rbd_snap_set_limit(self.image, UINT64_MAX)
1958 raise make_ex(ret, 'error removing snapshot limit for %s' % self.name)
1961 def set_snap(self, name):
1963 Set the snapshot to read from. Writes will raise ReadOnlyImage
1964 while a snapshot is set. Pass None to unset the snapshot
1965 (reads come from the current image) , and allow writing again.
1967 :param name: the snapshot to read from, or None to unset the snapshot
1968 :type name: str or None
1970 name = cstr(name, 'name', opt=True)
1971 cdef char *_name = opt_str(name)
1973 ret = rbd_snap_set(self.image, _name)
1975 raise make_ex(ret, 'error setting image %s to snapshot %s' % (self.name, name))
1977 def read(self, offset, length, fadvise_flags=0):
1979 Read data from the image. Raises :class:`InvalidArgument` if
1980 part of the range specified is outside the image.
1982 :param offset: the offset to start reading at
1984 :param length: how many bytes to read
1986 :param fadvise_flags: fadvise flags for this read
1987 :type fadvise_flags: int
1988 :returns: str - the data read
1989 :raises: :class:`InvalidArgument`, :class:`IOError`
1992 # This usage of the Python API allows us to construct a string
1993 # that librbd directly reads into, avoiding an extra copy. Although
1994 # strings are normally immutable, this usage is explicitly supported
1995 # for freshly created string objects.
1998 uint64_t _offset = offset
1999 size_t _length = length
2000 int _fadvise_flags = fadvise_flags
2001 PyObject* ret_s = NULL
2002 ret_s = PyBytes_FromStringAndSize(NULL, length)
2004 ret_buf = PyBytes_AsString(ret_s)
2006 ret = rbd_read2(self.image, _offset, _length, ret_buf,
2009 raise make_ex(ret, 'error reading %s %ld~%ld' % (self.name, offset, length))
2011 if ret != <ssize_t>length:
2012 _PyBytes_Resize(&ret_s, ret)
2014 return <object>ret_s
2016 # We DECREF unconditionally: the cast to object above will have
2017 # INCREFed if necessary. This also takes care of exceptions,
2018 # including if _PyString_Resize fails (that will free the string
2019 # itself and set ret_s to NULL, hence XDECREF).
2020 ref.Py_XDECREF(ret_s)
2022 def diff_iterate(self, offset, length, from_snapshot, iterate_cb,
2023 include_parent = True, whole_object = False):
2025 Iterate over the changed extents of an image.
2027 This will call iterate_cb with three arguments:
2029 (offset, length, exists)
2031 where the changed extent starts at offset bytes, continues for
2032 length bytes, and is full of data (if exists is True) or zeroes
2033 (if exists is False).
2035 If from_snapshot is None, it is interpreted as the beginning
2036 of time and this generates all allocated extents.
2038 The end version is whatever is currently selected (via set_snap)
2041 iterate_cb may raise an exception, which will abort the diff and will be
2042 propagated to the caller.
2044 Raises :class:`InvalidArgument` if from_snapshot is after
2045 the currently set snapshot.
2047 Raises :class:`ImageNotFound` if from_snapshot is not the name
2048 of a snapshot of the image.
2050 :param offset: start offset in bytes
2052 :param length: size of region to report on, in bytes
2054 :param from_snapshot: starting snapshot name, or None
2055 :type from_snapshot: str or None
2056 :param iterate_cb: function to call for each extent
2057 :type iterate_cb: function acception arguments for offset,
2059 :param include_parent: True if full history diff should include parent
2060 :type include_parent: bool
2061 :param whole_object: True if diff extents should cover whole object
2062 :type whole_object: bool
2063 :raises: :class:`InvalidArgument`, :class:`IOError`,
2064 :class:`ImageNotFound`
2066 from_snapshot = cstr(from_snapshot, 'from_snapshot', opt=True)
2068 char *_from_snapshot = opt_str(from_snapshot)
2069 uint64_t _offset = offset, _length = length
2070 uint8_t _include_parent = include_parent
2071 uint8_t _whole_object = whole_object
2073 ret = rbd_diff_iterate2(self.image, _from_snapshot, _offset,
2074 _length, _include_parent, _whole_object,
2075 &diff_iterate_cb, <void *>iterate_cb)
2077 msg = 'error generating diff from snapshot %s' % from_snapshot
2078 raise make_ex(ret, msg)
2080 def write(self, data, offset, fadvise_flags=0):
2082 Write data to the image. Raises :class:`InvalidArgument` if
2083 part of the write would fall outside the image.
2085 :param data: the data to be written
2087 :param offset: where to start writing data
2089 :param fadvise_flags: fadvise flags for this write
2090 :type fadvise_flags: int
2091 :returns: int - the number of bytes written
2092 :raises: :class:`IncompleteWriteError`, :class:`LogicError`,
2093 :class:`InvalidArgument`, :class:`IOError`
2095 if not isinstance(data, bytes):
2096 raise TypeError('data must be a byte string')
2098 uint64_t _offset = offset, length = len(data)
2100 int _fadvise_flags = fadvise_flags
2102 ret = rbd_write2(self.image, _offset, length, _data, _fadvise_flags)
2104 if ret == <ssize_t>length:
2107 raise make_ex(ret, "error writing to %s" % (self.name,))
2108 elif ret < <ssize_t>length:
2109 raise IncompleteWriteError("Wrote only %ld out of %ld bytes" % (ret, length))
2111 raise LogicError("logic error: rbd_write(%s) \
2112 returned %d, but %d was the maximum number of bytes it could have \
2113 written." % (self.name, ret, length))
2115 def discard(self, offset, length):
2117 Trim the range from the image. It will be logically filled
2120 cdef uint64_t _offset = offset, _length = length
2122 ret = rbd_discard(self.image, _offset, _length)
2124 msg = 'error discarding region %d~%d' % (offset, length)
2125 raise make_ex(ret, msg)
2129 Block until all writes are fully flushed if caching is enabled.
2132 ret = rbd_flush(self.image)
2134 raise make_ex(ret, 'error flushing image')
2136 def invalidate_cache(self):
2138 Drop any cached data for the image.
2141 ret = rbd_invalidate_cache(self.image)
2143 raise make_ex(ret, 'error invalidating cache')
2145 def stripe_unit(self):
2147 Returns the stripe unit used for the image.
2149 cdef uint64_t stripe_unit
2151 ret = rbd_get_stripe_unit(self.image, &stripe_unit)
2153 raise make_ex(ret, 'error getting stripe unit for image %s' % (self.name))
2156 def stripe_count(self):
2158 Returns the stripe count used for the image.
2160 cdef uint64_t stripe_count
2162 ret = rbd_get_stripe_count(self.image, &stripe_count)
2164 raise make_ex(ret, 'error getting stripe count for image %s' % (self.name))
2169 Flatten clone image (copy all blocks from parent to child)
2172 ret = rbd_flatten(self.image)
2174 raise make_ex(ret, "error flattening %s" % self.name)
2176 def rebuild_object_map(self):
2178 Rebuilds the object map for the image HEAD or currently set snapshot
2180 cdef librbd_progress_fn_t prog_cb = &no_op_progress_callback
2182 ret = rbd_rebuild_object_map(self.image, prog_cb, NULL)
2184 raise make_ex(ret, "error rebuilding object map %s" % self.name)
2186 def list_children(self):
2188 List children of the currently set snapshot (set via set_snap()).
2190 :returns: list - a list of (pool name, image name) tuples
2193 size_t pools_size = 512, images_size = 512
2194 char *c_pools = NULL
2195 char *c_images = NULL
2198 c_pools = <char *>realloc_chk(c_pools, pools_size)
2199 c_images = <char *>realloc_chk(c_images, images_size)
2201 ret = rbd_list_children(self.image, c_pools, &pools_size,
2202 c_images, &images_size)
2205 elif ret != -errno.ERANGE:
2206 raise make_ex(ret, 'error listing images')
2209 pools = map(decode_cstr, c_pools[:pools_size - 1].split(b'\0'))
2210 images = map(decode_cstr, c_images[:images_size - 1].split(b'\0'))
2211 return list(zip(pools, images))
2216 def list_lockers(self):
2218 List clients that have locked the image and information
2221 :returns: dict - contains the following keys:
2223 * ``tag`` - the tag associated with the lock (every
2224 additional locker must use the same tag)
2225 * ``exclusive`` - boolean indicating whether the
2226 lock is exclusive or shared
2227 * ``lockers`` - a list of (client, cookie, address)
2231 size_t clients_size = 512, cookies_size = 512
2232 size_t addrs_size = 512, tag_size = 512
2234 char *c_clients = NULL
2235 char *c_cookies = NULL
2236 char *c_addrs = NULL
2241 c_clients = <char *>realloc_chk(c_clients, clients_size)
2242 c_cookies = <char *>realloc_chk(c_cookies, cookies_size)
2243 c_addrs = <char *>realloc_chk(c_addrs, addrs_size)
2244 c_tag = <char *>realloc_chk(c_tag, tag_size)
2246 ret = rbd_list_lockers(self.image, &exclusive,
2248 c_clients, &clients_size,
2249 c_cookies, &cookies_size,
2250 c_addrs, &addrs_size)
2253 elif ret != -errno.ERANGE:
2254 raise make_ex(ret, 'error listing images')
2257 clients = map(decode_cstr, c_clients[:clients_size - 1].split(b'\0'))
2258 cookies = map(decode_cstr, c_cookies[:cookies_size - 1].split(b'\0'))
2259 addrs = map(decode_cstr, c_addrs[:addrs_size - 1].split(b'\0'))
2261 'tag' : decode_cstr(c_tag),
2262 'exclusive' : exclusive == 1,
2263 'lockers' : list(zip(clients, cookies, addrs)),
2271 def lock_acquire(self, lock_mode):
2273 Acquire a managed lock on the image.
2275 :param lock_mode: lock mode to set
2276 :type lock_mode: int
2277 :raises: :class:`ImageBusy` if the lock could not be acquired
2280 rbd_lock_mode_t _lock_mode = lock_mode
2282 ret = rbd_lock_acquire(self.image, _lock_mode)
2284 raise make_ex(ret, 'error acquiring lock on image')
2286 def lock_release(self):
2288 Release a managed lock on the image that was previously acquired.
2291 ret = rbd_lock_release(self.image)
2293 raise make_ex(ret, 'error releasing lock on image')
2295 def lock_get_owners(self):
2297 Iterate over the lock owners of an image.
2299 :returns: :class:`LockOwnerIterator`
2301 return LockOwnerIterator(self)
2303 def lock_break(self, lock_mode, lock_owner):
2305 Break the image lock held by a another client.
2307 :param lock_owner: the owner of the lock to break
2308 :type lock_owner: str
2310 lock_owner = cstr(lock_owner, 'lock_owner')
2312 rbd_lock_mode_t _lock_mode = lock_mode
2313 char *_lock_owner = lock_owner
2315 ret = rbd_lock_break(self.image, _lock_mode, _lock_owner)
2317 raise make_ex(ret, 'error breaking lock on image')
2319 def lock_exclusive(self, cookie):
2321 Take an exclusive lock on the image.
2323 :raises: :class:`ImageBusy` if a different client or cookie locked it
2324 :class:`ImageExists` if the same client and cookie locked it
2326 cookie = cstr(cookie, 'cookie')
2327 cdef char *_cookie = cookie
2329 ret = rbd_lock_exclusive(self.image, _cookie)
2331 raise make_ex(ret, 'error acquiring exclusive lock on image')
2333 def lock_shared(self, cookie, tag):
2335 Take a shared lock on the image. The tag must match
2336 that of the existing lockers, if any.
2338 :raises: :class:`ImageBusy` if a different client or cookie locked it
2339 :class:`ImageExists` if the same client and cookie locked it
2341 cookie = cstr(cookie, 'cookie')
2342 tag = cstr(tag, 'tag')
2344 char *_cookie = cookie
2347 ret = rbd_lock_shared(self.image, _cookie, _tag)
2349 raise make_ex(ret, 'error acquiring shared lock on image')
2351 def unlock(self, cookie):
2353 Release a lock on the image that was locked by this rados client.
2355 cookie = cstr(cookie, 'cookie')
2356 cdef char *_cookie = cookie
2358 ret = rbd_unlock(self.image, _cookie)
2360 raise make_ex(ret, 'error unlocking image')
2362 def break_lock(self, client, cookie):
2364 Release a lock held by another rados client.
2366 client = cstr(client, 'client')
2367 cookie = cstr(cookie, 'cookie')
2369 char *_client = client
2370 char *_cookie = cookie
2372 ret = rbd_break_lock(self.image, _client, _cookie)
2374 raise make_ex(ret, 'error unlocking image')
2376 def mirror_image_enable(self):
2378 Enable mirroring for the image.
2381 ret = rbd_mirror_image_enable(self.image)
2383 raise make_ex(ret, 'error enabling mirroring for image %s'
2386 def mirror_image_disable(self, force):
2388 Disable mirroring for the image.
2390 :param force: force disabling
2393 cdef bint c_force = force
2395 ret = rbd_mirror_image_disable(self.image, c_force)
2397 raise make_ex(ret, 'error disabling mirroring for image %s' %
2400 def mirror_image_promote(self, force):
2402 Promote the image to primary for mirroring.
2404 :param force: force promoting
2407 cdef bint c_force = force
2409 ret = rbd_mirror_image_promote(self.image, c_force)
2411 raise make_ex(ret, 'error promoting image %s to primary' %
2414 def mirror_image_demote(self):
2416 Demote the image to secondary for mirroring.
2419 ret = rbd_mirror_image_demote(self.image)
2421 raise make_ex(ret, 'error demoting image %s to secondary' %
2424 def mirror_image_resync(self):
2426 Flag the image to resync.
2429 ret = rbd_mirror_image_resync(self.image)
2431 raise make_ex(ret, 'error to resync image %s' % (self.name,))
2433 def mirror_image_get_info(self):
2435 Get mirror info for the image.
2437 :returns: dict - contains the following keys:
2439 * ``global_id`` (str) - image global id
2441 * ``state`` (int) - mirror state
2443 * ``primary`` (bool) - is image primary
2445 cdef rbd_mirror_image_info_t c_info
2447 ret = rbd_mirror_image_get_info(self.image, &c_info, sizeof(c_info))
2449 raise make_ex(ret, 'error getting mirror info for image %s' %
2452 'global_id' : decode_cstr(c_info.global_id),
2453 'state' : int(c_info.state),
2454 'primary' : c_info.primary,
2456 free(c_info.global_id)
2459 def mirror_image_get_status(self):
2461 Get mirror status for the image.
2463 :returns: dict - contains the following keys:
2465 * ``name`` (str) - mirror image name
2467 * `info` (dict) - mirror image info
2469 * ``state`` (int) - status mirror state
2471 * ``description`` (str) - status description
2473 * ``last_update`` (datetime) - last status update time
2475 * ``up`` (bool) - is mirroring agent up
2477 cdef rbd_mirror_image_status_t c_status
2479 ret = rbd_mirror_image_get_status(self.image, &c_status,
2482 raise make_ex(ret, 'error getting mirror status for image %s' %
2485 'name' : decode_cstr(c_status.name),
2487 'global_id' : decode_cstr(c_status.info.global_id),
2488 'state' : int(c_status.info.state),
2489 'primary' : c_status.info.primary,
2491 'state' : c_status.state,
2492 'description' : decode_cstr(c_status.description),
2493 'last_update' : datetime.fromtimestamp(c_status.last_update),
2497 free(c_status.info.global_id)
2498 free(c_status.description)
2501 def aio_read(self, offset, length, oncomplete, fadvise_flags=0):
2503 Asynchronously read data from the image
2505 Raises :class:`InvalidArgument` if part of the range specified is
2508 oncomplete will be called with the returned read value as
2509 well as the completion:
2511 oncomplete(completion, data_read)
2513 :param offset: the offset to start reading at
2515 :param length: how many bytes to read
2517 :param oncomplete: what to do when the read is complete
2518 :type oncomplete: completion
2519 :param fadvise_flags: fadvise flags for this read
2520 :type fadvise_flags: int
2521 :returns: :class:`Completion` - the completion object
2522 :raises: :class:`InvalidArgument`, :class:`IOError`
2527 uint64_t _offset = offset
2528 size_t _length = length
2529 int _fadvise_flags = fadvise_flags
2530 Completion completion
2532 def oncomplete_(completion_v):
2533 cdef Completion _completion_v = completion_v
2534 return_value = _completion_v.get_return_value()
2535 if return_value > 0 and return_value != length:
2536 _PyBytes_Resize(&_completion_v.buf, return_value)
2537 return oncomplete(_completion_v, <object>_completion_v.buf if return_value >= 0 else None)
2539 completion = self.__get_completion(oncomplete_)
2540 completion.buf = PyBytes_FromStringAndSize(NULL, length)
2541 ret_buf = PyBytes_AsString(completion.buf)
2543 completion.__persist()
2545 ret = rbd_aio_read2(self.image, _offset, _length, ret_buf,
2546 completion.rbd_comp, _fadvise_flags)
2548 raise make_ex(ret, 'error reading %s %ld~%ld' %
2549 (self.name, offset, length))
2551 completion.__unpersist()
2556 def aio_write(self, data, offset, oncomplete, fadvise_flags=0):
2558 Asynchronously write data to the image
2560 Raises :class:`InvalidArgument` if part of the write would fall outside
2563 oncomplete will be called with the completion:
2565 oncomplete(completion)
2567 :param data: the data to be written
2569 :param offset: the offset to start writing at
2571 :param oncomplete: what to do when the write is complete
2572 :type oncomplete: completion
2573 :param fadvise_flags: fadvise flags for this write
2574 :type fadvise_flags: int
2575 :returns: :class:`Completion` - the completion object
2576 :raises: :class:`InvalidArgument`, :class:`IOError`
2580 uint64_t _offset = offset
2582 size_t _length = len(data)
2583 int _fadvise_flags = fadvise_flags
2584 Completion completion
2586 completion = self.__get_completion(oncomplete)
2588 completion.__persist()
2590 ret = rbd_aio_write2(self.image, _offset, _length, _data,
2591 completion.rbd_comp, _fadvise_flags)
2593 raise make_ex(ret, 'error writing %s %ld~%ld' %
2594 (self.name, offset, _length))
2596 completion.__unpersist()
2601 def aio_discard(self, offset, length, oncomplete):
2603 Asynchronously trim the range from the image. It will be logically
2608 uint64_t _offset = offset
2609 size_t _length = length
2610 Completion completion
2612 completion = self.__get_completion(oncomplete)
2614 completion.__persist()
2616 ret = rbd_aio_discard(self.image, _offset, _length,
2617 completion.rbd_comp)
2619 raise make_ex(ret, 'error discarding %s %ld~%ld' %
2620 (self.name, offset, _length))
2622 completion.__unpersist()
2627 def aio_flush(self, oncomplete):
2629 Asyncronously wait until all writes are fully flushed if caching is
2633 cdef Completion completion = self.__get_completion(oncomplete)
2635 completion.__persist()
2637 ret = rbd_aio_flush(self.image, completion.rbd_comp)
2639 raise make_ex(ret, 'error flushing')
2641 completion.__unpersist()
2646 def metadata_get(self, key):
2648 Get image metadata for the given key.
2650 :param key: metadata key
2652 :returns: str - image id
2654 key = cstr(key, 'key')
2662 value = <char *>realloc_chk(value, size)
2664 ret = rbd_metadata_get(self.image, _key, value, &size)
2665 if ret != -errno.ERANGE:
2668 raise make_ex(ret, 'error getting metadata %s for image %s' %
2669 (self.key, self.name,))
2670 return decode_cstr(value)
2674 def metadata_set(self, key, value):
2676 Set image metadata for the given key.
2678 :param key: metadata key
2680 :param value: metadata value
2683 key = cstr(key, 'key')
2684 value = cstr(value, 'value')
2687 char *_value = value
2689 ret = rbd_metadata_set(self.image, _key, _value)
2692 raise make_ex(ret, 'error setting metadata %s for image %s' %
2693 (self.key, self.name,))
2696 def metadata_remove(self, key):
2698 Remove image metadata for the given key.
2700 :param key: metadata key
2703 key = cstr(key, 'key')
2707 ret = rbd_metadata_remove(self.image, _key)
2710 raise make_ex(ret, 'error removing metadata %s for image %s' %
2711 (self.key, self.name,))
2713 def metadata_list(self):
2715 List image metadata.
2717 :returns: :class:`MetadataIterator`
2719 return MetadataIterator(self)
2721 cdef class LockOwnerIterator(object):
2723 Iterator over managed lock owners for an image
2725 Yields a dictionary containing information about the image's lock
2729 * ``mode`` (int) - active lock mode
2731 * ``owner`` (str) - lock owner name
2735 rbd_lock_mode_t lock_mode
2737 size_t num_lock_owners
2740 def __init__(self, Image image):
2742 self.lock_owners = NULL
2743 self.num_lock_owners = 8
2745 self.lock_owners = <char**>realloc_chk(self.lock_owners,
2746 self.num_lock_owners *
2749 ret = rbd_lock_get_owners(image.image, &self.lock_mode,
2751 &self.num_lock_owners)
2754 elif ret != -errno.ERANGE:
2755 raise make_ex(ret, 'error listing lock owners for image %s' % (image.name,))
2758 for i in range(self.num_lock_owners):
2760 'mode' : int(self.lock_mode),
2761 'owner' : decode_cstr(self.lock_owners[i]),
2764 def __dealloc__(self):
2765 if self.lock_owners:
2766 rbd_lock_get_owners_cleanup(self.lock_owners, self.num_lock_owners)
2767 free(self.lock_owners)
2769 cdef class MetadataIterator(object):
2771 Iterator over metadata list for an image.
2773 Yields ``(key, value)`` tuple.
2775 * ``key`` (str) - metadata key
2776 * ``value`` (str) - metadata value
2786 def __init__(self, Image image):
2787 self.image_name = image.name
2788 self.image = image.image
2789 self.last_read = strdup("")
2791 self.get_next_chunk()
2794 while len(self.next_chunk) > 0:
2795 for pair in self.next_chunk:
2797 if len(self.next_chunk) < self.max_read:
2799 self.get_next_chunk()
2801 def get_next_chunk(self):
2804 size_t keys_size = 4096
2806 size_t vals_size = 4096
2809 c_keys = <char *>realloc_chk(c_keys, keys_size)
2810 c_vals = <char *>realloc_chk(c_vals, vals_size)
2812 ret = rbd_metadata_list(self.image, self.last_read,
2813 self.max_read, c_keys, &keys_size,
2817 elif ret != -errno.ERANGE:
2818 raise make_ex(ret, 'error listing metadata for image %s' %
2820 keys = [decode_cstr(key) for key in
2821 c_keys[:keys_size].split(b'\0') if key]
2822 vals = [decode_cstr(val) for val in
2823 c_vals[:vals_size].split(b'\0') if val]
2825 free(self.last_read)
2826 self.last_read = strdup(keys[-1])
2827 self.next_chunk = zip(keys, vals)
2832 cdef class SnapIterator(object):
2834 Iterator over snapshot info for an image.
2836 Yields a dictionary containing information about a snapshot.
2840 * ``id`` (int) - numeric identifier of the snapshot
2842 * ``size`` (int) - size of the image at the time of snapshot (in bytes)
2844 * ``name`` (str) - name of the snapshot
2847 cdef rbd_snap_info_t *snaps
2851 def __init__(self, Image image):
2856 self.snaps = <rbd_snap_info_t*>realloc_chk(self.snaps,
2858 sizeof(rbd_snap_info_t))
2860 ret = rbd_snap_list(image.image, self.snaps, &self.num_snaps)
2862 self.num_snaps = ret
2864 elif ret != -errno.ERANGE:
2865 raise make_ex(ret, 'error listing snapshots for image %s' % (image.name,))
2868 for i in range(self.num_snaps):
2870 'id' : self.snaps[i].id,
2871 'size' : self.snaps[i].size,
2872 'name' : decode_cstr(self.snaps[i].name),
2875 def __dealloc__(self):
2877 rbd_snap_list_end(self.snaps)
2880 cdef class TrashIterator(object):
2882 Iterator over trash entries.
2884 Yields a dictionary containing trash info of an image.
2888 * `id` (str) - image id
2890 * `name` (str) - image name
2892 * `source` (str) - source of deletion
2894 * `deletion_time` (datetime) - time of deletion
2896 * `deferment_end_time` (datetime) - time that an image is allowed to be
2903 rbd_trash_image_info_t *entries
2905 def __init__(self, ioctx):
2906 self.ioctx = convert_ioctx(ioctx)
2907 self.num_entries = 1024
2908 self.entries = <rbd_trash_image_info_t *>realloc_chk(NULL,
2909 sizeof(rbd_trash_image_info_t) * self.num_entries)
2911 ret = rbd_trash_list(self.ioctx, self.entries, &self.num_entries)
2913 raise make_ex(ret, 'error listing trash entries')
2915 __source_string = ['USER', 'MIRRORING']
2918 for i in range(self.num_entries):
2920 'id' : decode_cstr(self.entries[i].id),
2921 'name' : decode_cstr(self.entries[i].name),
2922 'source' : TrashIterator.__source_string[self.entries[i].source],
2923 'deletion_time' : datetime.fromtimestamp(self.entries[i].deletion_time),
2924 'deferment_end_time' : datetime.fromtimestamp(self.entries[i].deferment_end_time)
2927 def __dealloc__(self):
2928 rbd_trash_list_cleanup(self.entries, self.num_entries)