#include <sys/mman.h>
#include <inttypes.h>

Include dependency graph for osl.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	osl_object

struct	osl_column_description

struct	osl_table_description

Typedefs
typedef int	osl_compare_func(const struct osl_object obj1, const struct osl_object obj2)

typedef int	osl_rbtree_loop_func(struct osl_row row, void data)

Enumerations
enum	osl_table_flags { OSL_LARGE_TABLE = 1 }

enum	osl_storage_type { OSL_MAPPED_STORAGE, OSL_DISK_STORAGE, OSL_NO_STORAGE }

enum	osl_storage_flags { OSL_RBTREE = 1, OSL_FIXED_SIZE = 2, OSL_UNIQUE = 4, OSL_DONT_FREE = 8 }

enum	osl_close_flags { OSL_MARK_CLEAN = 1, OSL_FREE_VOLATILE = 2 }

enum	osl_errors { E_OSL_BAD_DB_DIR =1, E_OSL_NO_COLUMN_DESC, E_OSL_BAD_NAME, E_OSL_BAD_STORAGE_TYPE, E_OSL_BAD_STORAGE_FLAGS, E_OSL_NO_COLUMN_NAME, E_OSL_NO_COLUMNS, E_OSL_BAD_COLUMN_NAME, E_OSL_NO_UNIQUE_RBTREE_COLUMN, E_OSL_NO_RBTREE_COL, E_OSL_DUPLICATE_COL_NAME, E_OSL_BAD_STORAGE_SIZE, E_OSL_NO_COMPARE_FUNC, E_OSL_BAD_DATA_SIZE, E_OSL_NOT_MAPPED, E_OSL_ALREADY_MAPPED, E_OSL_BAD_SIZE, E_OSL_BAD_TABLE, E_OSL_BAD_TABLE_DESC, E_OSL_RB_KEY_EXISTS, E_OSL_RB_KEY_NOT_FOUND, E_OSL_BAD_ROW_NUM, E_OSL_INDEX_CORRUPTION, E_OSL_LSEEK, E_OSL_BUSY, E_OSL_SHORT_TABLE, E_OSL_NO_MAGIC, E_OSL_VERSION_MISMATCH, E_OSL_BAD_COLUMN_NUM, E_OSL_BAD_TABLE_FLAGS, E_OSL_BAD_ROW, E_OSL_EMPTY, E_OSL_MMAP, E_OSL_LOOP, E_OSL_NOMEM, E_OSL_NOTDIR, E_OSL_STAT, E_OSL_UNLINK, E_OSL_WRITE, E_OSL_OPEN, E_OSL_TRUNCATE, E_OSL_MKDIR, E_OSL_RENAME, E_OSL_MUNMAP, E_OSL_FSTAT, E_OSL_DIR_EXISTS, E_OSL_NOENT }

Functions
int	osl_create_table (const struct osl_table_description *desc)

int	osl_open_table (const struct osl_table_description desc, struct osl_table *result)

int	osl_close_table (struct osl_table *t, enum osl_close_flags flags)

int	osl_get_row (const struct osl_table t, unsigned col_num, const struct osl_object obj, struct osl_row **result)

int	osl_get_object (const struct osl_table t, const struct osl_row row, unsigned col_num, struct osl_object *object)

int	osl_open_disk_object (const struct osl_table t, const struct osl_row r, unsigned col_num, struct osl_object *obj)

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)

int	osl_add_row (struct osl_table t, struct osl_object objects)

int	osl_del_row (struct osl_table t, struct osl_row row)

int	osl_rbtree_loop (const struct osl_table t, unsigned col_num, void private_data, osl_rbtree_loop_func *func)

int	osl_rbtree_loop_reverse (const struct osl_table t, unsigned col_num, void private_data, osl_rbtree_loop_func *func)

int	osl_update_object (struct osl_table t, const struct osl_row r, unsigned col_num, struct osl_object *obj)

int	osl_get_num_rows (const struct osl_table t, unsigned num_rows)

