drivers/md/persistent-data/dm-array.h

   1 /*
   2  * Copyright (C) 2012 Red Hat, Inc.
   3  *
   4  * This file is released under the GPL.
   5  */
   6 #ifndef _LINUX_DM_ARRAY_H
   7 #define _LINUX_DM_ARRAY_H
   8
   9 #include "dm-btree.h"
  10
  11 /*----------------------------------------------------------------*/
  12
  13 /*
  14  * The dm-array is a persistent version of an array.  It packs the data
  15  * more efficiently than a btree which will result in less disk space use,
  16  * and a performance boost.  The element get and set operations are still
  17  * O(ln(n)), but with a much smaller constant.
  18  *
  19  * The value type structure is reused from the btree type to support proper
  20  * reference counting of values.
  21  *
  22  * The arrays implicitly know their length, and bounds are checked for
  23  * lookups and updated.  It doesn't store this in an accessible place
  24  * because it would waste a whole metadata block.  Make sure you store the
  25  * size along with the array root in your encompassing data.
  26  *
  27  * Array entries are indexed via an unsigned integer starting from zero.
  28  * Arrays are not sparse; if you resize an array to have 'n' entries then
  29  * 'n - 1' will be the last valid index.
  30  *
  31  * Typical use:
  32  *
  33  * a) initialise a dm_array_info structure.  This describes the array
  34  *    values and ties it into a specific transaction manager.  It holds no
  35  *    instance data; the same info can be used for many similar arrays if
  36  *    you wish.
  37  *
  38  * b) Get yourself a root.  The root is the index of a block of data on the
  39  *    disk that holds a particular instance of an array.  You may have a
  40  *    pre existing root in your metadata that you wish to use, or you may
  41  *    want to create a brand new, empty array with dm_array_empty().
  42  *
  43  * Like the other data structures in this library, dm_array objects are
  44  * immutable between transactions.  Update functions will return you the
  45  * root for a _new_ array.  If you've incremented the old root, via
  46  * dm_tm_inc(), before calling the update function you may continue to use
  47  * it in parallel with the new root.
  48  *
  49  * c) resize an array with dm_array_resize().
  50  *
  51  * d) Get a value from the array with dm_array_get_value().
  52  *
  53  * e) Set a value in the array with dm_array_set_value().
  54  *
  55  * f) Walk an array of values in index order with dm_array_walk().  More
  56  *    efficient than making many calls to dm_array_get_value().
  57  *
  58  * g) Destroy the array with dm_array_del().  This tells the transaction
  59  *    manager that you're no longer using this data structure so it can
  60  *    recycle it's blocks.  (dm_array_dec() would be a better name for it,
  61  *    but del is in keeping with dm_btree_del()).
  62  */
  63
  64 /*
  65  * Describes an array.  Don't initialise this structure yourself, use the
  66  * init function below.
  67  */
  68 struct dm_array_info {
  69         struct dm_transaction_manager *tm;
  70         struct dm_btree_value_type value_type;
  71         struct dm_btree_info btree_info;
  72 };
  73
  74 /*
  75  * Sets up a dm_array_info structure.  You don't need to do anything with
  76  * this structure when you finish using it.
  77  *
  78  * info - the structure being filled in.
  79  * tm   - the transaction manager that should supervise this structure.
  80  * vt   - describes the leaf values.
  81  */
  82 void dm_array_info_init(struct dm_array_info *info,
  83                         struct dm_transaction_manager *tm,
  84                         struct dm_btree_value_type *vt);
  85
  86 /*
  87  * Create an empty, zero length array.
  88  *
  89  * info - describes the array
  90  * root - on success this will be filled out with the root block
  91  */
  92 int dm_array_empty(struct dm_array_info *info, dm_block_t *root);
  93
  94 /*
  95  * Resizes the array.
  96  *
  97  * info - describes the array
  98  * root - the root block of the array on disk
  99  * old_size - the caller is responsible for remembering the size of
 100  *            the array
 101  * new_size - can be bigger or smaller than old_size
 102  * value - if we're growing the array the new entries will have this value
 103  * new_root - on success, points to the new root block
 104  *
 105  * If growing the inc function for 'value' will be called the appropriate
 106  * number of times.  So if the caller is holding a reference they may want
 107  * to drop it.
 108  */
 109 int dm_array_resize(struct dm_array_info *info, dm_block_t root,
 110                     uint32_t old_size, uint32_t new_size,
 111                     const void *value, dm_block_t *new_root)
 112         __dm_written_to_disk(value);
 113
 114 /*
 115  * Frees a whole array.  The value_type's decrement operation will be called
 116  * for all values in the array
 117  */
 118 int dm_array_del(struct dm_array_info *info, dm_block_t root);
 119
 120 /*
 121  * Lookup a value in the array
 122  *
 123  * info - describes the array
 124  * root - root block of the array
 125  * index - array index
 126  * value - the value to be read.  Will be in on-disk format of course.
 127  *
 128  * -ENODATA will be returned if the index is out of bounds.
 129  */
 130 int dm_array_get_value(struct dm_array_info *info, dm_block_t root,
 131                        uint32_t index, void *value);
 132
 133 /*
 134  * Set an entry in the array.
 135  *
 136  * info - describes the array
 137  * root - root block of the array
 138  * index - array index
 139  * value - value to be written to disk.  Make sure you confirm the value is
 140  *         in on-disk format with__dm_bless_for_disk() before calling.
 141  * new_root - the new root block
 142  *
 143  * The old value being overwritten will be decremented, the new value
 144  * incremented.
 145  *
 146  * -ENODATA will be returned if the index is out of bounds.
 147  */
 148 int dm_array_set_value(struct dm_array_info *info, dm_block_t root,
 149                        uint32_t index, const void *value, dm_block_t *new_root)
 150         __dm_written_to_disk(value);
 151
 152 /*
 153  * Walk through all the entries in an array.
 154  *
 155  * info - describes the array
 156  * root - root block of the array
 157  * fn - called back for every element
 158  * context - passed to the callback
 159  */
 160 int dm_array_walk(struct dm_array_info *info, dm_block_t root,
 161                   int (*fn)(void *context, uint64_t key, void *leaf),
 162                   void *context);
 163
 164 /*----------------------------------------------------------------*/
 165
 166 #endif  /* _LINUX_DM_ARRAY_H */