osl.h

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