int	osl_rbtree_first_row (const struct osl_table t, unsigned col_num, struct osl_row *result)

int	osl_rbtree_last_row (const struct osl_table t, unsigned col_num, struct osl_row *result)

int	osl_get_nth_row (const struct osl_table t, unsigned col_num, unsigned n, struct osl_row *result)

int	osl_get_rank (const struct osl_table t, struct osl_row r, unsigned col_num, unsigned *rank)

const char *	osl_strerror (int num)

Detailed Description

User interface for the object storage layer.

Definition in file osl.h.

Typedef Documentation

typedef int osl_compare_func(const struct osl_object *obj1, const struct osl_object *obj2)

In order to build up an rbtree a compare function for the objects must be 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.

Definition at line 85 of file osl.h.

typedef int osl_rbtree_loop_func(struct osl_row *row, void *data)

The osl_rbreee_loop functions take a function pointer of this type. For each node in the rbtree, the given function is called.

See also: osl_rbtree_loop(), osl_rbtree_loop_reverse().

Definition at line 94 of file osl.h.

Enumeration Type Documentation

enum osl_close_flags

Flags to be passed to osl_close_table().

Enumerator
OSL_MARK_CLEAN	The table header contains a "dirty" flag which indicates whether the table is currently held open by another process. The OSL_MARK_CLEAN flag instructs libosl to clear the dirty flag when the table is closed.
OSL_FREE_VOLATILE	If the table contains columns of type OSL_NO_STORAGE and this flag is passed to osl_close_table(), free(3) is called for each object of each column of type OSL_NO_STORAGE.

Definition at line 156 of file osl.h.

                      {
         OSL_MARK_CLEAN = 1,
         OSL_FREE_VOLATILE = 2
 };

enum osl_errors

public error codes of the osl library.

Definition at line 504 of file osl.h.

                 {       E_OSL_BAD_DB_DIR=1,
         E_OSL_NO_COLUMN_DESC,
         E_OSL_BAD_NAME,
         E_OSL_BAD_STORAGE_TYPE,
         E_OSL_BAD_STORAGE_FLAGS,
         E_OSL_NO_COLUMN_NAME,
         E_OSL_NO_COLUMNS,
         E_OSL_BAD_COLUMN_NAME,
         E_OSL_NO_UNIQUE_RBTREE_COLUMN,
         E_OSL_NO_RBTREE_COL,
         E_OSL_DUPLICATE_COL_NAME,
         E_OSL_BAD_STORAGE_SIZE,
         E_OSL_NO_COMPARE_FUNC,
         E_OSL_BAD_DATA_SIZE,
         E_OSL_NOT_MAPPED,
         E_OSL_ALREADY_MAPPED,
         E_OSL_BAD_SIZE,
         E_OSL_BAD_TABLE,
         E_OSL_BAD_TABLE_DESC,
         E_OSL_RB_KEY_EXISTS,
         E_OSL_RB_KEY_NOT_FOUND,
         E_OSL_BAD_ROW_NUM,
         E_OSL_INDEX_CORRUPTION,
         E_OSL_LSEEK,
         E_OSL_BUSY,
         E_OSL_SHORT_TABLE,
         E_OSL_NO_MAGIC,
         E_OSL_VERSION_MISMATCH,
         E_OSL_BAD_COLUMN_NUM,
         E_OSL_BAD_TABLE_FLAGS,
         E_OSL_BAD_ROW,
         E_OSL_EMPTY,
         E_OSL_MMAP,
         E_OSL_LOOP,
         E_OSL_NOMEM,
         E_OSL_NOTDIR,
         E_OSL_STAT,
         E_OSL_UNLINK,
         E_OSL_WRITE,
         E_OSL_OPEN,
         E_OSL_TRUNCATE,
         E_OSL_MKDIR,
         E_OSL_RENAME,
         E_OSL_MUNMAP,
         E_OSL_FSTAT,
         E_OSL_DIR_EXISTS,
         E_OSL_NOENT};

