scsl::Arena Class Reference

Fixed, pre-allocated memory. More...

#include <Arena.h>

Public Member Functions
	Arena ()
	An Arena is initialized with no backing memory.
	~Arena ()
int	SetStatic (uint8_t *mem, size_t memSize)
int	SetAlloc (size_t allocSize)
int	MemoryMap (int memFileDes, size_t memSize)
int	Create (const char *path, size_t fileSize)
int	Open (const char *path)
uint8_t *	Start () const
uint8_t *	End ()
bool	CursorInArena (const uint8_t *cursor)
size_t	Size () const
ArenaType	Type () const
bool	Ready () const
	Ready returns whether the arena is initialized.
void	Clear ()
	Clear zeroizes the memory in the arena.
void	Destroy ()
int	Write (const char *path)
uint8_t &	operator[] (size_t index)

Detailed Description

Fixed, pre-allocated memory.

The Arena uses the concept of a cursor to point to memory in the arena. The Start and End methods return pointers to the start and end of the arena memory.

The arena should be initialized with one of the Set methods (SetStatic, SetAlloc) or one of the file-based options (Create, Open, MemoryMap). At this point, no further memory management should be done until the end of the arena's life, At which point Destroy should be called.

Constructor & Destructor Documentation

Arena()

scsl::Arena::Arena

(

)

An Arena is initialized with no backing memory.

~Arena()

scsl::Arena::~Arena

(

)

Member Function Documentation

Clear()

void scsl::Arena::Clear

(

)

Clear zeroizes the memory in the arena.

Create()

int scsl::Arena::Create	(	const char *	path,
		size_t	fileSize
	)

Create creates a new file, truncating it if it already exists. On Unix-based platforms, the arena will be backed by a memory via MemoryMap. On other platforms (e.g. Windows), the arena will read the file into an allocated arena, calling SetAlloc.

Parameters

path	The path to the file that should be created.
fileSize	The size of the file to create.

Returns

Returns 0 on success and -1 on error.

CursorInArena()

bool scsl::Arena::CursorInArena

(

const uint8_t *

cursor

)

CursorInArena checks whether the cursor is still in the arena.

Parameters

cursor

A pointer that ostensibly points to the arena's memory.

Returns

True if the cursor is still in the arena.

Destroy()

void scsl::Arena::Destroy

(

)

Destroy removes any backing memory (e.g. from SetAlloc or MemoryMap). This does not call Clear; if the arena was backed by a file that should be persisted, it would wipe out the file.

End()

uint8_t * scsl::Arena::End ( )

inline

End returns a pointer to the end of the arena memory.

Returns

A pointer to the end of the arena memory.

MemoryMap()

int scsl::Arena::MemoryMap ( int  memFileDes, size_t  memSize  )

inline

MemoryMap points the arena to a memory-mapped file. This is currently only supported on Linux. If the arena is already backed, then Destroy will be called first.

Parameters

memFileDes	File descriptor to map into memory.
memSize	The size of memory to map.

Returns

Returns 0 on success and -1 on error.

Open()

int scsl::Arena::Open

(

const char *

path

)

Open reads a file into the arena; the file must already exist. On Unix-based platforms, the arena will be backed by a memory via MemoryMap. On other platforms (e.g. Windows), the arena will read the file into an allocated arena, calling SetAlloc. On these platforms, in order to persist changes, Write must be called to sync changes to disk.

Parameters

path	The path to the file to be loaded.

Returns

Returns 0 on success and -1 on error.

operator[]()

uint8_t & scsl::Arena::operator[]

(

size_t

index

)

This operator allows the data in the arena to be accessed as if it were an array. If the index is out of bounds, it will throw a range_error.

Exceptions

std::range_error.

Parameters

index

The index to retrieve.

Returns

Ready()

bool scsl::Arena::Ready ( ) const

inline

Ready returns whether the arena is initialized.

SetAlloc()

int scsl::Arena::SetAlloc

(

size_t

allocSize

)

SetAlloc allocates a chunk of memory for the arena; the arena takes ownership. If the arena is already backed, then Destroy will be called first.

Parameters

allocSize

The size of memory to allocate.

Returns

Returns 0 on success and -1 on error.

SetStatic()

int scsl::Arena::SetStatic	(	uint8_t *	mem,
		size_t	memSize
	)

SetStatic points the arena to a chunk of memory. That memory is intended to be statically allocated, e.g. via a global static uint8_t memory[memSize];. If the arena is already backed, then Destroy will be called first.

Parameters

mem	A pointer to a section of memory, preferably statically allocated.
memSize	The size of the memory section.

Returns

Returns 0 on success and -1 on error.

Size()

size_t scsl::Arena::Size ( ) const

inline

Returns the current size of the arena.

Returns

The size of the arena.

Start()

uint8_t * scsl::Arena::Start ( ) const

inline

Start returns a pointer to the start of the memory in the arena.

Returns

A pointer to the start of the arena memory.

Type()

ArenaType scsl::Arena::Type ( ) const

inline

Type returns an ArenaType describing the arena.

Returns

An ArenaType describing the backing memory for the arena.

Write()

int scsl::Arena::Write

(

const char *

path

)

Write dumps the arena to a file suitable for loading by Open.

Warning

DANGER: if arena is memory-mapped, DO NOT WRITE TO THE BACKING FILE!

Parameters

path

Returns

Returns 0 on success and -1 on error.

---

The documentation for this class was generated from the following file:

• include/scsl/Arena.h