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, errno, strerror):
393 self.strerror = strerror
396 return '[Errno {0}] {1}'.format(self.errno, self.strerror)
398 def __reduce__(self):
399 return (self.__class__, (self.errno, self.strerror))
401 class PermissionError(OSError):
405 class ImageNotFound(OSError):
409 class ImageExists(OSError):
413 class IOError(OSError):
417 class NoSpace(OSError):
421 class IncompleteWriteError(OSError):
425 class InvalidArgument(OSError):
429 class LogicError(Error):
433 class ReadOnlyImage(OSError):
437 class ImageBusy(OSError):
441 class ImageHasSnapshots(OSError):
445 class FunctionNotSupported(OSError):
449 class ArgumentOutOfRange(OSError):
453 class ConnectionShutdown(OSError):
457 class Timeout(OSError):
460 class DiskQuotaExceeded(OSError):
464 cdef errno_to_exception = {
465 errno.EPERM : PermissionError,
466 errno.ENOENT : ImageNotFound,
468 errno.ENOSPC : NoSpace,
469 errno.EEXIST : ImageExists,
470 errno.EINVAL : InvalidArgument,
471 errno.EROFS : ReadOnlyImage,
472 errno.EBUSY : ImageBusy,
473 errno.ENOTEMPTY : ImageHasSnapshots,
474 errno.ENOSYS : FunctionNotSupported,
475 errno.EDOM : ArgumentOutOfRange,
476 errno.ESHUTDOWN : ConnectionShutdown,
477 errno.ETIMEDOUT : Timeout,
478 errno.EDQUOT : DiskQuotaExceeded,
481 cdef make_ex(ret, msg):
483 Translate a librbd return code into an exception.
485 :param ret: the return code
487 :param msg: the error message to use
489 :returns: a subclass of :class:`Error`
492 if ret in errno_to_exception:
493 return errno_to_exception[ret](ret, msg)
495 return Error(ret, msg + (": error code %d" % ret))
498 cdef rados_ioctx_t convert_ioctx(rados.Ioctx ioctx) except? NULL:
499 return <rados_ioctx_t>ioctx.io
501 cdef int no_op_progress_callback(uint64_t offset, uint64_t total, void* ptr) nogil:
504 def cstr(val, name, encoding="utf-8", opt=False):
506 Create a byte string from a Python string
508 :param basestring val: Python string
509 :param str name: Name of the string parameter, for exceptions
510 :param str encoding: Encoding to use
511 :param bool opt: If True, None is allowed
513 :raises: :class:`InvalidArgument`
515 if opt and val is None:
517 if isinstance(val, bytes):
519 elif isinstance(val, unicode):
520 return val.encode(encoding)
522 raise InvalidArgument('%s must be a string' % name)
524 def decode_cstr(val, encoding="utf-8"):
526 Decode a byte string into a Python string.
528 :param bytes val: byte string
529 :rtype: unicode or None
534 return val.decode(encoding)
537 cdef char* opt_str(s) except? NULL:
542 cdef void* realloc_chk(void* ptr, size_t size) except NULL:
543 cdef void *ret = realloc(ptr, size)
545 raise MemoryError("realloc failed")
548 cdef class Completion
550 cdef void __aio_complete_cb(rbd_completion_t completion, void *args) with gil:
552 Callback to oncomplete() for asynchronous operations
554 cdef Completion cb = <Completion>args
558 cdef class Completion(object):
559 """completion object"""
564 rbd_completion_t rbd_comp
569 def __cinit__(self, image, object oncomplete):
570 self.oncomplete = oncomplete
572 self.persisted = False
574 def is_complete(self):
576 Has an asynchronous operation completed?
578 This does not imply that the callback has finished.
580 :returns: True if the operation is completed
583 ret = rbd_aio_is_complete(self.rbd_comp)
586 def wait_for_complete_and_cb(self):
588 Wait for an asynchronous operation to complete
590 This method waits for the callback to execute, if one was provided.
591 It will also re-raise any exceptions raised by the callback. You
592 should call this to "reap" asynchronous completions and ensure that
593 any exceptions in the callbacks are handled, as an exception internal
594 to this module may have occurred.
597 rbd_aio_wait_for_complete(self.rbd_comp)
600 raise self.exc_info[0], self.exc_info[1], self.exc_info[2]
602 def get_return_value(self):
604 Get the return value of an asychronous operation
606 The return value is set when the operation is complete.
608 :returns: int - return value of the operation
611 ret = rbd_aio_get_return_value(self.rbd_comp)
614 def __dealloc__(self):
618 This is automatically called when the completion object is freed.
620 ref.Py_XDECREF(self.buf)
622 if self.rbd_comp != NULL:
624 rbd_aio_release(self.rbd_comp)
627 cdef void _complete(self):
631 self.oncomplete(self)
632 # In the event that something raises an exception during the next 2
633 # lines of code, we will not be able to catch it, and this may result
634 # in the app not noticing a failed callback. However, this should only
635 # happen in extreme circumstances (OOM, etc.). KeyboardInterrupt
636 # should not be a problem because the callback thread from librbd
637 # ought to have SIGINT blocked.
639 self.exc_info = sys.exc_info()
641 cdef __persist(self):
642 if self.oncomplete is not None and not self.persisted:
643 # Increment our own reference count to make sure the completion
644 # is not freed until the callback is called. The completion is
645 # allowed to be freed if there is no callback.
647 self.persisted = True
649 cdef __unpersist(self):
652 self.persisted = False
657 This class wraps librbd CRUD functions.
661 Get the version number of the ``librbd`` C library.
663 :returns: a tuple of ``(major, minor, extra)`` components of the
669 rbd_version(&major, &minor, &extra)
670 return (major, minor, extra)
672 def create(self, ioctx, name, size, order=None, old_format=True,
673 features=None, stripe_unit=None, stripe_count=None,
678 :param ioctx: the context in which to create the image
679 :type ioctx: :class:`rados.Ioctx`
680 :param name: what the image is called
682 :param size: how big the image is in bytes
684 :param order: the image is split into (2**order) byte objects
686 :param old_format: whether to create an old-style image that
687 is accessible by old clients, but can't
688 use more advanced features like layering.
689 :type old_format: bool
690 :param features: bitmask of features to enable
692 :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
693 :type stripe_unit: int
694 :param stripe_count: objects to stripe over before looping
695 :type stripe_count: int
696 :param data_pool: optional separate pool for data blocks
698 :raises: :class:`ImageExists`
699 :raises: :class:`TypeError`
700 :raises: :class:`InvalidArgument`
701 :raises: :class:`FunctionNotSupported`
703 name = cstr(name, 'name')
705 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
707 uint64_t _size = size
709 rbd_image_options_t opts
710 if order is not None:
714 ((stripe_unit is not None) and stripe_unit != 0) or
715 ((stripe_count is not None) and stripe_count != 0) or
717 raise InvalidArgument('format 1 images do not support feature '
718 'masks, non-default striping, nor data '
721 ret = rbd_create(_ioctx, _name, _size, &_order)
723 rbd_image_options_create(&opts)
725 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FORMAT,
726 1 if old_format else 2)
727 if features is not None:
728 rbd_image_options_set_uint64(opts,
729 RBD_IMAGE_OPTION_FEATURES,
731 if order is not None:
732 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
734 if stripe_unit is not None:
735 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
737 if stripe_count is not None:
738 rbd_image_options_set_uint64(opts,
739 RBD_IMAGE_OPTION_STRIPE_COUNT,
741 if data_pool is not None:
742 rbd_image_options_set_string(opts,
743 RBD_IMAGE_OPTION_DATA_POOL,
746 ret = rbd_create4(_ioctx, _name, _size, opts)
748 rbd_image_options_destroy(opts)
750 raise make_ex(ret, 'error creating image')
752 def clone(self, p_ioctx, p_name, p_snapname, c_ioctx, c_name,
753 features=None, order=None, stripe_unit=None, stripe_count=None,
756 Clone a parent rbd snapshot into a COW sparse child.
758 :param p_ioctx: the parent context that represents the parent snap
759 :type ioctx: :class:`rados.Ioctx`
760 :param p_name: the parent image name
762 :param p_snapname: the parent image snapshot name
764 :param c_ioctx: the child context that represents the new clone
765 :type ioctx: :class:`rados.Ioctx`
766 :param c_name: the clone (child) name
768 :param features: bitmask of features to enable; if set, must include layering
770 :param order: the image is split into (2**order) byte objects
772 :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
773 :type stripe_unit: int
774 :param stripe_count: objects to stripe over before looping
775 :type stripe_count: int
776 :param data_pool: optional separate pool for data blocks
778 :raises: :class:`TypeError`
779 :raises: :class:`InvalidArgument`
780 :raises: :class:`ImageExists`
781 :raises: :class:`FunctionNotSupported`
782 :raises: :class:`ArgumentOutOfRange`
784 p_snapname = cstr(p_snapname, 'p_snapname')
785 p_name = cstr(p_name, 'p_name')
786 c_name = cstr(c_name, 'c_name')
788 rados_ioctx_t _p_ioctx = convert_ioctx(p_ioctx)
789 rados_ioctx_t _c_ioctx = convert_ioctx(c_ioctx)
790 char *_p_name = p_name
791 char *_p_snapname = p_snapname
792 char *_c_name = c_name
793 rbd_image_options_t opts
795 rbd_image_options_create(&opts)
797 if features is not None:
798 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
800 if order is not None:
801 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
803 if stripe_unit is not None:
804 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
806 if stripe_count is not None:
807 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
809 if data_pool is not None:
810 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
813 ret = rbd_clone3(_p_ioctx, _p_name, _p_snapname,
814 _c_ioctx, _c_name, opts)
816 rbd_image_options_destroy(opts)
818 raise make_ex(ret, 'error creating clone')
820 def list(self, ioctx):
824 :param ioctx: determines which RADOS pool is read
825 :type ioctx: :class:`rados.Ioctx`
826 :returns: list -- a list of image names
829 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
834 c_names = <char *>realloc_chk(c_names, size)
836 ret = rbd_list(_ioctx, c_names, &size)
839 elif ret != -errno.ERANGE:
840 raise make_ex(ret, 'error listing images')
841 return [decode_cstr(name) for name in c_names[:ret].split(b'\0')
846 def remove(self, ioctx, name):
848 Delete an RBD image. This may take a long time, since it does
849 not return until every object that comprises the image has
850 been deleted. Note that all snapshots must be deleted before
851 the image can be removed. If there are snapshots left,
852 :class:`ImageHasSnapshots` is raised. If the image is still
853 open, or the watch from a crashed client has not expired,
854 :class:`ImageBusy` is raised.
856 :param ioctx: determines which RADOS pool the image is in
857 :type ioctx: :class:`rados.Ioctx`
858 :param name: the name of the image to remove
860 :raises: :class:`ImageNotFound`, :class:`ImageBusy`,
861 :class:`ImageHasSnapshots`
863 name = cstr(name, 'name')
865 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
868 ret = rbd_remove(_ioctx, _name)
870 raise make_ex(ret, 'error removing image')
872 def rename(self, ioctx, src, dest):
876 :param ioctx: determines which RADOS pool the image is in
877 :type ioctx: :class:`rados.Ioctx`
878 :param src: the current name of the image
880 :param dest: the new name of the image
882 :raises: :class:`ImageNotFound`, :class:`ImageExists`
884 src = cstr(src, 'src')
885 dest = cstr(dest, 'dest')
887 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
891 ret = rbd_rename(_ioctx, _src, _dest)
893 raise make_ex(ret, 'error renaming image')
895 def trash_move(self, ioctx, name, delay=0):
897 Moves an RBD image to the trash.
898 :param ioctx: determines which RADOS pool the image is in
899 :type ioctx: :class:`rados.Ioctx`
900 :param name: the name of the image to remove
902 :param delay: time delay in seconds before the image can be deleted
905 :raises: :class:`ImageNotFound`
907 name = cstr(name, 'name')
909 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
911 uint64_t _delay = delay
913 ret = rbd_trash_move(_ioctx, _name, _delay)
915 raise make_ex(ret, 'error moving image to trash')
917 def trash_remove(self, ioctx, image_id, force=False):
919 Deletes an RBD image from trash. If image deferment time has not
920 expired :class:`PermissionError` is raised.
921 :param ioctx: determines which RADOS pool the image is in
922 :type ioctx: :class:`rados.Ioctx`
923 :param image_id: the id of the image to remove
925 :param force: force remove even if deferment time has not expired
927 :raises: :class:`ImageNotFound`, :class:`PermissionError`
929 image_id = cstr(image_id, 'image_id')
931 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
932 char *_image_id = image_id
935 ret = rbd_trash_remove(_ioctx, _image_id, _force)
937 raise make_ex(ret, 'error deleting image from trash')
939 def trash_get(self, ioctx, image_id):
941 Retrieve RBD image info from trash
942 :param ioctx: determines which RADOS pool the image is in
943 :type ioctx: :class:`rados.Ioctx`
944 :param image_id: the id of the image to restore
946 :returns: dict - contains the following keys:
948 * ``id`` (str) - image id
950 * ``name`` (str) - image name
952 * ``source`` (str) - source of deletion
954 * ``deletion_time`` (datetime) - time of deletion
956 * ``deferment_end_time`` (datetime) - time that an image is allowed
957 to be removed from trash
959 :raises: :class:`ImageNotFound`
961 image_id = cstr(image_id, 'image_id')
963 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
964 char *_image_id = image_id
965 rbd_trash_image_info_t c_info
967 ret = rbd_trash_get(_ioctx, _image_id, &c_info)
969 raise make_ex(ret, 'error restoring image from trash')
971 __source_string = ['USER', 'MIRRORING']
973 'id' : decode_cstr(c_info.id),
974 'name' : decode_cstr(c_info.name),
975 'source' : __source_string[c_info.source],
976 'deletion_time' : datetime.fromtimestamp(c_info.deletion_time),
977 'deferment_end_time' : datetime.fromtimestamp(c_info.deferment_end_time)
979 rbd_trash_get_cleanup(&c_info)
982 def trash_list(self, ioctx):
984 Lists all entries from trash.
985 :param ioctx: determines which RADOS pool the image is in
986 :type ioctx: :class:`rados.Ioctx`
987 :returns: :class:`TrashIterator`
989 return TrashIterator(ioctx)
991 def trash_restore(self, ioctx, image_id, name):
993 Restores an RBD image from trash.
994 :param ioctx: determines which RADOS pool the image is in
995 :type ioctx: :class:`rados.Ioctx`
996 :param image_id: the id of the image to restore
998 :param name: the new name of the restored image
1000 :raises: :class:`ImageNotFound`
1002 image_id = cstr(image_id, 'image_id')
1003 name = cstr(name, 'name')
1005 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1006 char *_image_id = image_id
1009 ret = rbd_trash_restore(_ioctx, _image_id, _name)
1011 raise make_ex(ret, 'error restoring image from trash')
1013 def mirror_mode_get(self, ioctx):
1015 Get pool mirror mode.
1017 :param ioctx: determines which RADOS pool is read
1018 :type ioctx: :class:`rados.Ioctx`
1019 :returns: int - pool mirror mode
1022 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1023 rbd_mirror_mode_t mirror_mode
1025 ret = rbd_mirror_mode_get(_ioctx, &mirror_mode)
1027 raise make_ex(ret, 'error getting mirror mode')
1030 def mirror_mode_set(self, ioctx, mirror_mode):
1032 Set pool mirror mode.
1034 :param ioctx: determines which RADOS pool is written
1035 :type ioctx: :class:`rados.Ioctx`
1036 :param mirror_mode: mirror mode to set
1037 :type mirror_mode: int
1040 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1041 rbd_mirror_mode_t _mirror_mode = mirror_mode
1043 ret = rbd_mirror_mode_set(_ioctx, _mirror_mode)
1045 raise make_ex(ret, 'error setting mirror mode')
1047 def mirror_peer_add(self, ioctx, cluster_name, client_name):
1051 :param ioctx: determines which RADOS pool is used
1052 :type ioctx: :class:`rados.Ioctx`
1053 :param cluster_name: mirror peer cluster name
1054 :type cluster_name: str
1055 :param client_name: mirror peer client name
1056 :type client_name: str
1057 :returns: str - peer uuid
1059 cluster_name = cstr(cluster_name, 'cluster_name')
1060 client_name = cstr(client_name, 'client_name')
1062 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1064 size_t _uuid_max_length = 512
1065 char *_cluster_name = cluster_name
1066 char *_client_name = client_name
1068 _uuid = <char *>realloc_chk(_uuid, _uuid_max_length)
1069 ret = rbd_mirror_peer_add(_ioctx, _uuid, _uuid_max_length,
1070 _cluster_name, _client_name)
1072 raise make_ex(ret, 'error adding mirror peer')
1073 return decode_cstr(_uuid)
1077 def mirror_peer_remove(self, ioctx, uuid):
1081 :param ioctx: determines which RADOS pool is used
1082 :type ioctx: :class:`rados.Ioctx`
1083 :param uuid: peer uuid
1086 uuid = cstr(uuid, 'uuid')
1088 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1091 ret = rbd_mirror_peer_remove(_ioctx, _uuid)
1093 raise make_ex(ret, 'error removing mirror peer')
1095 def mirror_peer_list(self, ioctx):
1097 Iterate over the peers of a pool.
1099 :param ioctx: determines which RADOS pool is read
1100 :type ioctx: :class:`rados.Ioctx`
1101 :returns: :class:`MirrorPeerIterator`
1103 return MirrorPeerIterator(ioctx)
1105 def mirror_peer_set_client(self, ioctx, uuid, client_name):
1107 Set mirror peer client name
1109 :param ioctx: determines which RADOS pool is written
1110 :type ioctx: :class:`rados.Ioctx`
1111 :param uuid: uuid of the mirror peer
1113 :param client_name: client name of the mirror peer to set
1114 :type client_name: str
1116 uuid = cstr(uuid, 'uuid')
1117 client_name = cstr(client_name, 'client_name')
1119 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1121 char *_client_name = client_name
1123 ret = rbd_mirror_peer_set_client(_ioctx, _uuid, _client_name)
1125 raise make_ex(ret, 'error setting mirror peer client')
1127 def mirror_peer_set_cluster(self, ioctx, uuid, cluster_name):
1129 Set mirror peer cluster name
1131 :param ioctx: determines which RADOS pool is written
1132 :type ioctx: :class:`rados.Ioctx`
1133 :param uuid: uuid of the mirror peer
1135 :param cluster_name: cluster name of the mirror peer to set
1136 :type cluster_name: str
1138 uuid = cstr(uuid, 'uuid')
1139 cluster_name = cstr(cluster_name, 'cluster_name')
1141 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1143 char *_cluster_name = cluster_name
1145 ret = rbd_mirror_peer_set_cluster(_ioctx, _uuid, _cluster_name)
1147 raise make_ex(ret, 'error setting mirror peer cluster')
1149 def mirror_image_status_list(self, ioctx):
1151 Iterate over the mirror image statuses of a pool.
1153 :param ioctx: determines which RADOS pool is read
1154 :type ioctx: :class:`rados.Ioctx`
1155 :returns: :class:`MirrorImageStatus`
1157 return MirrorImageStatusIterator(ioctx)
1159 def mirror_image_status_summary(self, ioctx):
1161 Get mirror image status summary of a pool.
1163 :param ioctx: determines which RADOS pool is read
1164 :type ioctx: :class:`rados.Ioctx`
1165 :returns: list - a list of (state, count) tuples
1168 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1169 rbd_mirror_image_status_state_t *states = NULL
1173 states = <rbd_mirror_image_status_state_t *>realloc_chk(states,
1174 sizeof(rbd_mirror_image_status_state_t) * maxlen)
1175 counts = <int *>realloc_chk(counts, sizeof(int) * maxlen)
1177 ret = rbd_mirror_image_status_summary(_ioctx, states, counts,
1180 raise make_ex(ret, 'error getting mirror image status summary')
1181 return [(states[i], counts[i]) for i in range(maxlen)]
1186 cdef class MirrorPeerIterator(object):
1188 Iterator over mirror peer info for a pool.
1190 Yields a dictionary containing information about a peer.
1194 * ``uuid`` (str) - uuid of the peer
1196 * ``cluster_name`` (str) - cluster name of the peer
1198 * ``client_name`` (str) - client name of the peer
1202 rbd_mirror_peer_t *peers
1205 def __init__(self, ioctx):
1207 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1211 self.peers = <rbd_mirror_peer_t *>realloc_chk(
1212 self.peers, self.num_peers * sizeof(rbd_mirror_peer_t))
1214 ret = rbd_mirror_peer_list(_ioctx, self.peers, &self.num_peers)
1216 if ret == -errno.ERANGE:
1219 raise make_ex(ret, 'error listing peers')
1223 for i in range(self.num_peers):
1225 'uuid' : decode_cstr(self.peers[i].uuid),
1226 'cluster_name' : decode_cstr(self.peers[i].cluster_name),
1227 'client_name' : decode_cstr(self.peers[i].client_name),
1230 def __dealloc__(self):
1232 rbd_mirror_peer_list_cleanup(self.peers, self.num_peers)
1235 cdef class MirrorImageStatusIterator(object):
1237 Iterator over mirror image status for a pool.
1239 Yields a dictionary containing mirror status of an image.
1243 * ``name`` (str) - mirror image name
1245 * `info` (dict) - mirror image info
1247 * `state` (int) - mirror state
1249 * `description` (str) - status description
1251 * `last_update` (datetime) - last status update time
1253 * ``up`` (bool) - is mirroring agent up
1261 rbd_mirror_image_status_t *images
1264 def __init__(self, ioctx):
1265 self.ioctx = convert_ioctx(ioctx)
1266 self.max_read = 1024
1267 self.last_read = strdup("")
1268 self.image_ids = <char **>realloc_chk(NULL,
1269 sizeof(char *) * self.max_read)
1270 self.images = <rbd_mirror_image_status_t *>realloc_chk(NULL,
1271 sizeof(rbd_mirror_image_status_t) * self.max_read)
1273 self.get_next_chunk()
1276 while self.size > 0:
1277 for i in range(self.size):
1279 'name' : decode_cstr(self.images[i].name),
1281 'global_id' : decode_cstr(self.images[i].info.global_id),
1282 'state' : self.images[i].info.state,
1284 'state' : self.images[i].state,
1285 'description' : decode_cstr(self.images[i].description),
1286 'last_update' : datetime.fromtimestamp(self.images[i].last_update),
1287 'up' : self.images[i].up,
1289 if self.size < self.max_read:
1291 self.get_next_chunk()
1293 def __dealloc__(self):
1294 rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1297 free(self.last_read)
1299 free(self.image_ids)
1303 def get_next_chunk(self):
1305 rbd_mirror_image_status_list_cleanup(self.image_ids, self.images,
1309 ret = rbd_mirror_image_status_list(self.ioctx, self.last_read,
1310 self.max_read, self.image_ids,
1311 self.images, &self.size)
1313 raise make_ex(ret, 'error listing mirror images status')
1315 free(self.last_read)
1316 last_read = decode_cstr(self.image_ids[self.size - 1])
1317 self.last_read = strdup(last_read)
1319 free(self.last_read)
1320 self.last_read = strdup("")
1322 cdef int diff_iterate_cb(uint64_t offset, size_t length, int write, void *cb) \
1323 except? -9000 with gil:
1324 # Make sure that if we wound up with an exception from a previous callback,
1325 # we stop calling back (just in case librbd ever fails to bail out on the
1326 # first negative return, as older versions did)
1327 if exc.PyErr_Occurred():
1329 ret = (<object>cb)(offset, length, bool(write))
1335 cdef class Image(object):
1337 This class represents an RBD image. It is used to perform I/O on
1338 the image and interact with snapshots.
1340 **Note**: Any method of this class may raise :class:`ImageNotFound`
1341 if the image has been deleted.
1343 cdef rbd_image_t image
1347 cdef rados_ioctx_t _ioctx
1349 def __init__(self, ioctx, name, snapshot=None, read_only=False):
1351 Open the image at the given snapshot.
1352 If a snapshot is specified, the image will be read-only, unless
1353 :func:`Image.set_snap` is called later.
1355 If read-only mode is used, metadata for the :class:`Image`
1356 object (such as which snapshots exist) may become obsolete. See
1357 the C api for more details.
1359 To clean up from opening the image, :func:`Image.close` should
1360 be called. For ease of use, this is done automatically when
1361 an :class:`Image` is used as a context manager (see :pep:`343`).
1363 :param ioctx: determines which RADOS pool the image is in
1364 :type ioctx: :class:`rados.Ioctx`
1365 :param name: the name of the image
1367 :param snapshot: which snapshot to read from
1368 :type snaphshot: str
1369 :param read_only: whether to open the image in read-only mode
1370 :type read_only: bool
1372 name = cstr(name, 'name')
1373 snapshot = cstr(snapshot, 'snapshot', opt=True)
1376 # Keep around a reference to the ioctx, so it won't get deleted
1379 rados_ioctx_t _ioctx = convert_ioctx(ioctx)
1381 char *_snapshot = opt_str(snapshot)
1384 ret = rbd_open_read_only(_ioctx, _name, &self.image, _snapshot)
1387 ret = rbd_open(_ioctx, _name, &self.image, _snapshot)
1389 raise make_ex(ret, 'error opening image %s at snapshot %s' % (name, snapshot))
1392 def __enter__(self):
1395 def __exit__(self, type_, value, traceback):
1397 Closes the image. See :func:`close`
1402 def __get_completion(self, oncomplete):
1404 Constructs a completion to use with asynchronous operations
1406 :param oncomplete: callback for the completion
1408 :raises: :class:`Error`
1409 :returns: completion object
1412 completion_obj = Completion(self, oncomplete)
1415 rbd_completion_t completion
1416 PyObject* p_completion_obj= <PyObject*>completion_obj
1419 ret = rbd_aio_create_completion(p_completion_obj, __aio_complete_cb,
1422 raise make_ex(ret, "error getting a completion")
1424 completion_obj.rbd_comp = completion
1425 return completion_obj
1429 Release the resources used by this image object.
1431 After this is called, this object should not be used.
1436 ret = rbd_close(self.image)
1438 raise make_ex(ret, 'error while closing image %s' % (
1441 def __dealloc__(self):
1445 return "rbd.Image(ioctx, %r)" % self.name
1447 def resize(self, size):
1449 Change the size of the image.
1451 :param size: the new size of the image
1454 cdef uint64_t _size = size
1456 ret = rbd_resize(self.image, _size)
1458 raise make_ex(ret, 'error resizing image %s' % (self.name,))
1462 Get information about the image. Currently parent pool and
1463 parent name are always -1 and ''.
1465 :returns: dict - contains the following keys:
1467 * ``size`` (int) - the size of the image in bytes
1469 * ``obj_size`` (int) - the size of each object that comprises the
1472 * ``num_objs`` (int) - the number of objects in the image
1474 * ``order`` (int) - log_2(object_size)
1476 * ``block_name_prefix`` (str) - the prefix of the RADOS objects used
1479 * ``parent_pool`` (int) - deprecated
1481 * ``parent_name`` (str) - deprecated
1483 See also :meth:`format` and :meth:`features`.
1486 cdef rbd_image_info_t info
1488 ret = rbd_stat(self.image, &info, sizeof(info))
1490 raise make_ex(ret, 'error getting info for image %s' % (self.name,))
1493 'obj_size' : info.obj_size,
1494 'num_objs' : info.num_objs,
1495 'order' : info.order,
1496 'block_name_prefix' : decode_cstr(info.block_name_prefix),
1497 'parent_pool' : info.parent_pool,
1498 'parent_name' : info.parent_name
1503 Get the RBD v2 internal image id
1505 :returns: str - image id
1508 int ret = -errno.ERANGE
1510 char *image_id = NULL
1512 while ret == -errno.ERANGE and size <= 4096:
1513 image_id = <char *>realloc_chk(image_id, size)
1515 ret = rbd_get_id(self.image, image_id, size)
1516 if ret == -errno.ERANGE:
1520 raise make_ex(ret, 'error getting id for image %s' % (self.name,))
1521 return decode_cstr(image_id)
1525 def block_name_prefix(self):
1527 Get the RBD block name prefix
1529 :returns: str - block name prefix
1532 int ret = -errno.ERANGE
1536 while ret == -errno.ERANGE and size <= 4096:
1537 prefix = <char *>realloc_chk(prefix, size)
1539 ret = rbd_get_block_name_prefix(self.image, prefix, size)
1540 if ret == -errno.ERANGE:
1544 raise make_ex(ret, 'error getting block name prefix for image %s' % (self.name,))
1545 return decode_cstr(prefix)
1549 def parent_info(self):
1551 Get information about a cloned image's parent (if any)
1553 :returns: tuple - ``(pool name, image name, snapshot name)`` components
1555 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1558 int ret = -errno.ERANGE
1562 char *snapname = NULL
1564 while ret == -errno.ERANGE and size <= 4096:
1565 pool = <char *>realloc_chk(pool, size)
1566 name = <char *>realloc_chk(name, size)
1567 snapname = <char *>realloc_chk(snapname, size)
1569 ret = rbd_get_parent_info2(self.image, pool, size, name,
1570 size, NULL, 0, snapname, size)
1571 if ret == -errno.ERANGE:
1575 raise make_ex(ret, 'error getting parent info for image %s' % (self.name,))
1576 return (decode_cstr(pool), decode_cstr(name), decode_cstr(snapname))
1582 def parent_id(self):
1584 Get image id of a cloned image's parent (if any)
1586 :returns: str - the parent id
1587 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1590 int ret = -errno.ERANGE
1592 char *parent_id = NULL
1594 while ret == -errno.ERANGE and size <= 4096:
1595 parent_id = <char *>realloc_chk(parent_id, size)
1597 ret = rbd_get_parent_info2(self.image, NULL, 0, NULL, 0,
1598 parent_id, size, NULL, 0)
1599 if ret == -errno.ERANGE:
1603 raise make_ex(ret, 'error getting parent id for image %s' % (self.name,))
1604 return decode_cstr(parent_id)
1608 def old_format(self):
1610 Find out whether the image uses the old RBD format.
1612 :returns: bool - whether the image uses the old RBD format
1616 ret = rbd_get_old_format(self.image, &old)
1618 raise make_ex(ret, 'error getting old_format for image %s' % (self.name))
1623 Get the size of the image. If open to a snapshot, returns the
1624 size of that snapshot.
1626 :returns: the size of the image in bytes
1628 cdef uint64_t image_size
1630 ret = rbd_get_size(self.image, &image_size)
1632 raise make_ex(ret, 'error getting size for image %s' % (self.name))
1637 Gets the features bitmask of the image.
1639 :returns: int - the features bitmask of the image
1641 cdef uint64_t features
1643 ret = rbd_get_features(self.image, &features)
1645 raise make_ex(ret, 'error getting features for image %s' % (self.name))
1648 def update_features(self, features, enabled):
1650 Updates the features bitmask of the image by enabling/disabling
1651 a single feature. The feature must support the ability to be
1652 dynamically enabled/disabled.
1654 :param features: feature bitmask to enable/disable
1656 :param enabled: whether to enable/disable the feature
1658 :raises: :class:`InvalidArgument`
1661 uint64_t _features = features
1662 uint8_t _enabled = bool(enabled)
1664 ret = rbd_update_features(self.image, _features, _enabled)
1666 raise make_ex(ret, 'error updating features for image %s' %
1671 Gets the number of overlapping bytes between the image and its parent
1672 image. If open to a snapshot, returns the overlap between the snapshot
1673 and the parent image.
1675 :returns: int - the overlap in bytes
1676 :raises: :class:`ImageNotFound` if the image doesn't have a parent
1678 cdef uint64_t overlap
1680 ret = rbd_get_overlap(self.image, &overlap)
1682 raise make_ex(ret, 'error getting overlap for image %s' % (self.name))
1687 Gets the flags bitmask of the image.
1689 :returns: int - the flags bitmask of the image
1693 ret = rbd_get_flags(self.image, &flags)
1695 raise make_ex(ret, 'error getting flags for image %s' % (self.name))
1698 def is_exclusive_lock_owner(self):
1700 Gets the status of the image exclusive lock.
1702 :returns: bool - true if the image is exclusively locked
1706 ret = rbd_is_exclusive_lock_owner(self.image, &owner)
1708 raise make_ex(ret, 'error getting lock status for image %s' % (self.name))
1711 def copy(self, dest_ioctx, dest_name, features=None, order=None,
1712 stripe_unit=None, stripe_count=None, data_pool=None):
1714 Copy the image to another location.
1716 :param dest_ioctx: determines which pool to copy into
1717 :type dest_ioctx: :class:`rados.Ioctx`
1718 :param dest_name: the name of the copy
1719 :type dest_name: str
1720 :param features: bitmask of features to enable; if set, must include layering
1722 :param order: the image is split into (2**order) byte objects
1724 :param stripe_unit: stripe unit in bytes (default None to let librbd decide)
1725 :type stripe_unit: int
1726 :param stripe_count: objects to stripe over before looping
1727 :type stripe_count: int
1728 :param data_pool: optional separate pool for data blocks
1729 :type data_pool: str
1730 :raises: :class:`TypeError`
1731 :raises: :class:`InvalidArgument`
1732 :raises: :class:`ImageExists`
1733 :raises: :class:`FunctionNotSupported`
1734 :raises: :class:`ArgumentOutOfRange`
1736 dest_name = cstr(dest_name, 'dest_name')
1738 rados_ioctx_t _dest_ioctx = convert_ioctx(dest_ioctx)
1739 char *_dest_name = dest_name
1740 rbd_image_options_t opts
1742 rbd_image_options_create(&opts)
1744 if features is not None:
1745 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_FEATURES,
1747 if order is not None:
1748 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_ORDER,
1750 if stripe_unit is not None:
1751 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_UNIT,
1753 if stripe_count is not None:
1754 rbd_image_options_set_uint64(opts, RBD_IMAGE_OPTION_STRIPE_COUNT,
1756 if data_pool is not None:
1757 rbd_image_options_set_string(opts, RBD_IMAGE_OPTION_DATA_POOL,
1760 ret = rbd_copy3(self.image, _dest_ioctx, _dest_name, opts)
1762 rbd_image_options_destroy(opts)
1764 raise make_ex(ret, 'error copying image %s to %s' % (self.name, dest_name))
1766 def list_snaps(self):
1768 Iterate over the snapshots of an image.
1770 :returns: :class:`SnapIterator`
1772 return SnapIterator(self)
1774 def create_snap(self, name):
1776 Create a snapshot of the image.
1778 :param name: the name of the snapshot
1780 :raises: :class:`ImageExists`
1782 name = cstr(name, 'name')
1783 cdef char *_name = name
1785 ret = rbd_snap_create(self.image, _name)
1787 raise make_ex(ret, 'error creating snapshot %s from %s' % (name, self.name))
1789 def rename_snap(self, srcname, dstname):
1791 rename a snapshot of the image.
1793 :param srcname: the src name of the snapshot
1795 :param dstname: the dst name of the snapshot
1797 :raises: :class:`ImageExists`
1799 srcname = cstr(srcname, 'srcname')
1800 dstname = cstr(dstname, 'dstname')
1802 char *_srcname = srcname
1803 char *_dstname = dstname
1805 ret = rbd_snap_rename(self.image, _srcname, _dstname)
1807 raise make_ex(ret, 'error renaming snapshot of %s from %s to %s' % (self.name, srcname, dstname))
1809 def remove_snap(self, name):
1811 Delete a snapshot of the image.
1813 :param name: the name of the snapshot
1815 :raises: :class:`IOError`, :class:`ImageBusy`
1817 name = cstr(name, 'name')
1818 cdef char *_name = name
1820 ret = rbd_snap_remove(self.image, _name)
1822 raise make_ex(ret, 'error removing snapshot %s from %s' % (name, self.name))
1824 def remove_snap2(self, name, flags):
1826 Delete a snapshot of the image.
1828 :param name: the name of the snapshot
1829 :param flags: the flags for removal
1831 :raises: :class:`IOError`, :class:`ImageBusy`
1833 name = cstr(name, 'name')
1836 uint32_t _flags = flags
1837 librbd_progress_fn_t prog_cb = &no_op_progress_callback
1839 ret = rbd_snap_remove2(self.image, _name, _flags, prog_cb, NULL)
1841 raise make_ex(ret, 'error removing snapshot %s from %s with flags %llx' % (name, self.name, flags))
1843 def rollback_to_snap(self, name):
1845 Revert the image to its contents at a snapshot. This is a
1846 potentially expensive operation, since it rolls back each
1847 object individually.
1849 :param name: the snapshot to rollback to
1851 :raises: :class:`IOError`
1853 name = cstr(name, 'name')
1854 cdef char *_name = name
1856 ret = rbd_snap_rollback(self.image, _name)
1858 raise make_ex(ret, 'error rolling back image %s to snapshot %s' % (self.name, name))
1860 def protect_snap(self, name):
1862 Mark a snapshot as protected. This means it can't be deleted
1863 until it is unprotected.
1865 :param name: the snapshot to protect
1867 :raises: :class:`IOError`, :class:`ImageNotFound`
1869 name = cstr(name, 'name')
1870 cdef char *_name = name
1872 ret = rbd_snap_protect(self.image, _name)
1874 raise make_ex(ret, 'error protecting snapshot %s@%s' % (self.name, name))
1876 def unprotect_snap(self, name):
1878 Mark a snapshot unprotected. This allows it to be deleted if
1881 :param name: the snapshot to unprotect
1883 :raises: :class:`IOError`, :class:`ImageNotFound`
1885 name = cstr(name, 'name')
1886 cdef char *_name = name
1888 ret = rbd_snap_unprotect(self.image, _name)
1890 raise make_ex(ret, 'error unprotecting snapshot %s@%s' % (self.name, name))
1892 def is_protected_snap(self, name):
1894 Find out whether a snapshot is protected from deletion.
1896 :param name: the snapshot to check
1898 :returns: bool - whether the snapshot is protected
1899 :raises: :class:`IOError`, :class:`ImageNotFound`
1901 name = cstr(name, 'name')
1906 ret = rbd_snap_is_protected(self.image, _name, &is_protected)
1908 raise make_ex(ret, 'error checking if snapshot %s@%s is protected' % (self.name, name))
1909 return is_protected == 1
1911 def get_snap_limit(self):
1913 Get the snapshot limit for an image.
1919 ret = rbd_snap_get_limit(self.image, &limit)
1921 raise make_ex(ret, 'error getting snapshot limit for %s' % self.name)
1924 def set_snap_limit(self, limit):
1926 Set the snapshot limit for an image.
1928 :param limit: the new limit to set
1932 uint64_t _limit = limit
1934 ret = rbd_snap_set_limit(self.image, _limit)
1936 raise make_ex(ret, 'error setting snapshot limit for %s' % self.name)
1939 def get_snap_timestamp(self, snap_id):
1941 Get the snapshot timestamp for an image.
1942 :param snap_id: the snapshot id of a snap shot
1946 uint64_t _snap_id = snap_id
1948 ret = rbd_snap_get_timestamp(self.image, _snap_id, ×tamp)
1950 raise make_ex(ret, 'error getting snapshot timestamp for image: %s, snap_id: %d' % (self.name, snap_id))
1951 return datetime.fromtimestamp(timestamp.tv_sec)
1953 def remove_snap_limit(self):
1955 Remove the snapshot limit for an image, essentially setting
1956 the limit to the maximum size allowed by the implementation.
1959 ret = rbd_snap_set_limit(self.image, UINT64_MAX)
1961 raise make_ex(ret, 'error removing snapshot limit for %s' % self.name)
1964 def set_snap(self, name):
1966 Set the snapshot to read from. Writes will raise ReadOnlyImage
1967 while a snapshot is set. Pass None to unset the snapshot
1968 (reads come from the current image) , and allow writing again.
1970 :param name: the snapshot to read from, or None to unset the snapshot
1971 :type name: str or None
1973 name = cstr(name, 'name', opt=True)
1974 cdef char *_name = opt_str(name)
1976 ret = rbd_snap_set(self.image, _name)
1978 raise make_ex(ret, 'error setting image %s to snapshot %s' % (self.name, name))
1980 def read(self, offset, length, fadvise_flags=0):
1982 Read data from the image. Raises :class:`InvalidArgument` if
1983 part of the range specified is outside the image.
1985 :param offset: the offset to start reading at
1987 :param length: how many bytes to read
1989 :param fadvise_flags: fadvise flags for this read
1990 :type fadvise_flags: int
1991 :returns: str - the data read
1992 :raises: :class:`InvalidArgument`, :class:`IOError`
1995 # This usage of the Python API allows us to construct a string
1996 # that librbd directly reads into, avoiding an extra copy. Although
1997 # strings are normally immutable, this usage is explicitly supported
1998 # for freshly created string objects.
2001 uint64_t _offset = offset
2002 size_t _length = length
2003 int _fadvise_flags = fadvise_flags
2004 PyObject* ret_s = NULL
2005 ret_s = PyBytes_FromStringAndSize(NULL, length)
2007 ret_buf = PyBytes_AsString(ret_s)
2009 ret = rbd_read2(self.image, _offset, _length, ret_buf,
2012 raise make_ex(ret, 'error reading %s %ld~%ld' % (self.name, offset, length))
2014 if ret != <ssize_t>length:
2015 _PyBytes_Resize(&ret_s, ret)
2017 return <object>ret_s
2019 # We DECREF unconditionally: the cast to object above will have
2020 # INCREFed if necessary. This also takes care of exceptions,
2021 # including if _PyString_Resize fails (that will free the string
2022 # itself and set ret_s to NULL, hence XDECREF).
2023 ref.Py_XDECREF(ret_s)
2025 def diff_iterate(self, offset, length, from_snapshot, iterate_cb,
2026 include_parent = True, whole_object = False):
2028 Iterate over the changed extents of an image.
2030 This will call iterate_cb with three arguments:
2032 (offset, length, exists)
2034 where the changed extent starts at offset bytes, continues for
2035 length bytes, and is full of data (if exists is True) or zeroes
2036 (if exists is False).
2038 If from_snapshot is None, it is interpreted as the beginning
2039 of time and this generates all allocated extents.
2041 The end version is whatever is currently selected (via set_snap)
2044 iterate_cb may raise an exception, which will abort the diff and will be
2045 propagated to the caller.
2047 Raises :class:`InvalidArgument` if from_snapshot is after
2048 the currently set snapshot.
2050 Raises :class:`ImageNotFound` if from_snapshot is not the name
2051 of a snapshot of the image.
2053 :param offset: start offset in bytes
2055 :param length: size of region to report on, in bytes
2057 :param from_snapshot: starting snapshot name, or None
2058 :type from_snapshot: str or None
2059 :param iterate_cb: function to call for each extent
2060 :type iterate_cb: function acception arguments for offset,
2062 :param include_parent: True if full history diff should include parent
2063 :type include_parent: bool
2064 :param whole_object: True if diff extents should cover whole object
2065 :type whole_object: bool
2066 :raises: :class:`InvalidArgument`, :class:`IOError`,
2067 :class:`ImageNotFound`
2069 from_snapshot = cstr(from_snapshot, 'from_snapshot', opt=True)
2071 char *_from_snapshot = opt_str(from_snapshot)
2072 uint64_t _offset = offset, _length = length
2073 uint8_t _include_parent = include_parent
2074 uint8_t _whole_object = whole_object
2076 ret = rbd_diff_iterate2(self.image, _from_snapshot, _offset,
2077 _length, _include_parent, _whole_object,
2078 &diff_iterate_cb, <void *>iterate_cb)
2080 msg = 'error generating diff from snapshot %s' % from_snapshot
2081 raise make_ex(ret, msg)
2083 def write(self, data, offset, fadvise_flags=0):
2085 Write data to the image. Raises :class:`InvalidArgument` if
2086 part of the write would fall outside the image.
2088 :param data: the data to be written
2090 :param offset: where to start writing data
2092 :param fadvise_flags: fadvise flags for this write
2093 :type fadvise_flags: int
2094 :returns: int - the number of bytes written
2095 :raises: :class:`IncompleteWriteError`, :class:`LogicError`,
2096 :class:`InvalidArgument`, :class:`IOError`
2098 if not isinstance(data, bytes):
2099 raise TypeError('data must be a byte string')
2101 uint64_t _offset = offset, length = len(data)
2103 int _fadvise_flags = fadvise_flags
2105 ret = rbd_write2(self.image, _offset, length, _data, _fadvise_flags)
2107 if ret == <ssize_t>length:
2110 raise make_ex(ret, "error writing to %s" % (self.name,))
2111 elif ret < <ssize_t>length:
2112 raise IncompleteWriteError("Wrote only %ld out of %ld bytes" % (ret, length))
2114 raise LogicError("logic error: rbd_write(%s) \
2115 returned %d, but %d was the maximum number of bytes it could have \
2116 written." % (self.name, ret, length))
2118 def discard(self, offset, length):
2120 Trim the range from the image. It will be logically filled
2123 cdef uint64_t _offset = offset, _length = length
2125 ret = rbd_discard(self.image, _offset, _length)
2127 msg = 'error discarding region %d~%d' % (offset, length)
2128 raise make_ex(ret, msg)
2132 Block until all writes are fully flushed if caching is enabled.
2135 ret = rbd_flush(self.image)
2137 raise make_ex(ret, 'error flushing image')
2139 def invalidate_cache(self):
2141 Drop any cached data for the image.
2144 ret = rbd_invalidate_cache(self.image)
2146 raise make_ex(ret, 'error invalidating cache')
2148 def stripe_unit(self):
2150 Returns the stripe unit used for the image.
2152 cdef uint64_t stripe_unit
2154 ret = rbd_get_stripe_unit(self.image, &stripe_unit)
2156 raise make_ex(ret, 'error getting stripe unit for image %s' % (self.name))
2159 def stripe_count(self):
2161 Returns the stripe count used for the image.
2163 cdef uint64_t stripe_count
2165 ret = rbd_get_stripe_count(self.image, &stripe_count)
2167 raise make_ex(ret, 'error getting stripe count for image %s' % (self.name))
2170 def create_timestamp(self):
2172 Returns the create timestamp for the image.
2177 ret = rbd_get_create_timestamp(self.image, ×tamp)
2179 raise make_ex(ret, 'error getting create timestamp for image: %s' % (self.name))
2180 return datetime.fromtimestamp(timestamp.tv_sec)
2184 Flatten clone image (copy all blocks from parent to child)
2187 ret = rbd_flatten(self.image)
2189 raise make_ex(ret, "error flattening %s" % self.name)
2191 def rebuild_object_map(self):
2193 Rebuilds the object map for the image HEAD or currently set snapshot
2195 cdef librbd_progress_fn_t prog_cb = &no_op_progress_callback
2197 ret = rbd_rebuild_object_map(self.image, prog_cb, NULL)
2199 raise make_ex(ret, "error rebuilding object map %s" % self.name)
2201 def list_children(self):
2203 List children of the currently set snapshot (set via set_snap()).
2205 :returns: list - a list of (pool name, image name) tuples
2208 size_t pools_size = 512, images_size = 512
2209 char *c_pools = NULL
2210 char *c_images = NULL
2213 c_pools = <char *>realloc_chk(c_pools, pools_size)
2214 c_images = <char *>realloc_chk(c_images, images_size)
2216 ret = rbd_list_children(self.image, c_pools, &pools_size,
2217 c_images, &images_size)
2220 elif ret != -errno.ERANGE:
2221 raise make_ex(ret, 'error listing images')
2224 pools = map(decode_cstr, c_pools[:pools_size - 1].split(b'\0'))
2225 images = map(decode_cstr, c_images[:images_size - 1].split(b'\0'))
2226 return list(zip(pools, images))
2231 def list_lockers(self):
2233 List clients that have locked the image and information
2236 :returns: dict - contains the following keys:
2238 * ``tag`` - the tag associated with the lock (every
2239 additional locker must use the same tag)
2240 * ``exclusive`` - boolean indicating whether the
2241 lock is exclusive or shared
2242 * ``lockers`` - a list of (client, cookie, address)
2246 size_t clients_size = 512, cookies_size = 512
2247 size_t addrs_size = 512, tag_size = 512
2249 char *c_clients = NULL
2250 char *c_cookies = NULL
2251 char *c_addrs = NULL
2256 c_clients = <char *>realloc_chk(c_clients, clients_size)
2257 c_cookies = <char *>realloc_chk(c_cookies, cookies_size)
2258 c_addrs = <char *>realloc_chk(c_addrs, addrs_size)
2259 c_tag = <char *>realloc_chk(c_tag, tag_size)
2261 ret = rbd_list_lockers(self.image, &exclusive,
2263 c_clients, &clients_size,
2264 c_cookies, &cookies_size,
2265 c_addrs, &addrs_size)
2268 elif ret != -errno.ERANGE:
2269 raise make_ex(ret, 'error listing images')
2272 clients = map(decode_cstr, c_clients[:clients_size - 1].split(b'\0'))
2273 cookies = map(decode_cstr, c_cookies[:cookies_size - 1].split(b'\0'))
2274 addrs = map(decode_cstr, c_addrs[:addrs_size - 1].split(b'\0'))
2276 'tag' : decode_cstr(c_tag),
2277 'exclusive' : exclusive == 1,
2278 'lockers' : list(zip(clients, cookies, addrs)),
2286 def lock_acquire(self, lock_mode):
2288 Acquire a managed lock on the image.
2290 :param lock_mode: lock mode to set
2291 :type lock_mode: int
2292 :raises: :class:`ImageBusy` if the lock could not be acquired
2295 rbd_lock_mode_t _lock_mode = lock_mode
2297 ret = rbd_lock_acquire(self.image, _lock_mode)
2299 raise make_ex(ret, 'error acquiring lock on image')
2301 def lock_release(self):
2303 Release a managed lock on the image that was previously acquired.
2306 ret = rbd_lock_release(self.image)
2308 raise make_ex(ret, 'error releasing lock on image')
2310 def lock_get_owners(self):
2312 Iterate over the lock owners of an image.
2314 :returns: :class:`LockOwnerIterator`
2316 return LockOwnerIterator(self)
2318 def lock_break(self, lock_mode, lock_owner):
2320 Break the image lock held by a another client.
2322 :param lock_owner: the owner of the lock to break
2323 :type lock_owner: str
2325 lock_owner = cstr(lock_owner, 'lock_owner')
2327 rbd_lock_mode_t _lock_mode = lock_mode
2328 char *_lock_owner = lock_owner
2330 ret = rbd_lock_break(self.image, _lock_mode, _lock_owner)
2332 raise make_ex(ret, 'error breaking lock on image')
2334 def lock_exclusive(self, cookie):
2336 Take an exclusive lock on the image.
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 cdef char *_cookie = cookie
2344 ret = rbd_lock_exclusive(self.image, _cookie)
2346 raise make_ex(ret, 'error acquiring exclusive lock on image')
2348 def lock_shared(self, cookie, tag):
2350 Take a shared lock on the image. The tag must match
2351 that of the existing lockers, if any.
2353 :raises: :class:`ImageBusy` if a different client or cookie locked it
2354 :class:`ImageExists` if the same client and cookie locked it
2356 cookie = cstr(cookie, 'cookie')
2357 tag = cstr(tag, 'tag')
2359 char *_cookie = cookie
2362 ret = rbd_lock_shared(self.image, _cookie, _tag)
2364 raise make_ex(ret, 'error acquiring shared lock on image')
2366 def unlock(self, cookie):
2368 Release a lock on the image that was locked by this rados client.
2370 cookie = cstr(cookie, 'cookie')
2371 cdef char *_cookie = cookie
2373 ret = rbd_unlock(self.image, _cookie)
2375 raise make_ex(ret, 'error unlocking image')
2377 def break_lock(self, client, cookie):
2379 Release a lock held by another rados client.
2381 client = cstr(client, 'client')
2382 cookie = cstr(cookie, 'cookie')
2384 char *_client = client
2385 char *_cookie = cookie
2387 ret = rbd_break_lock(self.image, _client, _cookie)
2389 raise make_ex(ret, 'error unlocking image')
2391 def mirror_image_enable(self):
2393 Enable mirroring for the image.
2396 ret = rbd_mirror_image_enable(self.image)
2398 raise make_ex(ret, 'error enabling mirroring for image %s'
2401 def mirror_image_disable(self, force):
2403 Disable mirroring for the image.
2405 :param force: force disabling
2408 cdef bint c_force = force
2410 ret = rbd_mirror_image_disable(self.image, c_force)
2412 raise make_ex(ret, 'error disabling mirroring for image %s' %
2415 def mirror_image_promote(self, force):
2417 Promote the image to primary for mirroring.
2419 :param force: force promoting
2422 cdef bint c_force = force
2424 ret = rbd_mirror_image_promote(self.image, c_force)
2426 raise make_ex(ret, 'error promoting image %s to primary' %
2429 def mirror_image_demote(self):
2431 Demote the image to secondary for mirroring.
2434 ret = rbd_mirror_image_demote(self.image)
2436 raise make_ex(ret, 'error demoting image %s to secondary' %
2439 def mirror_image_resync(self):
2441 Flag the image to resync.
2444 ret = rbd_mirror_image_resync(self.image)
2446 raise make_ex(ret, 'error to resync image %s' % (self.name,))
2448 def mirror_image_get_info(self):
2450 Get mirror info for the image.
2452 :returns: dict - contains the following keys:
2454 * ``global_id`` (str) - image global id
2456 * ``state`` (int) - mirror state
2458 * ``primary`` (bool) - is image primary
2460 cdef rbd_mirror_image_info_t c_info
2462 ret = rbd_mirror_image_get_info(self.image, &c_info, sizeof(c_info))
2464 raise make_ex(ret, 'error getting mirror info for image %s' %
2467 'global_id' : decode_cstr(c_info.global_id),
2468 'state' : int(c_info.state),
2469 'primary' : c_info.primary,
2471 free(c_info.global_id)
2474 def mirror_image_get_status(self):
2476 Get mirror status for the image.
2478 :returns: dict - contains the following keys:
2480 * ``name`` (str) - mirror image name
2482 * `info` (dict) - mirror image info
2484 * ``state`` (int) - status mirror state
2486 * ``description`` (str) - status description
2488 * ``last_update`` (datetime) - last status update time
2490 * ``up`` (bool) - is mirroring agent up
2492 cdef rbd_mirror_image_status_t c_status
2494 ret = rbd_mirror_image_get_status(self.image, &c_status,
2497 raise make_ex(ret, 'error getting mirror status for image %s' %
2500 'name' : decode_cstr(c_status.name),
2502 'global_id' : decode_cstr(c_status.info.global_id),
2503 'state' : int(c_status.info.state),
2504 'primary' : c_status.info.primary,
2506 'state' : c_status.state,
2507 'description' : decode_cstr(c_status.description),
2508 'last_update' : datetime.fromtimestamp(c_status.last_update),
2512 free(c_status.info.global_id)
2513 free(c_status.description)
2516 def aio_read(self, offset, length, oncomplete, fadvise_flags=0):
2518 Asynchronously read data from the image
2520 Raises :class:`InvalidArgument` if part of the range specified is
2523 oncomplete will be called with the returned read value as
2524 well as the completion:
2526 oncomplete(completion, data_read)
2528 :param offset: the offset to start reading at
2530 :param length: how many bytes to read
2532 :param oncomplete: what to do when the read is complete
2533 :type oncomplete: completion
2534 :param fadvise_flags: fadvise flags for this read
2535 :type fadvise_flags: int
2536 :returns: :class:`Completion` - the completion object
2537 :raises: :class:`InvalidArgument`, :class:`IOError`
2542 uint64_t _offset = offset
2543 size_t _length = length
2544 int _fadvise_flags = fadvise_flags
2545 Completion completion
2547 def oncomplete_(completion_v):
2548 cdef Completion _completion_v = completion_v
2549 return_value = _completion_v.get_return_value()
2550 if return_value > 0 and return_value != length:
2551 _PyBytes_Resize(&_completion_v.buf, return_value)
2552 return oncomplete(_completion_v, <object>_completion_v.buf if return_value >= 0 else None)
2554 completion = self.__get_completion(oncomplete_)
2555 completion.buf = PyBytes_FromStringAndSize(NULL, length)
2556 ret_buf = PyBytes_AsString(completion.buf)
2558 completion.__persist()
2560 ret = rbd_aio_read2(self.image, _offset, _length, ret_buf,
2561 completion.rbd_comp, _fadvise_flags)
2563 raise make_ex(ret, 'error reading %s %ld~%ld' %
2564 (self.name, offset, length))
2566 completion.__unpersist()
2571 def aio_write(self, data, offset, oncomplete, fadvise_flags=0):
2573 Asynchronously write data to the image
2575 Raises :class:`InvalidArgument` if part of the write would fall outside
2578 oncomplete will be called with the completion:
2580 oncomplete(completion)
2582 :param data: the data to be written
2584 :param offset: the offset to start writing at
2586 :param oncomplete: what to do when the write is complete
2587 :type oncomplete: completion
2588 :param fadvise_flags: fadvise flags for this write
2589 :type fadvise_flags: int
2590 :returns: :class:`Completion` - the completion object
2591 :raises: :class:`InvalidArgument`, :class:`IOError`
2595 uint64_t _offset = offset
2597 size_t _length = len(data)
2598 int _fadvise_flags = fadvise_flags
2599 Completion completion
2601 completion = self.__get_completion(oncomplete)
2603 completion.__persist()
2605 ret = rbd_aio_write2(self.image, _offset, _length, _data,
2606 completion.rbd_comp, _fadvise_flags)
2608 raise make_ex(ret, 'error writing %s %ld~%ld' %
2609 (self.name, offset, _length))
2611 completion.__unpersist()
2616 def aio_discard(self, offset, length, oncomplete):
2618 Asynchronously trim the range from the image. It will be logically
2623 uint64_t _offset = offset
2624 size_t _length = length
2625 Completion completion
2627 completion = self.__get_completion(oncomplete)
2629 completion.__persist()
2631 ret = rbd_aio_discard(self.image, _offset, _length,
2632 completion.rbd_comp)
2634 raise make_ex(ret, 'error discarding %s %ld~%ld' %
2635 (self.name, offset, _length))
2637 completion.__unpersist()
2642 def aio_flush(self, oncomplete):
2644 Asyncronously wait until all writes are fully flushed if caching is
2648 cdef Completion completion = self.__get_completion(oncomplete)
2650 completion.__persist()
2652 ret = rbd_aio_flush(self.image, completion.rbd_comp)
2654 raise make_ex(ret, 'error flushing')
2656 completion.__unpersist()
2661 def metadata_get(self, key):
2663 Get image metadata for the given key.
2665 :param key: metadata key
2667 :returns: str - image id
2669 key = cstr(key, 'key')
2677 value = <char *>realloc_chk(value, size)
2679 ret = rbd_metadata_get(self.image, _key, value, &size)
2680 if ret != -errno.ERANGE:
2683 raise make_ex(ret, 'error getting metadata %s for image %s' %
2684 (self.key, self.name,))
2685 return decode_cstr(value)
2689 def metadata_set(self, key, value):
2691 Set image metadata for the given key.
2693 :param key: metadata key
2695 :param value: metadata value
2698 key = cstr(key, 'key')
2699 value = cstr(value, 'value')
2702 char *_value = value
2704 ret = rbd_metadata_set(self.image, _key, _value)
2707 raise make_ex(ret, 'error setting metadata %s for image %s' %
2708 (self.key, self.name,))
2711 def metadata_remove(self, key):
2713 Remove image metadata for the given key.
2715 :param key: metadata key
2718 key = cstr(key, 'key')
2722 ret = rbd_metadata_remove(self.image, _key)
2725 raise make_ex(ret, 'error removing metadata %s for image %s' %
2726 (self.key, self.name,))
2728 def metadata_list(self):
2730 List image metadata.
2732 :returns: :class:`MetadataIterator`
2734 return MetadataIterator(self)
2736 cdef class LockOwnerIterator(object):
2738 Iterator over managed lock owners for an image
2740 Yields a dictionary containing information about the image's lock
2744 * ``mode`` (int) - active lock mode
2746 * ``owner`` (str) - lock owner name
2750 rbd_lock_mode_t lock_mode
2752 size_t num_lock_owners
2755 def __init__(self, Image image):
2757 self.lock_owners = NULL
2758 self.num_lock_owners = 8
2760 self.lock_owners = <char**>realloc_chk(self.lock_owners,
2761 self.num_lock_owners *
2764 ret = rbd_lock_get_owners(image.image, &self.lock_mode,
2766 &self.num_lock_owners)
2769 elif ret != -errno.ERANGE:
2770 raise make_ex(ret, 'error listing lock owners for image %s' % (image.name,))
2773 for i in range(self.num_lock_owners):
2775 'mode' : int(self.lock_mode),
2776 'owner' : decode_cstr(self.lock_owners[i]),
2779 def __dealloc__(self):
2780 if self.lock_owners:
2781 rbd_lock_get_owners_cleanup(self.lock_owners, self.num_lock_owners)
2782 free(self.lock_owners)
2784 cdef class MetadataIterator(object):
2786 Iterator over metadata list for an image.
2788 Yields ``(key, value)`` tuple.
2790 * ``key`` (str) - metadata key
2791 * ``value`` (str) - metadata value
2801 def __init__(self, Image image):
2802 self.image_name = image.name
2803 self.image = image.image
2804 self.last_read = strdup("")
2806 self.get_next_chunk()
2809 while len(self.next_chunk) > 0:
2810 for pair in self.next_chunk:
2812 if len(self.next_chunk) < self.max_read:
2814 self.get_next_chunk()
2816 def __dealloc__(self):
2818 free(self.last_read)
2820 def get_next_chunk(self):
2823 size_t keys_size = 4096
2825 size_t vals_size = 4096
2828 c_keys = <char *>realloc_chk(c_keys, keys_size)
2829 c_vals = <char *>realloc_chk(c_vals, vals_size)
2831 ret = rbd_metadata_list(self.image, self.last_read,
2832 self.max_read, c_keys, &keys_size,
2836 elif ret != -errno.ERANGE:
2837 raise make_ex(ret, 'error listing metadata for image %s' %
2839 keys = [decode_cstr(key) for key in
2840 c_keys[:keys_size].split(b'\0') if key]
2841 vals = [decode_cstr(val) for val in
2842 c_vals[:vals_size].split(b'\0') if val]
2844 free(self.last_read)
2845 self.last_read = strdup(keys[-1])
2846 self.next_chunk = zip(keys, vals)
2851 cdef class SnapIterator(object):
2853 Iterator over snapshot info for an image.
2855 Yields a dictionary containing information about a snapshot.
2859 * ``id`` (int) - numeric identifier of the snapshot
2861 * ``size`` (int) - size of the image at the time of snapshot (in bytes)
2863 * ``name`` (str) - name of the snapshot
2866 cdef rbd_snap_info_t *snaps
2870 def __init__(self, Image image):
2875 self.snaps = <rbd_snap_info_t*>realloc_chk(self.snaps,
2877 sizeof(rbd_snap_info_t))
2879 ret = rbd_snap_list(image.image, self.snaps, &self.num_snaps)
2881 self.num_snaps = ret
2883 elif ret != -errno.ERANGE:
2884 raise make_ex(ret, 'error listing snapshots for image %s' % (image.name,))
2887 for i in range(self.num_snaps):
2889 'id' : self.snaps[i].id,
2890 'size' : self.snaps[i].size,
2891 'name' : decode_cstr(self.snaps[i].name),
2894 def __dealloc__(self):
2896 rbd_snap_list_end(self.snaps)
2899 cdef class TrashIterator(object):
2901 Iterator over trash entries.
2903 Yields a dictionary containing trash info of an image.
2907 * `id` (str) - image id
2909 * `name` (str) - image name
2911 * `source` (str) - source of deletion
2913 * `deletion_time` (datetime) - time of deletion
2915 * `deferment_end_time` (datetime) - time that an image is allowed to be
2922 rbd_trash_image_info_t *entries
2924 def __init__(self, ioctx):
2925 self.ioctx = convert_ioctx(ioctx)
2926 self.num_entries = 1024
2929 self.entries = <rbd_trash_image_info_t*>realloc_chk(self.entries,
2931 sizeof(rbd_trash_image_info_t))
2933 ret = rbd_trash_list(self.ioctx, self.entries, &self.num_entries)
2935 self.num_entries = ret
2937 elif ret != -errno.ERANGE:
2938 raise make_ex(ret, 'error listing trash entries')
2940 __source_string = ['USER', 'MIRRORING']
2943 for i in range(self.num_entries):
2945 'id' : decode_cstr(self.entries[i].id),
2946 'name' : decode_cstr(self.entries[i].name),
2947 'source' : TrashIterator.__source_string[self.entries[i].source],
2948 'deletion_time' : datetime.fromtimestamp(self.entries[i].deletion_time),
2949 'deferment_end_time' : datetime.fromtimestamp(self.entries[i].deferment_end_time)
2952 def __dealloc__(self):
2953 rbd_trash_list_cleanup(self.entries, self.num_entries)