osl.h

   1 #include <sys/mman.h>
   2 /*
   3  * Copyright (C) 2007 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 };
  63
  64 struct osl_table;
  65 struct osl_row;
  66
  67 /**
  68  * In order to build up an rbtree a compare function for the objects must be
  69  * specified. Such a function always takes pointers to the two objects to be
  70  * compared. It must return -1, zero, or 1, if the first argument is considered
  71  * to  be  respectively less than, equal to, or greater than the second. If two
  72  * members compare as equal, their order in the sorted array is undefined.
  73  */
  74 typedef int osl_compare_func(const struct osl_object *obj1,
  75         const struct osl_object *obj2);
  76 typedef int osl_rbtree_loop_func(struct osl_row *row, void *data);
  77
  78 osl_compare_func osl_hash_compare, uint32_compare;
  79
  80 /**
  81  * Describes one column of a osl table.
  82  */
  83 struct osl_column_description {
  84         /** One of zje tree possible types of storage */
  85         enum osl_storage_type storage_type;
  86         /** Specifies further properties of the column */
  87         enum osl_storage_flags storage_flags;
  88         /**
  89          * The column name determines the name of the directory where all data
  90          * for this column will be stored. Its hash is stored in the table
  91          * header. This field is ignored if the storage type is \a NO_STORAGE
  92          */
  93         char *name;
  94         /**
  95          * For columns with an associated rbtree, this must point to a function
  96          * that compares the values of two objects, either a built-in function
  97          * or a function defined by the application may be supplied.  This
  98          * field is ignored if the column does not have an associated rbtree.
  99          *
 100          * \sa osl_storage_flags, osl_compare_func
 101          */
 102         osl_compare_func *compare_function;
 103         /**
 104          * If the \a OSL_FIXED_SIZE flag is set for this column, this value
 105          * determines the fixed size of all objects of this column. It is
 106          * ignored, if \a OSL_FIXED_SIZE is not set.
 107          */
 108         uint32_t data_size;
 109 };
 110
 111 /**
 112  * Describes one osl table.
 113  */
 114 struct osl_table_description {
 115         /** The directory which contains all files of this table. */
 116         const char *dir;
 117         /**
 118          * The table name. A subdirectory of \a dir called \a name is created
 119          * at table creation time. It must be a valid name for a subdirectory.
 120          * In particular, no slashes are allowed for \a name.
 121          */
 122         const char *name;
 123         /** The number of columns of this table. */
 124         uint16_t num_columns;
 125         /** Further table-wide information. */
 126         enum osl_table_flags flags;
 127         /** The array describing the individual columns of the table. */
 128         struct osl_column_description *column_descriptions;
 129 };
 130
 131 /** Flags to be passed to \a osl_close_table(). */
 132 enum osl_close_flags {
 133         /**
 134          * The table header contains a "dirty" flag which specifies whether
 135          * the table is currently open by another process. This flag specifies
 136          * that the dirty flag should be cleared before closing the table.
 137          */
 138         OSL_MARK_CLEAN = 1,
 139         /**
 140          * If the table contains columns of type \a OSL_NO_STORAGE and this
 141          * flag is passed to osl_close_table(), free(3) is called for each
 142          * object of each column of type \a OSL_NO_STORAGE.
 143          */
 144         OSL_FREE_VOLATILE = 2
 145 };
 146
 147
 148
 149 int osl_create_table(const struct osl_table_description *desc);
 150 int osl_open_table(const struct osl_table_description *desc,
 151         struct osl_table **result);
 152 int osl_close_table(struct osl_table *t, enum osl_close_flags flags);
 153 int osl_get_row(const struct osl_table *t, unsigned col_num,
 154         const struct osl_object *obj, struct osl_row **result);
 155 int osl_get_object(const struct osl_table *t, const struct osl_row *row,
 156         unsigned col_num, struct osl_object *object);
 157 int osl_open_disk_object(const struct osl_table *t,
 158         const struct osl_row *r, unsigned col_num, struct osl_object *obj);
 159 int osl_close_disk_object(struct osl_object *obj);
 160 int osl_add_and_get_row(struct osl_table *t, struct osl_object *objects,
 161         struct osl_row **row);
 162 int osl_add_row(struct osl_table *t, struct osl_object *objects);
 163 int osl_del_row(struct osl_table *t, struct osl_row *row);
 164 int osl_rbtree_loop(const struct osl_table *t, unsigned col_num,
 165         void *private_data, osl_rbtree_loop_func *func);
 166 int osl_rbtree_loop_reverse(const struct osl_table *t, unsigned col_num,
 167         void *private_data, osl_rbtree_loop_func *func);
 168 int osl_update_object(struct osl_table *t, const struct osl_row *r,
 169         unsigned col_num, struct osl_object *obj);
 170 int osl_get_num_rows(const struct osl_table *t, unsigned *num_rows);
 171 int osl_rbtree_first_row(const struct osl_table *t, unsigned col_num,
 172         struct osl_row **result);
 173 int osl_rbtree_last_row(const struct osl_table *t, unsigned col_num,
 174         struct osl_row **result);
 175 int osl_get_nth_row(const struct osl_table *t, unsigned col_num,
 176         unsigned n, struct osl_row **result);
 177 int osl_get_rank(const struct osl_table *t, struct osl_row *r,
 178         unsigned col_num, unsigned *rank);
 179
 180 int for_each_file_in_dir(const char *dirname,
 181         int (*func)(const char *, const void *), const void *private_data);
 182 ssize_t para_write_all(int fd, const void *buf, size_t size);
 183 int para_lseek(int fd, off_t *offset, int whence);
 184 int para_write_file(const char *filename, const void *buf, size_t size);
 185
 186 /**
 187  * A wrapper for munmap(2).
 188  *
 189  * \param start The start address of the memory mapping.
 190  * \param length The size of the mapping.
 191  *
 192  * \return Positive on success, \p -E_MUNMAP on errors.
 193  *
 194  * \sa munmap(2), mmap_full_file().
 195  */
 196 _static_inline_ int para_munmap(void *start, size_t length)
 197 {
 198         if (munmap(start, length) >= 0)
 199                 return 1;
 200         PARA_ERROR_LOG("munmap (%p/%zu) failed: %s\n", start, length,
 201                 strerror(errno));
 202         return -E_MUNMAP;
 203 }