bitablecommon.h File Reference

Common definitions for the bitable interface, shared between reading and writing. More...

#include <stdint.h>
#include <stdlib.h>

Go to the source code of this file.

Data Structures
struct	BitableValue
struct	BitablePaths
struct	BitableStats

Macros
#define	BITABLE_API
#define	BITABLE_MAX_KEY_SIZE   768
#define	BITABLE_MIN_PAGE_SIZE   2048
#define	BITABLE_MAX_PAGE_SIZE   65536
#define	BITABLE_MAX_ALIGNMENT   512
#define	BITABLE_MAX_BRANCH_LEVELS   32

Typedefs
typedef enum BitableResult	BitableResult
typedef enum BitableReadOpenFlags	BitableReadOpenFlags
typedef struct BitableValue	BitableValue
typedef struct BitablePaths	BitablePaths
typedef struct BitableStats	BitableStats
typedef int(	BitableComparisonFunction )(const BitableValue *left, const BitableValue *right)

Enumerations
enum	BitableResult {   BR_SUCCESS = 0, BR_END_OF_SEQUENCE = 1, BR_FILE_OPEN_FAILED = 2, BR_FILE_OPERATION_FAILED = 3,   BR_FILE_TOO_LARGE = 4, BR_BAD_PATH = 5, BR_ALREADY_OPEN = 6, BR_FILE_TOO_SMALL = 7,   BR_HEADER_CORRUPT = 8, BR_KEY_NOT_FOUND = 9, BR_INVALID_CURSOR_LOCATION = 10, BR_MAXIMUM_TABLE_TREE_DEPTH = 11,   BR_KEY_INVALID = 12, BR_PAGESIZE_INVALID = 13, BR_ALIGNMENT_INVALID = 14 }
enum	BitableReadOpenFlags { BRO_NONE = 0, BRO_RANDOM = 1, BRO_SEQUENTIAL = 2 }

Functions
BITABLE_API void	bitable_build_paths (BitablePaths *paths, const char *basePath)
BITABLE_API void	bitable_free_paths (BitablePaths *paths)

Detailed Description

Common definitions for the bitable interface, shared between reading and writing.

Macro Definition Documentation

#define BITABLE_API

The API prefix macro for the bitable exported functions

#define BITABLE_MAX_ALIGNMENT   512

The maximum alignment that can be used for keys and values.

#define BITABLE_MAX_BRANCH_LEVELS   32

The maximum number of branch levels used before indexing the bitable.

#define BITABLE_MAX_KEY_SIZE   768

The maximum allowed keysize in bytes. You may not have keys larger than this.

#define BITABLE_MAX_PAGE_SIZE   65536

The maximum page size allowed in bytes. Note, the limit is 64k because internal offsets are 16bit unsigned.

#define BITABLE_MIN_PAGE_SIZE   2048

The minimum allowed page size in bytes. You may not specify pages smaller than this.

Typedef Documentation

typedef int( BitableComparisonFunction)(const BitableValue *left, const BitableValue *right)

The type for a comparison function used for comparing two keys when searching a bitable.

typedef struct BitablePaths BitablePaths

The file paths for different files used by a bitable

typedef enum BitableReadOpenFlags BitableReadOpenFlags

Flags used for opening bitable files indicating the intended access patterns.

typedef enum BitableResult BitableResult

Return code used by bitable functions to indicate success, error conditions etc.

typedef struct BitableStats BitableStats

Statistics and information from the readable bitable header.

typedef struct BitableValue BitableValue

Represents a value used for keys/value data by bitable. Basically a pointer to a data buffer and a size.

Enumeration Type Documentation

enum BitableReadOpenFlags

Flags used for opening bitable files indicating the intended access patterns.

Enumerator
BRO_NONE	No options.
BRO_RANDOM	Access will be mostly random
BRO_SEQUENTIAL	Access will be mostly sequential.

enum BitableResult

Return code used by bitable functions to indicate success, error conditions etc.

Enumerator
BR_SUCCESS	The operation completed successfully.
BR_END_OF_SEQUENCE	The cursor or find operation resulted in going out of the bounds of the bitable.
BR_FILE_OPEN_FAILED	Failed to open the file.
BR_FILE_OPERATION_FAILED	An OS level file operation failed.
BR_FILE_TOO_LARGE	The bitable file is too large - this usually occurs when a file is too large to be mapped into the address space (e.g. on 32bit platforms)
BR_BAD_PATH	A file path provided was invalid.
BR_ALREADY_OPEN	The bitable passed in is already in an open state and can't be opened again.
BR_FILE_TOO_SMALL	The bitable file is too small (smaller than a page, or too small to read the header)
BR_HEADER_CORRUPT	The bitable header is corrupt - either the header identifier is wrong or the checksum is invalid.
BR_KEY_NOT_FOUND	An exact match (or similar) search was performed and the particular key wasn't found.
BR_INVALID_CURSOR_LOCATION	An operation was attempted on a cursor that wasn't in the valid range.
BR_MAXIMUM_TABLE_TREE_DEPTH	The bitable is larger than the maximum allowed tree depth.
BR_KEY_INVALID	A key that has been passed in is too large (larger than BITABLE_MAX_KEY_SIZE) or has a negative size
BR_PAGESIZE_INVALID	The page size is too small (less than BITABLE_MIN_PAGE_SIZE), too large (greater than BITABLE_MAX_PAGE_SIZE) or not a power of two.
BR_ALIGNMENT_INVALID	A value passed in for key or value data alignment is too large (greater than BITABLE_MAX_ALIGNMENT) or not a power of two.

Function Documentation

BITABLE_API void bitable_build_paths	(	BitablePaths *	paths,
		const char *	basePath
	)

Take a paths object and populate it with the potential sub-paths of a bitable. Will allocate memory to populate the paths. Does not read from the file system at all, builds the maximum number of paths deterministically. Note, uses malloc to allocate paths.

Parameters

[out]	paths	The paths to be populated. Should not be null.
	basePath	The main path for the bitable. Should not be null. Null terminated UTF8 is expected.

BITABLE_API void bitable_free_paths

(

BitablePaths *

paths

)

Free the memory for the file paths allocated by bitable_build_paths

Parameters

paths

The paths to be freed. Should not be null.