Region Format

Classes
struct	clod_rfmt_opts

Typedefs
typedef bool	clod_rfmt_file_sync(size_t size, void *user)

Enumerations
enum	clod_rfmt_result {   CLOD_RFMT_OK = 0 , CLOD_RFMT_ALLOCATION_FAILURE = 1 , CLOD_RFMT_TIMEOUT = 2 , CLOD_RFMT_OTHER = 3 ,   CLOD_RFMT_INVALID = 4 , CLOD_RFMT_MISUSE = 5 , CLOD_RFMT_OTHER_MISUSE = 6 , CLOD_RFMT_FILE_MANAGE_ERROR = 7 ,   CLOD_RFMT_FILE_SYNC_ERROR = 8 }

Functions
enum clod_rfmt_result	clod_rfmt_init_new (struct clod_rfmt **rfmt_out, struct clod_rfmt_opts *opts, char *chunk_filename_prefix, char *chunk_filename_extension, uint32_t sector_size)
enum clod_rfmt_result	clod_rfmt_init_rw (struct clod_rfmt **rfmt_out, struct clod_rfmt_opts *opts)
enum clod_rfmt_result	clod_rfmt_init_ro (struct clod_rfmt **rfmt_out, struct clod_rfmt_opts *opts)
enum clod_rfmt_result	clod_rfmt_free (struct clod_rfmt *rfmt)
enum clod_rfmt_result	clod_rfmt_lock_acquire (struct clod_rfmt *rfmt, uint32_t index)
enum clod_rfmt_result	clod_rfmt_lock_refresh (struct clod_rfmt *rfmt, uint32_t index)

Detailed Description

Methods for reading and writing to region files. None of the methods here are thread safe; for concurrent usage each thread must independently create its own handle to the same region file.

When the NDEBUG flag is not set (i.e. in debug builds), additional checks are performed to ensure that usage follows the file specification e.g. holding required locks before certain accesses.

Typedef Documentation

clod_rfmt_file_sync

typedef bool clod_rfmt_file_sync(size_t size, void *user)

Method provided by the user that is used to synchronise the file to disk. This method does not need external synchronisation as it is only called with the protection of the file lock.

Parameters

[in]	size	Size of the section of the file from the start to synchronise.
[in]	user	The provided user pointer.

Returns

True if the operation was successful, false if not.

Definition at line 31 of file region_format.h.

Enumeration Type Documentation

clod_rfmt_result

enum clod_rfmt_result

Result of an operation.

Enumerator
CLOD_RFMT_OK	No worries.
CLOD_RFMT_ALLOCATION_FAILURE	Memory allocation failure.
CLOD_RFMT_TIMEOUT	The provided timeout was reached.
CLOD_RFMT_OTHER	Other error.
CLOD_RFMT_INVALID	Invalid parameters.
CLOD_RFMT_MISUSE	The operation is not allowed to be performed in the current state. This typically indicates that a required lock was not held. Many checks which return this value are configurable, and may not be included in release builds. The return of this result indicates a critical bug in the library user.
CLOD_RFMT_OTHER_MISUSE	Someone else is interacting with the region file in a way which causes corruption and permanent data loss, or there is a critical bug in this library. The return of this error likely means data loss has already occurred. The implementation that caused this error needs to be fixed.
CLOD_RFMT_FILE_MANAGE_ERROR	The provided file_manage method indicated an error or returned invalid values.
CLOD_RFMT_FILE_SYNC_ERROR	The provided file_sync method indicated an error.

Definition at line 39 of file region_format.h.

Function Documentation

clod_rfmt_init_new()

enum clod_rfmt_result clod_rfmt_init_new	(	struct clod_rfmt **	rfmt_out,
		struct clod_rfmt_opts *	opts,
		char *	chunk_filename_prefix,
		char *	chunk_filename_extension,
		uint32_t	sector_size )

Create a new region file in read/write mode.

Parameters

[out]	rfmt_out	Handle to the region file.
[in]	opts	Configuration options for the opened file.
[in]	chunk_filename_prefix	Filename prefix for chunk files.
[in]	chunk_filename_extension	Filename extension for chunk files.
[in]	sector_size	Size fo sectors in the file. Ideally a multiple of system page size.

Returns

Handle to the file.

Definition at line 48 of file format.c.

clod_rfmt_init_rw()

enum clod_rfmt_result clod_rfmt_init_rw	(	struct clod_rfmt **	rfmt_out,
		struct clod_rfmt_opts *	opts )

Initialise a region file for read/write interaction.

Parameters

[out]	rfmt_out	Handle to the region file.
[in]	opts	Configuration options for the opened file.

Returns

Handle to the region file.

Definition at line 71 of file format.c.

clod_rfmt_init_ro()

enum clod_rfmt_result clod_rfmt_init_ro	(	struct clod_rfmt **	rfmt_out,
		struct clod_rfmt_opts *	opts )

Initialise a region file for read-only interaction.

Parameters

[out]	rfmt_out	Handle to the region file.
[in]	opts	Configuration options for the opened file.

Returns

Handle to the region file.

Definition at line 76 of file format.c.

clod_rfmt_free()

enum clod_rfmt_result clod_rfmt_free

(

struct clod_rfmt *

rfmt

)

Release resources associated with the file handle.

Parameters

[in]

rfmt

The file handle to free.

Returns

Result of any cleanup operations.

Definition at line 33 of file format.c.