xentara-plugin v1.2.1
The Xentara Plugin Framework
Loading...
Searching...
No Matches
xentara::memory::MemoryResource Class Referenceabstract

A concept used for classes that can be used as memory resources. More...

#include <memory/MemoryResource.hpp>

+ Inheritance diagram for xentara::memory::MemoryResource:

Classes

class  BlockHandler
 Base class for handlers that perorm certain operations on a block. More...
 
class  Handle
 A handle used to access a memory block within a memory resource. More...
 

Public Types

enum class  HandleRole { Generic , Read , Write }
 different roles for handles More...
 
using BlockHandle = Handle< HandleRole::Generic >
 A handle used to refer to a memory block.
 
using ReadHandle = Handle< HandleRole::Read >
 A handle used to perform synchronized reads from a memory block.
 
using WriteHandle = Handle< HandleRole::Write >
 A handle used to perform synchronized writed to a memory block.
 

Public Member Functions

virtual ~MemoryResource ()=0
 Virtual destructor.
 
Creating and Destroying Memory Blocks
auto createBlock (std::reference_wrapper< const BlockHandler > handler) -> std::pair< BlockHandle, void * >
 Creates a memory block.
 
auto destroyBlock (const BlockHandle &blockHandle) noexcept -> void
 Destroys a memory block.
 
auto placement (const BlockHandle &blockHandle) const noexcept -> void *
 Recovers the current placement of a memory block without synchronization.
 
Reading from Memory Blocks
auto beginRead (const BlockHandle &blockHandle) -> std::pair< ReadHandle, const void * >
 Locks a handle for reading.
 
auto endRead (const BlockHandle &blockHandle, const ReadHandle &readHandle) noexcept -> void
 Unlocks a handle for reading.
 
Writing to Memory Blocks
auto beginWrite (const BlockHandle &blockHandle, bool copy) -> std::pair< WriteHandle, void * >
 Locks a handle for writing.
 
auto discard (const BlockHandle &blockHandle, const WriteHandle &writeHandle) noexcept -> void
 Unlocks a handle for writing, discarding the data if possible.
 
auto commit (const BlockHandle &blockHandle, const WriteHandle &writeHandle) -> void
 Unlocks a handle for writing, commiting the data if necessary.
 

Detailed Description

A concept used for classes that can be used as memory resources.

Member Typedef Documentation

◆ BlockHandle

A handle used to refer to a memory block.

◆ ReadHandle

A handle used to perform synchronized reads from a memory block.

◆ WriteHandle

A handle used to perform synchronized writed to a memory block.

Member Enumeration Documentation

◆ HandleRole

different roles for handles

Enumerator
Generic 

A handle used to refer to a memory block.

Read 

A handle used to perform synchronized reads from a memory block.

Write 

A handle used to perform synchronized writed to a memory block.

Constructor & Destructor Documentation

◆ ~MemoryResource()

xentara::memory::MemoryResource::~MemoryResource ( )
pure virtualdefault

Virtual destructor.

Member Function Documentation

◆ beginRead()

auto xentara::memory::MemoryResource::beginRead ( const BlockHandle blockHandle) -> std::pair< ReadHandle, const void * >

Locks a handle for reading.

Parameters
blockHandleA handle to the block to lock.
Returns
A read handle for the block, plus a pointer to the block's memory. The pointer remains valid until you call endRead().

◆ beginWrite()

auto xentara::memory::MemoryResource::beginWrite ( const BlockHandle blockHandle,
bool  copy 
) -> std::pair< WriteHandle, void * >

Locks a handle for writing.

Parameters
blockHandleA handle to the block to lock.
copyWhether the data of the existing block should be copied to the newly created swap-in block. If you pass true, the new block will contain a copy of the old block; if you pass false, then the new block will be default constructed.
Returns
A write handle for the block, plus a pointer to the memory to be written. The memory pointer points to the newly allocated block that will be swapped in when calling commit(). The pointer only remains valid until you call discard() or commit().

◆ commit()

auto xentara::memory::MemoryResource::commit ( const BlockHandle blockHandle,
const WriteHandle writeHandle 
) -> void

Unlocks a handle for writing, commiting the data if necessary.

This function atomically replaces the existing block with the swap-in block allocated in beginWrite().

Parameters
blockHandleA handle to the block to unlock.
writeHandleThe read handle returned by beginWrite() when the block was locked.

◆ createBlock()

auto xentara::memory::MemoryResource::createBlock ( std::reference_wrapper< const BlockHandler handler) -> std::pair< BlockHandle, void * >

Creates a memory block.

This function allocates memory for the block and then calls BlockHandler::constructAt(void *placement) const to construct a blockin the allocated space.

Parameters
handlerThe handler for the block. Must remain valid until destroyBlock() is called.
Returns
A handle to the newly allocated block, plus a pointer to the block data. The pointer can be used to initialize the allocated memory.
Exceptions
std::bad_allocThe memory resource is exhausted

◆ destroyBlock()

auto xentara::memory::MemoryResource::destroyBlock ( const BlockHandle blockHandle) -> void
noexcept

Destroys a memory block.

This function calls BlockHandler::destroy() to destroy the block, and then deallocates the data.

Parameters
blockHandleA handle to the block. This must be a handle previously returned by allocate().

◆ discard()

auto xentara::memory::MemoryResource::discard ( const BlockHandle blockHandle,
const WriteHandle writeHandle 
) -> void
noexcept

Unlocks a handle for writing, discarding the data if possible.

This function will discard the swap-in block allocated in beginWrite() and the old block will be retained.

Parameters
blockHandleA handle to the block to unlock.
writeHandleThe read handle returned by beginWrite() when the block was locked.

◆ endRead()

auto xentara::memory::MemoryResource::endRead ( const BlockHandle blockHandle,
const ReadHandle readHandle 
) -> void
noexcept

Unlocks a handle for reading.

Parameters
blockHandleA handle to the block to unlock.
readHandleThe read handle returned by beginRead() when the block was locked.

◆ placement()

auto xentara::memory::MemoryResource::placement ( const BlockHandle blockHandle) const -> void *
noexcept

Recovers the current placement of a memory block without synchronization.

Attention
Contrary to beninRead() and beginWrite(), this function does not synchronize access to the block between consumers. The block data must only be accessed through the returned pointer as long as no read or write handles exist, and simultaneous access by multiple threads must be synchronized using regular thread synchronization mechanisms like std::mutex.
Parameters
blockHandleA handle to the block. This must be a handle previously returned by allocate().
Returns
The current placement of the memory block. The returned value is only valid as long as no read or write handles exist.
See also
beginRead(), beginWrite()