osl.h.in

   1 /*
   2  * Copyright (C) 2007-2008 Andre Noll <maan@systemlinux.org>
   3  *
   4  * Licensed under the GPL v2. For licencing details see COPYING.
   5  */
   6
   7 /** \file osl.h User interface for the object storage layer. */
   8
   9 #include <sys/mman.h>
  10
  11 /** Export all declarations in this file. */
  12 #pragma GCC visibility push(default)
  13
  14 /** Describes an object of the object storage layer (osl) */
  15 struct osl_object {
  16         /** Pointer to the data of the object. */
  17         void *data;
  18         /** The object's size. */
  19         size_t size;
  20 };
  21
  22 /** Flags that change the internal handling of osl tables. */
  23 enum osl_table_flags {
  24         /** This table will have many rows. */
  25         OSL_LARGE_TABLE = 1
  26 };
  27
  28 /** The three different types of storage for an osl column */
  29 enum osl_storage_type {
  30         /**
  31          * All data for this column is stored in one file which gets mmapped by
  32          * osl_open_table(). This is suitable for columns that do not hold much
  33          * data.
  34          */
  35         OSL_MAPPED_STORAGE,
  36         /**
  37          * Each entry is stored on disk and is loaded on demand by
  38          * open_disk_object(). This is the preferable storage type for large
  39          * objects that need not be in memory all the time.
  40          */
  41          OSL_DISK_STORAGE,
  42         /**
  43          * Objects for columns of this type are volatile: They are only stored
  44          * in memory and are discarded once the table gets closed.
  45          */
  46         OSL_NO_STORAGE
  47 };
  48
  49 /**
  50  * Additional per-column flags
  51  */
  52 enum osl_storage_flags {
  53         /**
  54          * Build an rbtree for this column. This is only possible if the
  55          * storage type of the column is either \a OSL_MAPPED_STORAGE or \a
  56          * OSL_NO_STORAGE. In order to lookup objects in the table by using \a
  57          * osl_get_row(), the lookup column must have an associated rbtree.
  58          *
  59          * \sa osl_storage_type, osl_get_row()
  60          */
  61         OSL_RBTREE = 1,
  62         /** The data for this column will have constant size. */
  63         OSL_FIXED_SIZE = 2,
  64         /** All values of this column will be different. */
  65         OSL_UNIQUE = 4,
  66         /** Do not free the data for this column (\p OSL_NO_STORAGE). */
  67         OSL_DONT_FREE = 8
  68 };
  69
  70 /** Opaque osl table structure. */
  71 struct osl_table;
  72 /** Opaque osl row structure. */
  73 struct osl_row;
  74
  75 /**
  76  * In order to build up an rbtree a compare function for the objects must be
  77  * specified. Such a function always takes pointers to the two objects to be
  78  * compared. It must return -1, zero, or 1, if the first argument is considered
  79  * to  be  respectively less than, equal to, or greater than the second. If two
  80  * members compare as equal, their order in the sorted array is undefined.
  81  */
  82 typedef int osl_compare_func(const struct osl_object *obj1,
  83         const struct osl_object *obj2);
  84
  85 /**
  86  * The osl_rbreee_loop functions take a function pointer of this type. For each
  87  * node in the rbtree, the given function is called.
  88  *
  89  * \sa osl_rbtree_loop(), osl_rbtree_loop_reverse().
  90  */
  91 typedef int osl_rbtree_loop_func(struct osl_row *row, void *data);
  92
  93 /**
  94  * Describes one column of a osl table.
  95  */
  96 struct osl_column_description {
  97         /** One of the tree possible types of storage */
  98         enum osl_storage_type storage_type;
  99         /** Specifies further properties of the column */
 100         enum osl_storage_flags storage_flags;
 101         /**
 102          * The column name determines the name of the directory where all data
 103          * for this column will be stored. Its hash is stored in the table
 104          * header. This field is ignored if the storage type is \a NO_STORAGE
 105          */
 106         char *name;
 107         /**
 108          * For columns with an associated rbtree, this must point to a function
 109          * that compares the values of two objects, either a built-in function
 110          * or a function defined by the application may be supplied.  This
 111          * field is ignored if the column does not have an associated rbtree.
 112          *
 113          * \sa osl_storage_flags, osl_compare_func
 114          */
 115         osl_compare_func *compare_function;
 116         /**
 117          * If the \a OSL_FIXED_SIZE flag is set for this column, this value
 118          * determines the fixed size of all objects of this column. It is
 119          * ignored, if \a OSL_FIXED_SIZE is not set.
 120          */
 121         uint32_t data_size;
 122 };
 123
 124 /**
 125  * Describes one osl table.
 126  */
 127 struct osl_table_description {
 128         /** The directory which contains all files of this table. */
 129         const char *dir;
 130         /**
 131          * The table name. A subdirectory of \a dir called \a name is created
 132          * at table creation time. It must be a valid name for a subdirectory.
 133          * In particular, no slashes are allowed for \a name.
 134          */
 135         const char *name;
 136         /** The number of columns of this table. */
 137         uint16_t num_columns;
 138         /** Further table-wide information. */
 139         enum osl_table_flags flags;
 140         /** The array describing the individual columns of the table. */
 141         struct osl_column_description *column_descriptions;
 142 };
 143
 144 /** Flags to be passed to \a osl_close_table(). */
 145 enum osl_close_flags {
 146         /**
 147          * The table header contains a "dirty" flag which specifies whether
 148          * the table is currently open by another process. This flag specifies
 149          * that the dirty flag should be cleared before closing the table.
 150          */
 151         OSL_MARK_CLEAN = 1,
 152         /**
 153          * If the table contains columns of type \a OSL_NO_STORAGE and this
 154          * flag is passed to osl_close_table(), free(3) is called for each
 155          * object of each column of type \a OSL_NO_STORAGE.
 156          */
 157         OSL_FREE_VOLATILE = 2
 158 };
 159
 160 int osl_create_table(const struct osl_table_description *desc);
 161 int osl_open_table(const struct osl_table_description *desc,
 162         struct osl_table **result);
 163 int osl_close_table(struct osl_table *t, enum osl_close_flags flags);
 164 int osl_get_row(const struct osl_table *t, unsigned col_num,
 165         const struct osl_object *obj, struct osl_row **result);
 166 int osl_get_object(const struct osl_table *t, const struct osl_row *row,
 167         unsigned col_num, struct osl_object *object);
 168 int osl_open_disk_object(const struct osl_table *t,
 169         const struct osl_row *r, unsigned col_num, struct osl_object *obj);
 170 int osl_close_disk_object(struct osl_object *obj);
 171 int osl_add_and_get_row(struct osl_table *t, struct osl_object *objects,
 172         struct osl_row **row);
 173 int osl_add_row(struct osl_table *t, struct osl_object *objects);
 174 int osl_del_row(struct osl_table *t, struct osl_row *row);
 175 int osl_rbtree_loop(const struct osl_table *t, unsigned col_num,
 176         void *private_data, osl_rbtree_loop_func *func);
 177 int osl_rbtree_loop_reverse(const struct osl_table *t, unsigned col_num,
 178         void *private_data, osl_rbtree_loop_func *func);
 179 int osl_update_object(struct osl_table *t, const struct osl_row *r,
 180         unsigned col_num, struct osl_object *obj);
 181 int osl_get_num_rows(const struct osl_table *t, unsigned *num_rows);
 182 int osl_rbtree_first_row(const struct osl_table *t, unsigned col_num,
 183         struct osl_row **result);
 184 int osl_rbtree_last_row(const struct osl_table *t, unsigned col_num,
 185         struct osl_row **result);
 186 int osl_get_nth_row(const struct osl_table *t, unsigned col_num,
 187         unsigned n, struct osl_row **result);
 188 int osl_get_rank(const struct osl_table *t, struct osl_row *r,
 189         unsigned col_num, unsigned *rank);
 190 int osl_hash_compare(const struct osl_object *obj1,
 191                 const struct osl_object *obj2);
 192 const char *osl_strerror(int nr);
 193
 194 #pragma GCC visibility pop