X-Git-Url: http://git.tuebingen.mpg.de/?p=osl.git;a=blobdiff_plain;f=osl.h.in;h=3d21439719c3277bbd9d181d717cf82df7244e6b;hp=67d705a5371a0f435297e9914e4efd8fd45d4072;hb=c283f067d330a9288aec5510836cd4a898dd07df;hpb=368cbd78587922ec3620b72bdb1c9f8cdf9297d1 diff --git a/osl.h.in b/osl.h.in index 67d705a..3d21439 100644 --- a/osl.h.in +++ b/osl.h.in @@ -1,5 +1,5 @@ /* - * Copyright (C) 2007-2008 Andre Noll + * Copyright (C) 2007-2009 Andre Noll * * Licensed under the GPL v2. For licencing details see COPYING. */ @@ -7,6 +7,7 @@ /** \file osl.h User interface for the object storage layer. */ #include +#include /** Export all declarations in this file. */ #pragma GCC visibility push(default) @@ -41,7 +42,7 @@ enum osl_storage_type { 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 }; @@ -61,7 +62,7 @@ enum osl_storage_flags { 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 @@ -74,10 +75,10 @@ struct osl_row; /** * 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); @@ -94,14 +95,14 @@ typedef int osl_rbtree_loop_func(struct osl_row *row, void *data); * 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; /** @@ -115,7 +116,7 @@ struct osl_column_description { 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; @@ -123,9 +124,17 @@ struct osl_column_description { /** * 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 @@ -144,9 +153,10 @@ struct osl_table_description { /** 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, /** @@ -171,7 +181,7 @@ int osl_create_table(const struct osl_table_description *desc); * * 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 @@ -209,7 +219,8 @@ int osl_close_table(struct osl_table *t, enum osl_close_flags flags); * 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 */ @@ -217,10 +228,10 @@ int osl_get_row(const struct osl_table *t, unsigned col_num, 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. * @@ -291,7 +302,6 @@ int osl_close_disk_object(struct osl_object *obj); 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. * @@ -313,7 +323,7 @@ int osl_add_row(struct osl_table *t, struct osl_object *objects); * 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. */ @@ -336,9 +346,9 @@ int osl_del_row(struct osl_table *t, struct osl_row *row); * 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. */ @@ -378,7 +388,7 @@ int osl_rbtree_loop_reverse(const struct osl_table *t, unsigned col_num, * 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 */ @@ -397,7 +407,6 @@ int osl_update_object(struct osl_table *t, const struct osl_row *r, */ 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. * @@ -444,8 +453,8 @@ int osl_rbtree_last_row(const struct osl_table *t, unsigned col_num, * \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. * @@ -476,19 +485,6 @@ int osl_get_nth_row(const struct osl_table *t, unsigned col_num, 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. *