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::ReadMemory ImebraReadMemory Allows to read the memory content
imebra::ReadWriteMemory ImebraReadWriteMemory 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.

Memory related classes

Class diagram of the memory classes

Memory access

ReadMemory

C++

class ReadMemory

Manages a read-only buffer of memory.

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

The memory used by ReadMemory and ReadWriteMemory is managed by MemoryPool.

Subclassed by imebra::ReadWriteMemory

Public Functions

ReadMemory()

Construct an empty buffer of memory.

ReadMemory(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).

Python

In Python this method accepts a single parameter (an array).

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

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.

Python

In Python this method accepts a single parameter (an array). The size of the array (in bytes) 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)

Python

In Python this method accepts two parameters:

  • an array
  • an 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 ReadMemory 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 ImebraReadMemory : 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 ImebraReadWriteMemory is managed by ImebraMemoryPool.

Subclassed by ImebraReadWriteMemory

Public Functions

id ImebraReadMemory::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 ImebraReadMemory::empty

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

ReadWriteMemory

C++

class ReadWriteMemory : public imebra::ReadMemory

Manages a writable buffer of memory.

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

The memory used by ReadMemory and ReadWriteMemory is managed by MemoryPool.

Public Functions

ReadWriteMemory()

Construct an empty buffer of memory.

The memory can be resized later with resize().

ReadWriteMemory(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

ReadWriteMemory(const ReadMemory &sourceMemory)

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

Parameters
  • sourceMemory: the object containing the initial memory’s content

ReadWriteMemory(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).

Python

In Python this method accepts a single parameter (an array).

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

void copyFrom(const ReadMemory &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 ReadWriteMemory object and must not be freed by the client.

Return
a pointer to the referenced memory. The referenced buffer is owned by the ReadWriteMemory 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 ReadWriteMemory object.

Java

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

Python

In Python this method accepts a single parameter (an 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 ReadWriteMemory.

The memory size remains unchanged.

Java

In Java this method accepts two parameters:

  • a byte array
  • a long integer (destinationOffset)

Python

In Python this method accepts two parameters:

  • an array
  • an integer (destinationOffset)

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

Objective-C/Swift

class ImebraReadWriteMemory : public ImebraReadMemory

Manages a writable buffer of memory.

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

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

Public Functions

id init()

Construct an empty buffer of memory.

The memory can be resized later with resize().

id ImebraReadWriteMemory::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 ImebraReadWriteMemory::initWithMemory:(ImebraReadMemory * source)

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

Parameters
  • source: the object containing the initial memory’s content

id ImebraReadWriteMemory::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 ImebraReadWriteMemory::copyFrom:error:(ImebraReadMemory * 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 ImebraReadWriteMemory::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 ImebraReadWriteMemory::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 ImebraReadWriteMemory::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 ImebraReadWriteMemory::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