enum osl_storage_flags

Additional per-column flags

Enumerator
OSL_RBTREE	Build an rbtree for this column. This is only possible if the storage type of the column is either OSL_MAPPED_STORAGE or OSL_NO_STORAGE. In order to lookup objects in the table by using osl_get_row(), the lookup column must have an associated rbtree. See also osl_storage_type, osl_get_row()
OSL_FIXED_SIZE	The data for this column will have constant size.
OSL_UNIQUE	All values are different. Must be set if `OSL_RBTREE` is set.
OSL_DONT_FREE	Do not free the data for this column (`OSL_NO_STORAGE`).

Definition at line 55 of file osl.h.

                        {
         OSL_RBTREE = 1,
         OSL_FIXED_SIZE = 2,
         OSL_UNIQUE = 4,
         OSL_DONT_FREE = 8
 };

enum osl_storage_type

The three different types of storage for an osl column

Enumerator
OSL_MAPPED_STORAGE	All data for this column is stored in one file which gets mmapped by osl_open_table(). This is suitable for columns that do not hold much data.
OSL_DISK_STORAGE	Each entry is stored on disk and is loaded on demand by open_disk_object(). This is the preferable storage type for large objects that need not be in memory all the time.
OSL_NO_STORAGE	Objects for columns of this type are volatile: They are only stored in memory and are discarded when the table is closed.

Definition at line 32 of file osl.h.

                       {
         OSL_MAPPED_STORAGE,
          OSL_DISK_STORAGE,
         OSL_NO_STORAGE
 };

enum osl_table_flags

Flags that change the internal handling of osl tables.

Enumerator
OSL_LARGE_TABLE	This table will have many rows.

Definition at line 26 of file osl.h.

                      {
         OSL_LARGE_TABLE = 1
 };

Function Documentation

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 and retrieve this row.

Parameters

t	Pointer to an open osl table.
objects	Array of objects to be added.
row	Result pointer.

The objects parameter must point to an array containing one object per column. The order of the objects in the array is given by the table description of table. Several sanity checks are performed during object insertion and the function returns without modifying the table if any of these tests fail. In fact, it is atomic in the sense that it either succeeds or leaves the table unchanged (i.e. either all or none of the objects are added to the table).

