]>
git.proxmox.com Git - ceph.git/blob - ceph/src/os/ObjectStore.h
1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
2 // vim: ts=8 sw=2 smarttab
4 * Ceph - scalable distributed file system
6 * Copyright (C) 2004-2006 Sage Weil <sage@newdream.net>
8 * This is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License version 2.1, as published by the Free Software
11 * Foundation. See file COPYING.
14 #ifndef CEPH_OBJECTSTORE_H
15 #define CEPH_OBJECTSTORE_H
17 #include "include/common_fwd.h"
18 #include "include/Context.h"
19 #include "include/buffer.h"
20 #include "include/types.h"
21 #include "include/stringify.h"
22 #include "osd/osd_types.h"
23 #include "common/TrackedOp.h"
24 #include "common/WorkQueue.h"
25 #include "ObjectMap.h"
26 #include "os/Transaction.h"
33 #if defined(__APPLE__) || defined(__FreeBSD__) || defined(__sun)
34 #include <sys/statvfs.h>
36 #include <sys/vfs.h> /* or <sys/statfs.h> */
44 * low-level interface to the local OSD file system
50 static inline void encode(const std::map
<std::string
,ceph::buffer::ptr
> *attrset
, ceph::buffer::list
&bl
) {
56 typedef uint32_t osflagbits_t
;
57 const int SKIP_JOURNAL_REPLAY
= 1 << 0;
58 const int SKIP_MOUNT_OMAP
= 1 << 1;
65 using Transaction
= ceph::os::Transaction
;
69 * create - create an ObjectStore instance.
71 * This is invoked once at initialization time.
73 * @param type type of store. This is a std::string from the configuration file.
74 * @param data path (or other descriptor) for data
75 * @param journal path (or other descriptor) for journal (optional)
76 * @param flags which filestores should check if applicable
78 static ObjectStore
*create(CephContext
*cct
,
79 const std::string
& type
,
80 const std::string
& data
,
81 const std::string
& journal
,
82 osflagbits_t flags
= 0);
85 * probe a block device to learn the uuid of the owning OSD
88 * @param path path to device
89 * @param fsid [out] osd uuid
91 static int probe_block_device_fsid(
93 const std::string
& path
,
97 * Fetch Object Store statistics.
99 * Currently only latency of write and apply times are measured.
101 * This appears to be called with nothing locked.
103 virtual objectstore_perf_stat_t
get_cur_stats() = 0;
106 * Fetch Object Store performance counters.
109 * This appears to be called with nothing locked.
111 virtual const PerfCounters
* get_perf_counters() const = 0;
114 * a collection also orders transactions
116 * Any transactions queued under a given collection will be applied in
117 * sequence. Transactions queued under different collections may run
120 * ObjectStore users may get collection handles with open_collection() (or,
121 * for bootstrapping a new collection, create_new_collection()).
123 struct CollectionImpl
: public RefCountedObject
{
126 /// wait for any queued transactions to apply
127 // block until any previous transactions are visible. specifically,
128 // collection_list and collection_empty need to reflect prior operations.
129 virtual void flush() = 0;
134 * There are two cases:
135 * 1) collection is currently idle: the method returns true. c is
137 * 2) collection is not idle: the method returns false and c is
138 * called asynchronously with a value of 0 once all transactions
139 * queued on this collection prior to the call have been applied
142 virtual bool flush_commit(Context
*c
) = 0;
144 const coll_t
&get_cid() {
148 CollectionImpl() = delete;
149 CollectionImpl(CephContext
* cct
, const coll_t
& c
) : RefCountedObject(cct
), cid(c
) {}
150 ~CollectionImpl() = default;
152 using CollectionHandle
= ceph::ref_t
<CollectionImpl
>;
155 /*********************************
157 * Object Contents and semantics
159 * All ObjectStore objects are identified as a named object
160 * (ghobject_t and hobject_t) in a named collection (coll_t).
161 * ObjectStore operations support the creation, mutation, deletion
162 * and enumeration of objects within a collection. Enumeration is
163 * in sorted key order (where keys are sorted by hash). Object names
164 * are globally unique.
166 * Each object has four distinct parts: byte data, xattrs, omap_header
169 * The data portion of an object is conceptually equivalent to a
170 * file in a file system. Random and Partial access for both read
171 * and write operations is required. The ability to have a sparse
172 * implementation of the data portion of an object is beneficial for
173 * some workloads, but not required. There is a system-wide limit on
174 * the maximum size of an object, which is typically around 100 MB.
176 * Xattrs are equivalent to the extended attributes of file
177 * systems. Xattrs are a std::set of key/value pairs. Sub-value access
178 * is not required. It is possible to enumerate the std::set of xattrs in
179 * key order. At the implementation level, xattrs are used
180 * exclusively internal to Ceph and the implementer can expect the
181 * total size of all of the xattrs on an object to be relatively
182 * small, i.e., less than 64KB. Much of Ceph assumes that accessing
183 * xattrs on temporally adjacent object accesses (recent past or
184 * near future) is inexpensive.
186 * omap_header is a single blob of data. It can be read or written
189 * Omap entries are conceptually the same as xattrs
190 * but in a different address space. In other words, you can have
191 * the same key as an xattr and an omap entry and they have distinct
192 * values. Enumeration of xattrs doesn't include omap entries and
193 * vice versa. The size and access characteristics of omap entries
194 * are very different from xattrs. In particular, the value portion
195 * of an omap entry can be quite large (MBs). More importantly, the
196 * interface must support efficient range queries on omap entries even
197 * when there are a large numbers of entries.
199 *********************************/
201 /*******************************
205 * A collection is simply a grouping of objects. Collections have
206 * names (coll_t) and can be enumerated in order. Like an
207 * individual object, a collection also has a std::set of xattrs.
213 int queue_transaction(CollectionHandle
& ch
,
215 TrackedOpRef op
= TrackedOpRef(),
216 ThreadPool::TPHandle
*handle
= NULL
) {
217 std::vector
<Transaction
> tls
;
218 tls
.push_back(std::move(t
));
219 return queue_transactions(ch
, tls
, op
, handle
);
222 virtual int queue_transactions(
223 CollectionHandle
& ch
, std::vector
<Transaction
>& tls
,
224 TrackedOpRef op
= TrackedOpRef(),
225 ThreadPool::TPHandle
*handle
= NULL
) = 0;
229 ObjectStore(CephContext
* cct
,
230 const std::string
& path_
) : path(path_
), cct(cct
) {}
231 virtual ~ObjectStore() {}
234 explicit ObjectStore(const ObjectStore
& o
) = delete;
235 const ObjectStore
& operator=(const ObjectStore
& o
) = delete;
238 virtual int upgrade() {
242 virtual void get_db_statistics(ceph::Formatter
*f
) { }
243 virtual void generate_db_histogram(ceph::Formatter
*f
) { }
244 virtual int flush_cache(std::ostream
*os
= NULL
) { return -1; }
245 virtual void dump_perf_counters(ceph::Formatter
*f
) {}
246 virtual void dump_cache_stats(ceph::Formatter
*f
) {}
247 virtual void dump_cache_stats(std::ostream
& os
) {}
249 virtual std::string
get_type() = 0;
252 virtual bool test_mount_in_use() = 0;
253 virtual int mount() = 0;
254 virtual int umount() = 0;
255 virtual int fsck(bool deep
) {
258 virtual int repair(bool deep
) {
261 virtual int quick_fix() {
265 virtual void set_cache_shards(unsigned num
) { }
268 * Returns 0 if the hobject is valid, -error otherwise
271 * -ENAMETOOLONG: locator/namespace/name too large
273 virtual int validate_hobject_key(const hobject_t
&obj
) const = 0;
275 virtual unsigned get_max_attr_name_length() = 0;
276 virtual int mkfs() = 0; // wipe
277 virtual int mkjournal() = 0; // journal only
278 virtual bool needs_journal() = 0; //< requires a journal
279 virtual bool wants_journal() = 0; //< prefers a journal
280 virtual bool allows_journal() = 0; //< allows a journal
282 // return store min allocation size, if applicable
283 virtual uint64_t get_min_alloc_size() const {
287 /// enumerate hardware devices (by 'devname', e.g., 'sda' as in /sys/block/sda)
288 virtual int get_devices(std::set
<std::string
> *devls
) {
292 /// true if a txn is readable immediately after it is queued.
293 virtual bool is_sync_onreadable() const {
300 * Check whether store is backed by a rotational (HDD) or non-rotational
303 * This must be usable *before* the store is mounted.
305 * @return true for HDD, false for SSD
307 virtual bool is_rotational() {
312 * is_journal_rotational
314 * Check whether journal is backed by a rotational (HDD) or non-rotational
318 * @return true for HDD, false for SSD
320 virtual bool is_journal_rotational() {
324 virtual std::string
get_default_device_class() {
325 return is_rotational() ? "hdd" : "ssd";
328 virtual int get_numa_node(
330 std::set
<int> *nodes
,
331 std::set
<std::string
> *failed
) {
336 virtual bool can_sort_nibblewise() {
337 return false; // assume a backend cannot, unless it says otherwise
340 virtual int statfs(struct store_statfs_t
*buf
,
341 osd_alert_list_t
* alerts
= nullptr) = 0;
342 virtual int pool_statfs(uint64_t pool_id
, struct store_statfs_t
*buf
,
343 bool *per_pool_omap
) = 0;
345 virtual void collect_metadata(std::map
<std::string
,string
> *pm
) { }
348 * write_meta - write a simple configuration key out-of-band
350 * Write a simple key/value pair for basic store configuration
351 * (e.g., a uuid or magic number) to an unopened/unmounted store.
352 * The default implementation writes this to a plaintext file in the
355 * A newline is appended.
357 * @param key key name (e.g., "fsid")
358 * @param value value (e.g., a uuid rendered as a std::string)
359 * @returns 0 for success, or an error code
361 virtual int write_meta(const std::string
& key
,
362 const std::string
& value
);
365 * read_meta - read a simple configuration key out-of-band
367 * Read a simple key value to an unopened/mounted store.
369 * Trailing whitespace is stripped off.
371 * @param key key name
372 * @param value pointer to value std::string
373 * @returns 0 for success, or an error code
375 virtual int read_meta(const std::string
& key
,
379 * get ideal max value for collection_list()
381 * default to some arbitrary values; the implementation will override.
383 virtual int get_ideal_list_max() { return 64; }
387 * get a collection handle
389 * Provide a trivial handle as a default to avoid converting legacy
392 virtual CollectionHandle
open_collection(const coll_t
&cid
) = 0;
395 * get a collection handle for a soon-to-be-created collection
397 * This handle must be used by queue_transaction that includes a
398 * create_collection call in order to become valid. It will become the
399 * reference to the created collection.
401 virtual CollectionHandle
create_new_collection(const coll_t
&cid
) = 0;
404 * std::set ContextQueue for a collection
406 * After that, oncommits of Transaction will queue into commit_queue.
407 * And osd ShardThread will call oncommits.
409 virtual void set_collection_commit_queue(const coll_t
&cid
, ContextQueue
*commit_queue
) = 0;
412 * Synchronous read operations
416 * exists -- Test for existance of object
418 * @param cid collection for object
419 * @param oid oid of object
420 * @returns true if object exists, false otherwise
422 virtual bool exists(CollectionHandle
& c
, const ghobject_t
& oid
) = 0;
424 * set_collection_opts -- std::set pool options for a collectioninformation for an object
426 * @param cid collection
427 * @param opts new collection options
428 * @returns 0 on success, negative error code on failure.
430 virtual int set_collection_opts(
432 const pool_opts_t
& opts
) = 0;
435 * stat -- get information for an object
437 * @param cid collection for object
438 * @param oid oid of object
439 * @param st output information for the object
440 * @param allow_eio if false, assert on -EIO operation failure
441 * @returns 0 on success, negative error code on failure.
445 const ghobject_t
& oid
,
447 bool allow_eio
= false) = 0;
449 * read -- read a byte range of data from an object
451 * Note: if reading from an offset past the end of the object, we
452 * return 0 (not, say, -EINVAL).
454 * @param cid collection for object
455 * @param oid oid of object
456 * @param offset location offset of first byte to be read
457 * @param len number of bytes to be read
458 * @param bl output ceph::buffer::list
459 * @param op_flags is CEPH_OSD_OP_FLAG_*
460 * @returns number of bytes read on success, or negative error code on failure.
464 const ghobject_t
& oid
,
467 ceph::buffer::list
& bl
,
468 uint32_t op_flags
= 0) = 0;
471 * fiemap -- get extent std::map of data of an object
473 * Returns an encoded std::map of the extents of an object's data portion
474 * (std::map<offset,size>).
476 * A non-enlightened implementation is free to return the extent (offset, len)
477 * as the sole extent.
479 * @param cid collection for object
480 * @param oid oid of object
481 * @param offset location offset of first byte to be read
482 * @param len number of bytes to be read
483 * @param bl output ceph::buffer::list for extent std::map information.
484 * @returns 0 on success, negative error code on failure.
486 virtual int fiemap(CollectionHandle
& c
, const ghobject_t
& oid
,
487 uint64_t offset
, size_t len
, ceph::buffer::list
& bl
) = 0;
488 virtual int fiemap(CollectionHandle
& c
, const ghobject_t
& oid
,
489 uint64_t offset
, size_t len
, std::map
<uint64_t, uint64_t>& destmap
) = 0;
492 * readv -- read specfic intervals from an object;
493 * caller must call fiemap to fill in the extent-map first.
495 * Note: if reading from an offset past the end of the object, we
496 * return 0 (not, say, -EINVAL). Also the default version of readv
497 * reads each extent separately synchronously, which can become horribly
498 * inefficient if the physical layout of the pushing object get massively
499 * fragmented and hence should be overridden by any real os that
500 * cares about the performance..
502 * @param cid collection for object
503 * @param oid oid of object
504 * @param m intervals to be read
505 * @param bl output ceph::buffer::list
506 * @param op_flags is CEPH_OSD_OP_FLAG_*
507 * @returns number of bytes read on success, or negative error code on failure.
511 const ghobject_t
& oid
,
512 interval_set
<uint64_t>& m
,
513 ceph::buffer::list
& bl
,
514 uint32_t op_flags
= 0) {
516 for (auto p
= m
.begin(); p
!= m
.end(); p
++) {
518 int r
= read(c
, oid
, p
.get_start(), p
.get_len(), t
, op_flags
);
522 // prune fiemap, if necessary
523 if (p
.get_len() != t
.length()) {
525 if (t
.length() == 0) {
526 m
.erase(save
); // Remove this empty interval
528 save
.set_len(t
.length()); // fix interval length
531 // Remove any other follow-up intervals present too
532 while (p
!= m
.end()) {
544 * dump_onode -- dumps onode metadata in human readable form,
545 intended primiarily for debugging
547 * @param cid collection for object
548 * @param oid oid of object
549 * @param section_name section name to create and print under
550 * @param f Formatter class instance to print to
551 * @returns 0 on success, negative error code on failure.
553 virtual int dump_onode(
555 const ghobject_t
& oid
,
556 const string
& section_name
,
562 * getattr -- get an xattr of an object
564 * @param cid collection for object
565 * @param oid oid of object
566 * @param name name of attr to read
567 * @param value place to put output result.
568 * @returns 0 on success, negative error code on failure.
570 virtual int getattr(CollectionHandle
&c
, const ghobject_t
& oid
,
571 const char *name
, ceph::buffer::ptr
& value
) = 0;
574 * getattr -- get an xattr of an object
576 * @param cid collection for object
577 * @param oid oid of object
578 * @param name name of attr to read
579 * @param value place to put output result.
580 * @returns 0 on success, negative error code on failure.
583 CollectionHandle
&c
, const ghobject_t
& oid
,
584 const std::string
& name
, ceph::buffer::list
& value
) {
585 ceph::buffer::ptr bp
;
586 int r
= getattr(c
, oid
, name
.c_str(), bp
);
592 * getattrs -- get all of the xattrs of an object
594 * @param cid collection for object
595 * @param oid oid of object
596 * @param aset place to put output result.
597 * @returns 0 on success, negative error code on failure.
599 virtual int getattrs(CollectionHandle
&c
, const ghobject_t
& oid
,
600 std::map
<std::string
,ceph::buffer::ptr
>& aset
) = 0;
603 * getattrs -- get all of the xattrs of an object
605 * @param cid collection for object
606 * @param oid oid of object
607 * @param aset place to put output result.
608 * @returns 0 on success, negative error code on failure.
610 int getattrs(CollectionHandle
&c
, const ghobject_t
& oid
,
611 std::map
<std::string
,ceph::buffer::list
>& aset
) {
612 std::map
<std::string
,ceph::buffer::ptr
> bmap
;
613 int r
= getattrs(c
, oid
, bmap
);
614 for (auto i
= bmap
.begin(); i
!= bmap
.end(); ++i
) {
615 aset
[i
->first
].append(i
->second
);
624 * list_collections -- get all of the collections known to this ObjectStore
626 * @param ls std::list of the collections in sorted order.
627 * @returns 0 on success, negative error code on failure.
629 virtual int list_collections(std::vector
<coll_t
>& ls
) = 0;
632 * does a collection exist?
634 * @param c collection
635 * @returns true if it exists, false otherwise
637 virtual bool collection_exists(const coll_t
& c
) = 0;
640 * is a collection empty?
642 * @param c collection
643 * @param empty true if the specified collection is empty, false otherwise
644 * @returns 0 on success, negative error code on failure.
646 virtual int collection_empty(CollectionHandle
& c
, bool *empty
) = 0;
649 * return the number of significant bits of the coll_t::pgid.
651 * This should return what the last create_collection or split_collection
652 * std::set. A legacy backend may return -EAGAIN if the value is unavailable
653 * (because we upgraded from an older version, e.g., FileStore).
655 virtual int collection_bits(CollectionHandle
& c
) = 0;
659 * std::list contents of a collection that fall in the range [start, end) and no more than a specified many result
661 * @param c collection
662 * @param start list object that sort >= this value
663 * @param end list objects that sort < this value
664 * @param max return no more than this many results
665 * @param seq return no objects with snap < seq
666 * @param ls [out] result
667 * @param next [out] next item sorts >= this value
668 * @return zero on success, or negative error
670 virtual int collection_list(CollectionHandle
&c
,
671 const ghobject_t
& start
, const ghobject_t
& end
,
673 std::vector
<ghobject_t
> *ls
, ghobject_t
*next
) = 0;
675 virtual int collection_list_legacy(CollectionHandle
&c
,
676 const ghobject_t
& start
,
677 const ghobject_t
& end
, int max
,
678 std::vector
<ghobject_t
> *ls
,
680 return collection_list(c
, start
, end
, max
, ls
, next
);
684 /// Get omap contents
685 virtual int omap_get(
686 CollectionHandle
&c
, ///< [in] Collection containing oid
687 const ghobject_t
&oid
, ///< [in] Object containing omap
688 ceph::buffer::list
*header
, ///< [out] omap header
689 std::map
<std::string
, ceph::buffer::list
> *out
/// < [out] Key to value std::map
693 virtual int omap_get_header(
694 CollectionHandle
&c
, ///< [in] Collection containing oid
695 const ghobject_t
&oid
, ///< [in] Object containing omap
696 ceph::buffer::list
*header
, ///< [out] omap header
697 bool allow_eio
= false ///< [in] don't assert on eio
700 /// Get keys defined on oid
701 virtual int omap_get_keys(
702 CollectionHandle
&c
, ///< [in] Collection containing oid
703 const ghobject_t
&oid
, ///< [in] Object containing omap
704 std::set
<std::string
> *keys
///< [out] Keys defined on oid
708 virtual int omap_get_values(
709 CollectionHandle
&c
, ///< [in] Collection containing oid
710 const ghobject_t
&oid
, ///< [in] Object containing omap
711 const std::set
<std::string
> &keys
, ///< [in] Keys to get
712 std::map
<std::string
, ceph::buffer::list
> *out
///< [out] Returned keys and values
716 virtual int omap_get_values(
717 CollectionHandle
&c
, ///< [in] Collection containing oid
718 const ghobject_t
&oid
, ///< [in] Object containing omap
719 const std::optional
<std::string
> &start_after
, ///< [in] Keys to get
720 std::map
<std::string
, ceph::buffer::list
> *out
///< [out] Returned keys and values
724 /// Filters keys into out which are defined on oid
725 virtual int omap_check_keys(
726 CollectionHandle
&c
, ///< [in] Collection containing oid
727 const ghobject_t
&oid
, ///< [in] Object containing omap
728 const std::set
<std::string
> &keys
, ///< [in] Keys to check
729 std::set
<std::string
> *out
///< [out] Subset of keys defined on oid
733 * Returns an object map iterator
735 * Warning! The returned iterator is an implicit lock on filestore
736 * operations in c. Do not use filestore methods on c while the returned
737 * iterator is live. (Filling in a transaction is no problem).
739 * @return iterator, null on error
741 virtual ObjectMap::ObjectMapIterator
get_omap_iterator(
742 CollectionHandle
&c
, ///< [in] collection
743 const ghobject_t
&oid
///< [in] object
746 virtual int flush_journal() { return -EOPNOTSUPP
; }
748 virtual int dump_journal(std::ostream
& out
) { return -EOPNOTSUPP
; }
750 virtual int snapshot(const std::string
& name
) { return -EOPNOTSUPP
; }
753 * Set and get internal fsid for this instance. No external data is modified
755 virtual void set_fsid(uuid_d u
) = 0;
756 virtual uuid_d
get_fsid() = 0;
759 * Estimates additional disk space used by the specified amount of objects and caused by file allocation granularity and metadata store
760 * - num objects - total (including witeouts) object count to measure used space for.
762 virtual uint64_t estimate_objects_overhead(uint64_t num_objects
) = 0;
766 virtual void inject_data_error(const ghobject_t
&oid
) {}
767 virtual void inject_mdata_error(const ghobject_t
&oid
) {}
769 virtual void compact() {}
770 virtual bool has_builtin_csum() const {