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.

Memory related classes

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

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

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.

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

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

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

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 MutableMemory.

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