It is considered an error if an object is added to a column with associated rbtree if this object is equal to an object already contained in that column (i.e. the compare function for the column's rbtree returns zero).

Returns: Standard.

See also: struct osl_table_description, osl_compare_func, osl_add_row().

int osl_add_row	(	struct osl_table *	t,
		struct osl_object *	objects
	)

Add a new row to an osl table.

Parameters

t	Same meaning as osl_add_and_get_row().
objects	Same meaning as osl_add_and_get_row().

Returns: The return value of the underlying call to osl_add_and_get_row().

This is equivalent to osl_add_and_get_row(t, objects, NULL).

Referenced by string_compare().

Here is the caller graph for this function:

int osl_close_disk_object ( struct osl_object * obj )

Free resources that were allocated during osl_open_disk_object().

Parameters

obj	Pointer to the object previously returned by open_disk_object().

Returns: The return value of the underlying call to munmap().

See also: munmap(2).

int osl_close_table	(	struct osl_table *	t,
		enum osl_close_flags	flags
	)

Close an osl table.

Parameters

t	Pointer to the table to be closed.
flags	Options for what should be cleaned up.

If osl_open_table() succeeds, the resulting table pointer must later be passed to this function in order to flush all changes to the file system and to free the resources that were allocated by osl_open_table().

Returns: Standard.

See also: osl_open_table(), unmap_table().

Referenced by string_compare().

Here is the caller graph for this function:

int osl_create_table ( const struct osl_table_description * desc )

Create a new osl table.

Parameters

desc	Pointer to the table description.

Returns: Standard.

Referenced by string_compare().

Here is the caller graph for this function:

int osl_del_row	(	struct osl_table *	t,
		struct osl_row *	row
	)

Delete a row from an osl table.

Parameters

t	Pointer to an open osl table.
row	Pointer to the row to delete.

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 oslfsck.

Returns: Standard.

int osl_get_nth_row	(	const struct osl_table *	t,
		unsigned	col_num,
		unsigned	n,
		struct osl_row **	result
	)

Get the row with n-th greatest value.

Parameters

t	Pointer to an open osl table.
col_num	The column number.
n	The rank of the desired row.
result	Row is returned here.

Retrieve the n-th order statistic with respect to the compare function of the rbtree column col_num. In other words, get the row with n th greatest value in column col_num. It is an error if col_num is not a rbtree column, or if n is larger than the number of rows in the table.

Returns: Standard.

See also: osl_storage_flags, osl_compare_func, osl_get_row(), osl_rbtree_last_row(), osl_rbtree_first_row(), osl_get_rank().

int osl_get_num_rows	(	const struct osl_table *	t,
		unsigned *	num_rows
	)

Get the number of rows of the given table.

Parameters

t	Pointer to an open osl table.
num_rows	Result is returned here.

The number of rows returned via num_rows excluding any invalid rows.

Returns: Positive on success, -E_OSL_BAD_TABLE if t is NULL.

int osl_get_object	(	const struct osl_table *	t,
		const struct osl_row *	row,
		unsigned	col_num,
		struct osl_object *	object
	)

Retrieve an object identified by row and column.

Parameters

t	Pointer to an open osl table.
row	Pointer to the row.
col_num	The column number.
object	The result pointer.

The column determined by col_num must be of type OSL_MAPPED_STORAGE or OSL_NO_STORAGE, i.e. no disk storage objects may be retrieved by this function.

Returns: Standard.

See also: osl_storage_type, osl_open_disk_object().

Referenced by string_compare().

Here is the caller graph for this function:

int osl_get_rank	(	const struct osl_table *	t,
		struct osl_row *	r,
		unsigned	col_num,
		unsigned *	rank
	)

Get the rank of a row.

Parameters

t	An open osl table.
r	The row to get the rank of.
col_num	The number of an rbtree column.
rank	Result pointer.

The rank is, by definition, the position of the row in the linear order determined by an in-order tree walk of the rbtree associated with column number col_num of table.

Returns: Standard.

See also: osl_get_nth_row().

int osl_get_row	(	const struct osl_table *	t,
		unsigned	col_num,
		const struct osl_object *	obj,
		struct osl_row **	result
	)

Get the row that contains the given object.

Parameters

t	Pointer to an open osl table.
col_num	The number of the column to be searched.
obj	The object to be looked up.
result	Points to the row containing obj.

Lookup obj in t and return the row containing obj. The column specified by col_num must have an associated rbtree.

Returns: Standard. result is set to NULL if and only if the function returns negative.

See also: osl_storage_flags

Referenced by string_compare().

Here is the caller graph for this function:

int osl_open_disk_object	(	const struct osl_table *	t,
		const struct osl_row *	r,
		unsigned	col_num,
		struct osl_object *	obj
	)

Retrieve an object of type OSL_DISK_STORAGE by row and column.

Parameters

t	Pointer to an open osl table.
r	Pointer to the row containing the object.
col_num	The column number.
obj	Points to the result upon successful return.

For columns of type OSL_DISK_STORAGE, this function must be used to retrieve one of its containing objects. Afterwards, osl_close_disk_object() must be called in order to deallocate the resources.

Returns: Standard.

See also: osl_get_object(), osl_storage_type, osl_close_disk_object().

int osl_open_table	(	const struct osl_table_description *	desc,
		struct osl_table **	result
	)

Open an osl table.

Each osl table must be opened before its data can be accessed.

Parameters

desc	Describes the table to be opened.
result	Contains a pointer to the open table on success.

The table description given by desc should coincide with the description used at creation time.

Returns: Standard.

Referenced by string_compare().

Here is the caller graph for this function:

int osl_rbtree_first_row	(	const struct osl_table *	t,
		unsigned	col_num,
		struct osl_row **	result
	)

Get the row corresponding to the smallest rbtree node of a column.

Parameters

t	An open rbtree table.
col_num	The number of the rbtree column.
result	A pointer to the first row is returned here.

The rbtree node of the smallest object (with respect to the corresponding compare function) is selected and the row containing this object is returned. It is an error if col_num refers to a column without an associated rbtree.

Returns: Standard.

See also: osl_get_nth_row(), osl_rbtree_last_row().

int osl_rbtree_last_row	(	const struct osl_table *	t,
		unsigned	col_num,
		struct osl_row **	result
	)

Get the row corresponding to the greatest rbtree node of a column.

Parameters

t	The same meaning as in `osl_rbtree_first_row()`.
col_num	The same meaning as in `osl_rbtree_first_row()`.
result	The same meaning as in `osl_rbtree_first_row()`.

This function works just like osl_rbtree_first_row(), the only difference is that the row containing the greatest rather than the smallest object is returned.

Returns: Standard.

See also: osl_get_nth_row(), osl_rbtree_first_row().

int osl_rbtree_loop	(	const struct osl_table *	t,
		unsigned	col_num,
		void *	private_data,
		osl_rbtree_loop_func *	func
	)

Loop over all nodes in an rbtree.

Parameters

t	Pointer to an open osl table.
col_num	The column to use for iterating over the elements.
private_data	Pointer that gets passed to func.
func	The function to be called for each node in the rbtree.

This function does an in-order walk of the rbtree associated with col_num. It is an error if the OSL_RBTREE flag is not set for this column. For each node in the rbtree, the given function func is called with two pointers as arguments: The first osl_row* argument points to the row that contains the object corresponding to the rbtree node currently traversed, and the private_data pointer is passed verbatim to func as the second argument. The loop terminates either if func returns a negative value, or if all nodes of the tree have been visited.

Returns: Standard. If the termination of the loop was caused by func returning a negative value, -E_OSL_LOOP is returned. This is the only possible error.

See also: osl_storage_flags, osl_rbtree_loop_reverse(), osl_compare_func.

Referenced by string_compare().

Here is the caller graph for this function:

int osl_rbtree_loop_reverse	(	const struct osl_table *	t,
		unsigned	col_num,
		void *	private_data,
		osl_rbtree_loop_func *	func
	)

Loop over all nodes in an rbtree in reverse order.

Parameters

t	Identical meaning as in `osl_rbtree_loop()`.
col_num	Identical meaning as in `osl_rbtree_loop()`.
private_data	Identical meaning as in `osl_rbtree_loop()`.
func	Identical meaning as in `osl_rbtree_loop()`.

This function is identical to osl_rbtree_loop(), the only difference is that the tree is walked in reverse order.

Returns: The same return value as osl_rbtree_loop().

See also: osl_rbtree_loop().

const char* osl_strerror ( int num )

Get a string describing the error code passed in the argument.

Parameters

num	The error code.

This works just like strerror(3). The given number must be an osl error code. The result must not be freed by the caller.

Returns: The error text corresponding to an osl error code.

Referenced by string_compare().

Here is the caller graph for this function:

int osl_update_object	(	struct osl_table *	t,
		const struct osl_row *	r,
		unsigned	col_num,
		struct osl_object *	obj
	)

Change an object in an osl table.

Parameters

t	Pointer to an open osl table.
r	Pointer to the row containing the object to be updated.
col_num	Number of the column containing the object to be updated.
obj	Pointer to the replacement object.

This function gets rid of all references to the old object. This includes removal of the rbtree node in case there is an rbtree associated with col_num. It then inserts obj into the table and the rbtree if necessary.

If the OSL_RBTREE flag is set for col_num, you 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 OSL_RBTREE is not set). Otherwise the rbtree might become corrupt.

Returns: Standard

The lightweight storage library

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation