Memory management classes¶

Introduction¶

This chapter describes the classes and methods responsible for allocating and accessing the memory used by the Imebra classes.

The following classes are described in this chapter:

C++ class	Objective-C/Swift class	Description
`imebra::Memory`	`ImebraMemory`	Allows to read the memory content
`imebra::MutableMemory`	`ImebraMutableMemory`	Allows to read and write the memory content
`imebra::MemoryPool`	`ImebraMemoryPool`	Allocatess or reuse a memory block

The inner working classes of the Imebra library use the MemoryPool class to allocate blocks of memory.

When a memory block allocated by MemoryPool is released then it is not deleted immediately but instead it is kept for a while so it can be reused by classes than need a similar amount of memory.

Class diagram of the memory classes¶

Memory access¶

Memory¶

C++¶

class Memory¶

Manages a read-only buffer of memory.

The buffer of memory is usually associated with a Tag buffer content.

The memory used by Memory and MutableMemory is managed by MemoryPool.

Subclassed by imebra::MutableMemory

Public Functions

Memory()¶: Construct an empty buffer of memory.

Memory(const char *source, size_t sourceSize)¶

Construct a buffer of memory and copy the specified content into it.

Java

In Java this method accepts a single parameter (a byte array).

Parameters

source: a pointer to the source data
sourceSize: the amount of data to copy into the allocated memory

Memory(const Memory &source)¶

Copy constructor.

Parameters

source: source Memory object

size_t size() const¶

Return the memory size, in bytes.

Return: the memory size in bytes

size_t data(char *destination, size_t destinationSize) const¶

Copies the raw memory content into the specified buffer.

If the allocated buffer is not large enough then the method doesn’t copy any data and just returns the required buffer’ size.

Java

In Java this method accepts a single parameter (a byte array). The size of the byte array must be equal or greater than the number of bytes stored by the data handler.

Return

the number of bytes copied into the pre-allocated buffer, or the desired size of destination if destinationSize is smaller than the return value

Parameters

destination: a pointer to the allocated buffer
destinationSize: the size of the allocated buffer, in bytes

void regionData(char *destination, size_t destinationSize, size_t sourceOffset) const¶

Copies the raw memory region into the specified buffer.

If the memory’s size is too small to extract the requested region then throws MemorySizeError.

Java

In Java this method accepts two parameters:

a byte array
a long integer (sourceOffset)

Parameters

destination: a pointer to the allocated buffer
destinationSize: the size of the allocated buffer, in bytes
sourceOffset: the offset

const char *data(size_t *pDataSize) const¶

Return a pointer to the constant referenced memory.

The referenced buffer is owned by the ReadMemory object and must not be freed by the client.

Return

a pointer to the referenced memory. The referenced buffer is owned by the Memory object and must not be freed by the client.

Parameters

pDataSize: pointer to a variable that will be filled with the memory size, in bytes

bool empty() const¶

Return true if the referenced memory is zero bytes long or hasn’t been allocated yet.

Return: true if the referenced memory does not exist or is empty

Objective-C/Swift¶

class ImebraMemory : public NSObject¶

Manages a read-only buffer of memory.

The buffer of memory is usually associated with a ImebraTag buffer content.

The memory used by ImebraReadMemory and ImebraMutableMemory is managed by ImebraMemoryPool.

Subclassed by ImebraMutableMemory

Public Functions

id ImebraMemory::initWithData:(NSData * source)

Construct a buffer of memory and copy the specified content into it.

Parameters

source: a pointer to the source data

NSData *data()¶

Copies the raw memory content into a NSData object and returns it.

Return: a NSData containing a copy of the memory managed by ImebraReadMemory

Property

property ImebraMemory::empty: Return true if the referenced memory is zero bytes long or hasn’t been allocated yet.

MutableMemory¶

C++¶

class MutableMemory : public imebra::Memory ¶

Manages a writable buffer of memory.

The buffer of memory is usually associated with a Tag buffer content.

The memory used by Memory and MutableMemory is managed by MemoryPool.

Public Functions

MutableMemory()¶

Construct an empty buffer of memory.

The memory can be resized later with resize().

MutableMemory(size_t initialSize)¶

Construct a buffer of memory of the specified size.

The memory can be resized later with resize().

Parameters

initialSize: the initial memory’s size, in bytes

MutableMemory(const Memory &sourceMemory)¶

Construct a buffer of memory and copy the specified content into it.

Parameters

sourceMemory: the object containing the initial memory’s content

MutableMemory(const MutableMemory &source)¶

Copy constructor.

Parameters

source: source MutableMemory object

MutableMemory(const char *source, size_t sourceSize)¶

Construct a buffer of memory and copy the specified content into it.

Java

In Java this method accepts a single parameter (a byte array).

Parameters

source: a pointer to the source data
sourceSize: the amount of data to copy into the allocated memory

void copyFrom(const Memory &sourceMemory)¶

Copy the content from another memory object.

Parameters

sourceMemory: the source memory object

void clear()¶: Resize the memory to zero bytes.

void resize(size_t newSize)¶

Resize the memory.

Parameters

newSize: the new memory size, in bytes

void reserve(size_t reserveSize)¶

Reserve the specified amount of bytes, without changing the memory size.

Parameters

reserveSize: the number of bytes to reserve

char *data(size_t *pDataSize) const¶

Return a pointer to the referenced memory.

The referenced buffer is owned by the MutableMemory object and must not be freed by the client.

Return

a pointer to the referenced memory. The referenced buffer is owned by the MutableMemory object and must not be freed by the client.

Parameters

pDataSize: pointer to a variable that will be filled with the memory size, in bytes

void assign(const char *source, size_t sourceSize)¶

Copy the content of the specified buffer into the MutableMemory object.

Java

In Java this method accepts a single parameter (a byte array).

Parameters

source: a pointer to the source memory buffer
sourceSize: the number of bytes to copy and the new memory size

void assignRegion(const char *source, size_t sourceSize, size_t destinationOffset)¶

Copy the content of the specified buffer into a region of the MutableMemory.

The memory size remains unchanged.

Java

In Java this method accepts two parameters:

a byte array
a long integer (destinationOffset)

Parameters

source: a pointer to the source memory buffer
sourceSize: the number of bytes to copy
destinationOffset: the offset into the MutableMemory at which the data must be copied

Objective-C/Swift¶

class ImebraMutableMemory : public ImebraMemory ¶

Manages a writable buffer of memory.

The buffer of memory is usually associated with a tag buffer content.

The memory used by ImebraReadMemory and ImebraMutableMemory is managed by ImebraMemoryPool.

Public Functions

id init()¶

Construct an empty buffer of memory.

The memory can be resized later with resize().

id ImebraMutableMemory::initWithSize:(unsigned int size)

Construct a buffer of memory of the specified size.

The memory can be resized later with resize().

Parameters

size: the initial memory’s size, in bytes

id ImebraMutableMemory::initWithMemory:(ImebraMemory * source)

Construct a buffer of memory and copy the specified content into it.

Parameters

source: the object containing the initial memory’s content

id ImebraMutableMemory::initWithData:(NSData * pSource)

Construct a buffer of memory and copy the specified content into it.

Parameters

pSource: the object containing the initial memory’s content

void ImebraMutableMemory::copyFrom:error:(ImebraMemory * source, (swift_error(nonnull_error)) __attribute__)

Copy the content from another memory object.

Parameters

source: the source memory object
pError: set to a NSError derived class in case of error

void ImebraMutableMemory::clear:((swift_error(nonnull_error)) __attribute__)

Resize the memory to zero bytes.

Parameters

pError: set to a NSError derived class in case of error

void ImebraMutableMemory::resize:error:(unsigned int newSize, (swift_error(nonnull_error)) __attribute__)

Resize the memory.

Parameters

newSize: the new memory size, in bytes
pError: set to a NSError derived class in case of error

void reserve(size_t reserveSize)¶

Reserve the specified amount of bytes, without changing the memory size.

Parameters

reserveSize: the number of bytes to reserve
pError: set to a NSError derived class in case of error

void ImebraMutableMemory::assign:error:(NSData * pSource, (swift_error(nonnull_error)) __attribute__)

Copy the content of the specified buffer into the ReadWriteMemory object.

Parameters

pSource: a pointer to the source memory buffer
pError: set to a NSError derived class in case of error

void ImebraMutableMemory::assignRegion:offset:error:(NSData * pSource, unsigned int destinationOffset, (swift_error(nonnull_error)) __attribute__)

Copy the content of the specified buffer into a region of the ReadWriteMemory.

The memory size remains unchanged.

Parameters

pSource: a pointer to the source memory buffer
destinationOffset: the offset into the ReadWriteMemory at which the data must be copied
pError: set to a NSError derived class in case of error

Memory allocation¶

MemoryPool¶

C++¶

class MemoryPool¶

Used by Imebra to allocate memory.

MemoryPool keeps around recently deleted memory regions so they can be repurposed quickly when new memory regions are requested.

Each thread has its own MemoryPool object.

Public Static Functions

static void flush()¶: Release all the unused memory regions.

static size_t getUnusedMemorySize()¶

Return the total size of the memory that has been released but not yet freed.

Return: the total size of the memory released but not yet freed

static void setMemoryPoolSize(size_t minMemoryBlockSize, size_t maxMemoryPoolSize)¶

Set the maximum size of the kept unused memory.

Parameters

minMemoryBlockSize: if a memory region is smaller than this size then when it is released it is deleted immediately, otherwise it is kept in the memory pool
maxMemoryPoolSize: the maximum size of the sum of all the unused memory regions. When the total size of the unused memory regions is greater than this parameter then the oldest memory regions are deleted permanently

Objective-C/Swift¶

class ImebraMemoryPool : public NSObject¶

Public Static Functions

void flush()¶: Release all the unused memory regions.

unsigned int getUnusedMemorySize()¶

Return the total size of the memory that has been released but not yet freed.

Return: the total size of the memory released but not yet freed

void ImebraMemoryPool::setMemoryPoolSize:maxSize:(unsigned int minMemoryBlockSize, unsigned int maxMemoryPoolSize)

Set the maximum size of the kept unused memory.

Parameters

minMemoryBlockSize: if a memory region is smaller than this size then when it is released it is deleted immediately, otherwise it is kept in the memory pool
maxMemoryPoolSize: the maximum size of the sum of all the unused memory regions. When the total size of the unused memory regions is greater than this parameter then the oldest memory regions are deleted permanently