bitablewrite.h File Reference

Interface for writing to a bitable. More...

#include "bitablecommon.h"

Go to the source code of this file.

Typedefs
typedef enum BitableCompletionOptions	BitableCompletionOptions
typedef struct BitableWritable	BitableWritable

Enumerations
enum	BitableCompletionOptions { BCO_NONE = 0, BCO_DURABLE = 1, BCO_DISCARD = 2 }

Functions
BITABLE_API BitableWritable *	bitable_write_allocate ()
BITABLE_API BitableResult	bitable_write_create (BitableWritable *table, const char *path, uint16_t pageSize, uint16_t keyAlignment, uint16_t dataAlignment)
BITABLE_API BitableResult	bitable_append (BitableWritable *table, const BitableValue *key, const BitableValue *data)
BITABLE_API BitableResult	bitable_writable_stats (const BitableWritable *table, BitableStats *stats)
BITABLE_API BitableResult	bitable_write_close (BitableWritable *table, BitableCompletionOptions options)
BITABLE_API void	bitable_write_free (BitableWritable *table)

Detailed Description

Interface for writing to a bitable.

Typedef Documentation

typedef enum BitableCompletionOptions BitableCompletionOptions

Options for completing (flushing) the bitable out to disk as it is closed.

typedef struct BitableWritable BitableWritable

A bitable that can be written to.

Enumeration Type Documentation

enum BitableCompletionOptions

Options for completing (flushing) the bitable out to disk as it is closed.

Enumerator
BCO_NONE	Bitable will be flushed out to the file system, with the header written last, however no syncs will be done so write order to storage is not guaranteed. Use this option if it's not important to be durable following a crash/power failure.
BCO_DURABLE	Bitable will be flushed out to file system and syncs done in the correct order such that completion is atomic and the rest of the bitable will be on storage before the final header is written out. Headers are checksum'd to guarantee that they are complete/correct.
BCO_DISCARD	Don't perform any completion writes, this bitable will not be used.

Function Documentation

BITABLE_API BitableResult bitable_append	(	BitableWritable *	table,
		const BitableValue *	key,
		const BitableValue *	data
	)

Append a key value pair to the bitable. Keys and pairs are always appended in key sorted order. Duplicate keys are not currently supported. It is the responsibility of the user to order the keys in the order matching the comparison function they will provide for reading. Only directly allocates memory when a new branch level is added. May block performing I/O.

Parameters

table	A writable bitable created with bitable_write_create for the key/value pair to be appended to. Should not be null.
key	The key of the key value pair to append. The key size needs to be less than BITABLE_MAX_KEY_SIZE. Should not be null.
data	The value data of the key value pair to append. Should not be null.

Returns

BR_SUCCESS if the table is successfully created. BR_KEY_INVALID if the key is not valid. BR_MAXIMUM_TABLE_TREE_DEPTH if the tree reaches its maximum depth. BR_FILE_OPERATION_FAILED or BR_FILE_OPEN_FAILED if a file operation fails.

BITABLE_API BitableResult bitable_writable_stats	(	const BitableWritable *	table,
		BitableStats *	stats
	)

Get the statistics associated with a particular bitable (including the number of items, depth, page size, key and value alignments etc).

Parameters

	table	The open readable bitable to get the stats from. Should not be null.
[out]	stats	The stats from the table. Should not be null.

Returns

BR_SUCCESS if the stats could successfully be retrieved.

BITABLE_API BitableWritable* bitable_write_allocate

(

)

Allocate a zeroed writable bitable, to be used with bitable_write_create (can be re-used multiple times).

Returns

The allocated writable bitable.

BITABLE_API BitableResult bitable_write_close	(	BitableWritable *	table,
		BitableCompletionOptions	options
	)

Close a writable bitable created with bitable_write_create. Does not free the memory associated with the writable bitable (that allocated by bitable_write_allocate). Optionally complete or discard the remaining writes required for the table.

Parameters

table	The writable bitable to close. Should not be null.
options	The options for completing (or discarding) the table on close.

Returns

BR_SUCCESS if the table is successfully completed/closed. BR_FILE_OPERATION_FAILED if file operations fail and prevent the completion of the bitable writes.

BITABLE_API BitableResult bitable_write_create	(	BitableWritable *	table,
		const char *	path,
		uint16_t	pageSize,
		uint16_t	keyAlignment,
		uint16_t	dataAlignment
	)

Create an empty bitable for writing.

Parameters

[out]	table	A writable bitable allocated with bitable_write_allocate that will be initialised with the parameters for the table. Should not be null.
	path	The path (UTF8 encoding) to create the bitable. This should be the main leaf/data file name. Should not be null.
	pageSize	The size of the page to use. Should be greater or equal to BITABLE_MIN_PAGE_SIZE and less than or equal to BITABLE_MAX_PAGE_SIZE. Should be a power of 2. Recommended to use a memory page size on your target platform.
	keyAlignment	The alignment that will be used for starting address of keys stored in the table. Needs to be greater than 0, less than BITABLE_MAX_ALIGNMENT and a power of 2.
	dataAlignment	The alignment that will be used for starting address of data value stored in the table. Needs to be greater than 0, less than BITABLE_MAX_ALIGNMENT and a power of 2.

Returns

BR_SUCCESS if the table is successfully created. BR_ALREADY_OPEN if the table is already open, BR_PAGESIZE_INVALID if pageSize is not a valid value, BR_ALIGNMENT_INVALID if keyAlignment or dataAlignment are invalid. BR_FILE_OPEN_FAILED, BR_BAD_PATH or BR_FILE_OPERATION_FAILED if a file operation means the file can not be created.

BITABLE_API void bitable_write_free

(

BitableWritable *

table

)

Free the allocated bitable. If the bitable has not been closed, the bitable is closed with the BCO_DISCARD option.

Parameters

table

The writable bitable to free. Should be allocated by bitable_write_allocate. Should not be null.