/*
- * Copyright (C) 2007-2008 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2007-2009 Andre Noll <maan@tuebingen.mpg.de>
*
* Licensed under the GPL v2. For licencing details see COPYING.
*/
OSL_DISK_STORAGE,
/**
* Objects for columns of this type are volatile: They are only stored
- * in memory and are discarded once the table gets closed.
+ * in memory and are discarded when the table is closed.
*/
OSL_NO_STORAGE
};
OSL_RBTREE = 1,
/** The data for this column will have constant size. */
OSL_FIXED_SIZE = 2,
- /** All values of this column will be different. */
+ /** All values are different. Must be set if \p OSL_RBTREE is set. */
OSL_UNIQUE = 4,
/** Do not free the data for this column (\p OSL_NO_STORAGE). */
OSL_DONT_FREE = 8
/**
* In order to build up an rbtree a compare function for the objects must be
- * specified. Such a function always takes pointers to the two objects to be
- * compared. It must return -1, zero, or 1, if the first argument is considered
- * to be respectively less than, equal to, or greater than the second. If two
- * members compare as equal, their order in the sorted array is undefined.
+ * provided. This function takes pointers to the two objects to be compared. It
+ * must return -1, zero, or 1, if the first argument is considered to be
+ * respectively less than, equal to, or greater than the second. If two members
+ * compare as equal, their order in the rbtree is undefined.
*/
typedef int osl_compare_func(const struct osl_object *obj1,
const struct osl_object *obj2);
* Describes one column of a osl table.
*/
struct osl_column_description {
- /** One of the tree possible types of storage, \sa osl_storage_type. */
+ /** One of the three possible types of storage, \sa osl_storage_type. */
uint16_t storage_type;
/** Specifies further properties of the column, \sa osl_storage_flags. */
uint16_t storage_flags;
/**
* The column name determines the name of the directory where all data
* for this column will be stored. Its hash is stored in the table
- * header. This field is ignored if the storage type is \a NO_STORAGE
+ * header. This field is ignored if the storage type is \a NO_STORAGE.
*/
char *name;
/**
osl_compare_func *compare_function;
/**
* If the \a OSL_FIXED_SIZE flag is set for this column, this value
- * determines the fixed size of all objects of this column. It is
+ * describes the number of bytes of each object of this column. It is
* ignored, if \a OSL_FIXED_SIZE is not set.
*/
uint32_t data_size;
/**
* Describes one osl table.
+ *
+ * A pointer to the table description is passed to \ref osl_create_table() and
+ * \ref osl_open_table(). The osl library calls which operate on an open table
+ * refer to the fields of the table description through this pointer. Hence the
+ * table description must not be modified or freed before the table is closed.
*/
struct osl_table_description {
- /** The directory which contains all files of this table. */
+ /**
+ * The directory which contains all files of this table. This may be
+ * either relative to the cwd or an absolute path.
+ */
const char *dir;
/**
* The table name. A subdirectory of \a dir called \a name is created
/** Flags to be passed to \a osl_close_table(). */
enum osl_close_flags {
/**
- * The table header contains a "dirty" flag which specifies whether
- * the table is currently open by another process. This flag specifies
- * that the dirty flag should be cleared before closing the table.
+ * The table header contains a "dirty" flag which indicates whether the
+ * table is currently held open by another process. The \a
+ * OSL_MARK_CLEAN flag instructs libosl to clear the dirty flag when
+ * the table is closed.
*/
OSL_MARK_CLEAN = 1,
/**
*
* Each osl table must be opened before its data can be accessed.
*
- * \param table_desc Describes the table to be opened.
+ * \param desc Describes the table to be opened.
* \param result Contains a pointer to the open table on success.
*
* The table description given by \a desc should coincide with the
* Lookup \a obj in \a t and return the row containing \a obj. The column
* specified by \a col_num must have an associated rbtree.
*
- * \return Standard.
+ * \return Standard. \a result is set to \p NULL if and only if the function
+ * returns negative.
*
* \sa osl_storage_flags
*/
const struct osl_object *obj, struct osl_row **result);
/**
- * Retrieve an object identified by row and column
+ * Retrieve an object identified by row and column.
*
* \param t Pointer to an open osl table.
- * \param r Pointer to the row.
+ * \param row Pointer to the row.
* \param col_num The column number.
* \param object The result pointer.
*
int osl_add_and_get_row(struct osl_table *t, struct osl_object *objects,
struct osl_row **row);
-
/**
* Add a new row to an osl table.
*
* This removes all disk storage objects, removes all rbtree nodes, and frees
* all volatile objects belonging to the given row. For mapped columns, the
* data is merely marked invalid and may be pruned from time to time by
- * osl_fsck.
+ * oslfsck.
*
* \return Standard.
*/
* second argument. The loop terminates either if \a func returns a negative
* value, or if all nodes of the tree have been visited.
*
- *
* \return Standard. If the termination of the loop was caused by \a func
- * returning a negative value, \p -E_OSL_LOOP is returned.
+ * returning a negative value, \p -E_OSL_LOOP is returned. This is the only
+ * possible error.
*
* \sa osl_storage_flags, osl_rbtree_loop_reverse(), osl_compare_func.
*/
* If the \p OSL_RBTREE flag is set for \a col_num, you \b MUST call this
* function in order to change the contents of an object, even for volatile or
* mapped columns of constant size (which may be updated directly if \p
- * OSL_RBTREE is not set). Otherwise the rbtree might become corrupted.
+ * OSL_RBTREE is not set). Otherwise the rbtree might become corrupt.
*
* \return Standard
*/
*/
int osl_get_num_rows(const struct osl_table *t, unsigned *num_rows);
-
/**
* Get the row corresponding to the smallest rbtree node of a column.
*
* \param result Row is returned here.
*
* Retrieve the n-th order statistic with respect to the compare function
- * of the rbtree column \a col_num. In other words, get that row with
- * \a n th greatest value in column \a col_num. It's an error if
+ * of the rbtree column \a col_num. In other words, get the row with
+ * \a n th greatest value in column \a col_num. It is an error if
* \a col_num is not a rbtree column, or if \a n is larger than the
* number of rows in the table.
*
int osl_get_rank(const struct osl_table *t, struct osl_row *r,
unsigned col_num, unsigned *rank);
-/**
- * Compare two osl objects pointing to hash values.
- *
- * \param obj1 Pointer to the first hash object.
- * \param obj2 Pointer to the second hash object.
- *
- * \return The values required for an osl compare function.
- *
- * \sa osl_compare_func, uint32_compare().
- */
-int osl_hash_compare(const struct osl_object *obj1,
- const struct osl_object *obj2);
-
/**
* Get a string describing the error code passed in the argument.
*
projects / osl.git / blobdiff