palloc.c

Simple embeddable persistent-allocation library for C

Allows your program to allocate and iterate over persistently allocated blobs of data within a file or other file-like medium.

This library is designed to be simple (to use), not to break any speed records. While performance improvements are welcome, keep simplicity in mind when making contributions.

Example

// Pre-open the file descriptor palloc will be operating on
int fd = palloc_open("path/to/file.db", PALLOC_DEFAULT | PALLOC_DYNAMIC);
palloc_init(fd, PALLOC_DEFAULT);

// Fetch the first allocated blob
PALLOC_OFFSET first = palloc_next(fd, 0);

// Fetch the second allocated blob
PALLOC_OFFSET second = palloc_next(fd, first);

// Allocate a new blob of 1024 bytes
PALLOC_OFFSET third = palloc(fd, 1024);

// Free the first blob
pfree(fd, first);

// Close file descriptor and clear internal cache on it
palloc_close(fd);

Installation

This library makes use of dep to manage it's dependencies and exports.

dep add finwo/palloc

Dependencies:

• finwo/assert
• finwo/canonical-path
• finwo/endian

API

Definitions - Flags

PALLOC_DEFAULT

Default flags to initialize palloc with, in case some compatibility flags are required after a future update.

#define PALLOC_DEFAULT 0

PALLOC_DYNAMIC

Indicates a storage medium to be initialized as being dynamic. This flag is overridden by the medium if the medium has already been initialized.

#define PALLOC_DYNAMIC 1

PALLOC_SYNC

During the initialization, open the medium in DSYNC (or os' equivalent) mode to provide some minor protection against things like power failures or disconnects.

#define PALLOC_SYNC 2

PALLOC_EXTENDED

Reserved flag for future use if the current reserved space for flags becomes unsufficient.

#define PALLOC_EXTENDED (1<<31)

Definitions - Types

PALLOC_FD

A reference to how the file descriptors for palloc look like

#define PALLOC_FD int

PALLOC_FLAGS

A reference to how the file descriptors for palloc look like

#define PALLOC_FLAGS uint32_t

PALLOC_RESPONSE

Common return-type, indicating errors and such

#define PALLOC_RESPONSE int

PALLOC_OFFSET

Indicates an offset within the file descriptor

#define PALLOC_OFFSET uint64_t

PALLOC_SIZE

Indicates an size within the file descriptor

#define PALLOC_SIZE uint64_t

Definitions - Responses

PALLOC_OK

Indicates no error was encountered

#define PALLOC_OK (0)

PALLOC_ERR

Indicates a generic error without specification

#define PALLOC_ERR (-1)

Methods

palloc_open(filename, flags)

Opens a palloc medium and returns it as a file descriptor both palloc and the user can use.

PALLOC_FD palloc_open(const char *filename, PALLOC_FLAGS flags);

palloc_init(fd, flags)

Initializes a pre-opened medium for use with palloc if not already initialized

PALLOC_RESPONSE palloc_init(PALLOC_FD fd, PALLOC_FLAGS flags);

palloc_close(fd)

Closes a pre-opened file descriptor

PALLOC_RESPONSE palloc_close(PALLOC_FD fd);

palloc(fd,size)

Allocates a new blob of the given size in the storage medium and returns an offset to the start of the data section you can use for your storage purposes.

PALLOC_OFFSET palloc(PALLOC_FD fd, PALLOC_SIZE size);

pfree(fd,ptr)

Marks the blob pointed to by ptr as being unused, allowing it to be re-used for future allocations and preventing it from being returned during iteration.

PALLOC_RESPONSE pfree(PALLOC_FD fd, PALLOC_OFFSET ptr);

palloc_size(fd,ptr)

Returns the real size of the data section of the allocated blob pointed to by ptr, not the originally requested size.

PALLOC_SIZE palloc_size(PALLOC_FD fd, PALLOC_OFFSET ptr);

palloc_next(pt, ptr)

Returns an offset to the data section of the next allocated blob within the descriptor based on the offset to a data section indicated by ptr, or 0 if no next allocated blob exists.

PALLOC_OFFSET palloc_next(PALLOC_FD fd, PALLOC_OFFSET ptr);

File structure

• header
  • 4B header "PBA\0"
  • uint16_t flags
• blobs
  • 8B free + size
• size indicator: data only, excludes size indicator itself
• free flag:
  • 1 = free
  • 0 = occupied
• blob structure:
  • free:
    • 8B size | flag
    • 8B pointer previous free block (0 = no previous free block)
    • 8B pointer next free block (0 = no next free block)
    • 8B size | flag
  • occupied:
    • 8B size
    • <data[n]>
    • 8B size