Container library#

This library provides basic building blocks to manage memory backing tensor locations. This library could be used like following:

#include <metalchat/container.h>

Memory container#

template<typename T> struct memory_container : public metalchat::basic_container#

Typed memory container interface. Extends basic_container with type-safe access to contiguous memory. All memory containers in the library derive from this template.

Example usage:

class custom_container : public memory_container<float> {
private:
    std::vector<float> _M_data;

public:
    pointer data()
    {
        return _M_data.data();
    }

    const_pointer data() const
    {
        return _M_data.data();
    }

    std::size_t size() const
    {
        return _M_data.size() * sizeof(float);
    }
};

Template Parameters:: T – The value type stored in the container.

Subclassed by metalchat::filebuf_memory_container< T >, metalchat::hardware_memory_container< T >, metalchat::offsetted_container_adapter< T >, metalchat::random_memory_container< T >, metalchat::scalar_memory_container< T >, metalchat::vector_memory_container< T >

Public Functions

virtual pointer data() = 0#: Get a write access to the underlying container data.

virtual const_pointer data() const = 0#: Get a read access to the underlying container data.

inline virtual void *data_ptr() override#: Get a type-erased write access to the underlying container data.

inline virtual const void *data_ptr() const override#: Get a type-erased read access to the underlying container data.

inline pointer operator*()#: Dereference operator for convenient access.

virtual ~memory_container() = default#: The memory_container virtual destructor.

Hardware memory container#

template<typename T> struct hardware_memory_container : public metalchat::memory_container<T>#

Container backed by Metal framework buffer (GPU memory).

Wraps Metal GPU buffers for use in the container system. Supports offset-based sub-views for efficient buffer slicing without copying.

Template Parameters:: T – The value type.

Public Functions

inline hardware_memory_container(const storage_type &storage, std::size_t offset = 0)#

Constructs a container from a Metal buffer.

Parameters:

storage – The Metal buffer.
offset – Byte offset from the buffer start (default: 0).

inline virtual std::size_t size() const#: Returns the size of the container in bytes.

inline virtual pointer data()#: Get a write access to the underlying container data.

inline virtual const_pointer data() const#: Get a read access to the underlying container data.

inline std::size_t storage_offset() const#: Returns the byte offset from the buffer start.

inline void *storage_ptr() const#: Returns a void pointer to the buffer data at the current offset.

Random memory container#

template<typename T> struct random_memory_container : public metalchat::memory_container<T>#

Container wrapping arbitrary memory allocated via shared_ptr.

This container provides a view over memory managed by a std::shared_ptr<void>. Supports offset-based sub-views of the same underlying storage.

Example usage:

// Allocate raw memory.
std::shared_ptr<void> storage = std::make_shared<float[]>(1024);

// Create container.
using Container = random_memory_container<float>;
auto container = std::make_shared<Container>(storage, 1024);

// Access data.
float* data = container->data();

// Create offset view of same storage.
auto offsetted_container = std::make_shared<Container>(storage, 512, 512);

Template Parameters:: T – The value type.

Public Functions

inline random_memory_container(const storage_type &storage, std::size_t size, std::size_t offset = 0)#

Constructs a container from shared storage.

Parameters:

storage – Shared pointer to the underlying memory.
size – Size of the accessible region in bytes.
offset – Byte offset from the storage start (default: 0).

inline virtual std::size_t size() const#: Returns the size of the container in bytes.

inline virtual pointer data()#: Get a write access to the underlying container data.

inline virtual const_pointer data() const#: Get a read access to the underlying container data.

inline std::size_t storage_offset() const#: Returns the byte offset from the storage start.

inline void *storage_ptr() const#: Returns a void pointer to the data at the current offset.

Vector memory container#

template<typename T> struct vector_memory_container : public metalchat::memory_container<T>#

Container backed by std::vector. Wraps a std::vector providing container interface.

Example usage:

auto storage = std::vector<int>({1, 2, 3, 4, 5});

using Container = vector_memory_container<int>;
auto container = std::make_shared<Container>(std::move(storage));

auto data_ptr = container->data();
auto data_size = container->size();

