High Level Allocators

Many of the large data structures used in the library to store graphs or large blocks of dense data support using different allocators to provide their memory. This enables easy use of hugepages for large allocations or for direct memory mapping of files if the on-disk representation of the file is suitable.

Algorithms designed to accomodate multiple allocators are templated on the allocator type.

Standard Allocators

template<typename T>
class HugepageAllocator

#include <svs/core/allocator.h>

Allocator class to use hugepages to back memory allocations.

Public Functions

HugepageAllocator() = default

Construct a new allocator.

When default construction is used, the resulting allocator will be configured to use normal pages if sufficient huge pages are not available to fulfill an allocation.

inline explicit HugepageAllocator(bool force)

Construct a new HugepageAllocator.

If false, than normal 4 KiB will be used if huge pages are not available.

Parameters:

force – - If true, ensure that memory allocations are fulfilled with hugepages, throwing an exception if not enough pages are available.

class MemoryMapper

#include <svs/core/allocator.h>

Allocate memory for a data collection directly from a file using memory mapping.

Used by more file-aware allocators. Shouldn’t be invoked directly.

Public Types

enum Policy

Policy for file memory mapping.

Values:

enumerator MustUseExisting

Memory mapping must use an existing file. A new file will not be created.

enumerator MustCreate

Memory mapping must create a new file. An existing file cannot be used.

enumerator MayCreate

Memory mapping may either create a new file or use an existing one.

enum Permission

Permissions for the memory map.

Values:

enumerator ReadOnly

enumerator ReadWrite

Public Functions

inline explicit MemoryMapper(Permission permission = ReadOnly, Policy policy = MustUseExisting)

Construct a new MemoryMapper.

Parameters:

• permission – The permission for the file

• policy – The policy to use when memory mapping. If a situation arises that goes against the policy, an ANNException will be thrown when allocation is performed.

Helpers

template<typename T>
class MMapPtr

#include <svs/core/allocator.h>

A memory mapped smart pointer.

Contains the memory for an array of objects of type T. The memory pointed to will be freed when this object’s destructor is run. Objects of type T must be trivially default constructible and trivially copyable.

Template Parameters:

T – The element type of the array.

Public Functions

inline T *data() noexcept

Return a pointer to the start of valid memory held by the pointer.

inline const T *data() const noexcept

Return a pointer to the start of valid memory held by the pointer.

inline void *base() noexcept

Return the first addresses owned by the pointer.

This is not necessarily the start of the data region as instances are free to use an arbitrary amount of leading space in memory maps.

inline const void *base() const noexcept

Return the first addresses owned by the pointer.

This is not necessarily the start of the data region as instances are free to use an arbitrary amount of leading space in memory maps.

inline size_t size() const noexcept

Return the size (in bytes) of the total memory mapping.

inline void setoffset(size_t offset)

Configure the offset.

This sets the difference between data() and base().

inline MMapPtr(T *ptr, void *base, size_t size)

Construct a new MMapPtr around raw pointers.

The base pointer must have been obtained from a memory mapping. In other words, calling munmap on it must be valid.

Parameters:

• ptr – A pointer to the start of the valid (non-header) data for the mapping.

• base – The pointer returned by the memory mapping.

• size – The size (in bytes) of the total memory mapping (measured from base).

inline MMapPtr(void *base, size_t size)

Construct a new pointer with no data/base offset.