Template Parameters:: T – The value type.

Public Functions

inline vector_memory_container(storage_type &&storage)#

Constructs a container from an existing vector (moved).

Parameters:: storage – The vector to take ownership of.

inline vector_memory_container()#: Constructs an empty container.

inline virtual std::size_t size() const override#: Returns the size of the container in bytes.

inline virtual pointer data() override#: Get a write access to the underlying container data.

inline virtual const value_type *data() const override#: Get a read access to the underlying container data.

Scalar memory container#

template<typename T> struct scalar_memory_container : public metalchat::memory_container<T>#

Container holding a single scalar value.

This container wraps a single value of type T, providing the container interface. Useful for uniform treatment of scalar and array data.

Example usage:

using Container = scalar_memory_container<double>;
auto container = std::make_shared<Container>(3.14159);

auto data_ptr = container->data();
auto data_size = container->size();

Template Parameters:: T – The value type.

Public Functions

inline scalar_memory_container(const storage_type &storage)#

Constructs a container holding the given value.

Parameters:: storage – The value to store.

inline virtual std::size_t size() const#: Returns the size of the container in bytes.

inline virtual pointer data()#: Get a write access to the underlying container data.

inline virtual const_pointer data() const#: Get a read access to the underlying container data.

File buffer container#

template<typename T> struct filebuf_memory_container : public metalchat::memory_container<T>#

A container that keeps data within a temporary file.

When users need to get read (or write) access to the file, it’s mapped to the memory and remains mapped, until filebuf_memory_container::park method is called.

Example usage:

auto storage = std::vector<float>({1.0f, 2.0f, 3.0f});

using Container = filebuf_memory_container<float>;
auto container = std::make_shared<Container>(data.data(), data.size() * sizeof(float));

// Maps file to memory.
auto data_ptr = container->data();

// Evict from memory when not needed.
container->park();

Template Parameters:: T – The value type.

Public Functions

inline filebuf_memory_container(const_pointer data, std::size_t size)#

Constructs a new instance of a file-buffered container and initializes it with the provided data. After construction file is not mapped into the memory.

Parameters:

data – Pointer to the source data to write to file.
size – Size of the data in bytes.

inline filebuf_memory_container(const storage_type &storage, std::size_t size, std::size_t offset)#

Constructs a container from existing file storage.

Parameters:

storage – Shared pointer to the underlying file.
size – Size of the accessible region in bytes.
offset – Byte offset from the file start.

inline void park() const#: Method evicts memory-mapped file from the memory. When the file is not memory-mapped method does absolutely nothing, so calling method multiple time is safe.

inline void unpark() const#: Maps the file into memory if not already mapped.

inline virtual std::size_t size() const#: Returns the size of the container in bytes.

inline virtual pointer data()#: Get a write access to the underlying container data.

inline virtual const_pointer data() const#: Get a read access to the underlying container data.

inline std::size_t storage_offset() const#: Returns the byte offset from the file start.

inline void *storage_ptr() const#: Returns a void pointer to the data at the current offset. Automatically maps the file into memory if needed.

Offsetted container adapter#

template<typename T> class offsetted_container_adapter : public metalchat::memory_container<T>#

Adapter that creates offset views of any memory container.

This adapter wraps an existing memory_container and provides an offsetted view without copying data. Unlike container-specific offset implementations, this works with any memory_container subclass. The offsetted_container_adapter shares ownership of the wrapped memory container.

Example usage:

using Container = vector_memory_container<int>;
auto storage = std::vector<int32_t>({1, 2, 3, 4, 5});
auto container_ptr = std::make_shared<Container>(storage);

// Create view starting at byte offset 8 (skipping first 2 integers)
using View = offsetted_container_adapter<int32_t>;
auto view = std::make_shared<View>(container_ptr, 8);

// Points to element `storage[2]`.
int* p = container_view->data();

// Returns size of `storage` minus 8 bytes (2 integers).
std::size_t size = container_view->size();

Template Parameters:: T – The value type.

Public Functions

inline offsetted_container_adapter(const storage_type &storage, std::size_t offset)#

Constructs an offset adapter from an existing container.

Parameters:

storage – Shared pointer to the base container.
offset – Byte offset from the base container’s start.

inline virtual pointer data()#: Get a write access to the underlying container data.

inline virtual const_pointer data() const#: Get a read access to the underlying container data.

inline virtual std::size_t size() const#: Returns the size of the container in bytes.

Container concepts#

template<typename Container> concept contiguous_container#

#include <container.h>

Concept defining requirements for contiguous memory containers. A container satisfies this concept if it:

Derives from memory_container<T>.
Defines value_type, pointer, const_pointer, and storage_type.
Provides a storage() method returning const reference to storage_type.

tparam Container:: The container type to check.

template<contiguous_container> struct container_remove_type#

Template for removing the value type from a container.

Specialized for each container type to create a void-typed version.

Template Parameters:: Container – The container type.

template<contiguous_container> struct container_offset#

Template for creating offset views of containers.

Specialized for each container type to enable creating sub-views at specific byte offsets.

Template Parameters:: Container – The container type.

template<typename T, contiguous_container Container> struct container_rebind#

Template for rebinding container types to different value types.

Specialized for each container type to enable type conversion while preserving the underlying storage.

Template Parameters:

T – The new value type.
Container – The container type to rebind.

template<contiguous_container Container> struct container_traits#

This template class provides the standardized way to access various properties of contiguous_container. The library allocators and other components access containers through this template.

Template Parameters:: Container – a contiguous memory container type.

Public Types

using container_type = Container #: A type of the container.

using container_pointer = std::shared_ptr<container_type>#: A shared pointer type of the container.

using value_type = container_type::value_type#: A value type of the container’s underlying type.

using pointer = container_type::pointer#: A pointer type of the container’s underlying type.

using const_pointer = const container_type::pointer#: A const pointer type of the container’s underlying type.

using void_pointer = void*#: A void pointer type.

using const_void_pointer = const void*#: A const void pointer type.

template<typename T> using rebind_container = container_rebind<T, Container>::type#: Container type after type rebinding.

template<typename T> using rebind_traits = container_traits<rebind_container<T>>#: Container traits of the rebind container type.

using offset_container = container_offset<container_type>::type#: Container type after storage offset.

using offset_traits = container_traits<offset_container>#: Container traits of the offset container type.

Public Static Functions

static inline const_void_pointer begin(const container_type &container)#

Returns a pointer to the beginning of the container underlying storage.

Parameters:: container – A contiguous memory container.

static inline const_void_pointer begin(const container_pointer &container_ptr)#

Returns a pointer to the beginning of the container underlying storage.

Parameters:: container_ptr – A pointer to the contiguous memory container.

static inline const_void_pointer end(const container_type &container)#

Returns a pointer to the end (i.e. the element after the last element) of the container underlying storage.

Parameters:: container – A contiguous memory container.

static inline const_void_pointer end(const container_pointer &container_ptr)#

Returns a pointer to the end of the container underlying storage.

Parameters:: container_ptr – A pointer to the contiguous memory container.

static inline bool contains(const container_type &container, const_void_pointer ptr)#

Checks whether or not a given container contains the specified pointer.

Parameters:

container – A contiguous memory container.
ptr – A pointer that is checked.

static inline bool contains(const container_type &container, const_void_pointer first, std::size_t size)#

Checks whether or not a given container contains the specified range contiguous memory.

Parameters:

container – A contiguous memory container.
first – A start position of the contiguous memory.
size – A size of the contiguous memory.

static inline bool contains(const container_pointer &container_ptr, const_void_pointer first, std::size_t size)#

Checks whether or not a given container contains the specified range contiguous memory.

Parameters:

container_ptr – A pointer to a contiguous memory container.
first – A start position of the contiguous memory.
size – A size of the contiguous memory.

Public Static Attributes

template<typename T> static constexpr auto rebind = container_rebind<T, Container>::rebind#: A template method to rebind container type, when logic is present.

static constexpr auto offset = container_offset<Container>::offset#: A method to shift container type, when logic is present.