xentara::memory::MemoryResource Class Reference

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

#include <xentara/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, std::chrono::system_clock::time_point timeStamp, std::span< std::reference_wrapper< const process::Event > > additionalEvents={}) -> 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

using xentara::memory::MemoryResource::BlockHandle = Handle<HandleRole::Generic>

A handle used to refer to a memory block.

ReadHandle

using xentara::memory::MemoryResource::ReadHandle = Handle<HandleRole::Read>

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

WriteHandle

using xentara::memory::MemoryResource::WriteHandle = Handle<HandleRole::Write>

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

Member Enumeration Documentation

HandleRole

enum class xentara::memory::MemoryResource::HandleRole

strong

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

blockHandle

A 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

blockHandle	A handle to the block to lock.
copy	Whether 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,
		std::chrono::system_clock::time_point	timeStamp,
		std::span< std::reference_wrapper< const process::Event > >	additionalEvents = {}
	)		-> 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

blockHandle	A handle to the block to unlock.
writeHandle	The read handle returned by beginWrite() when the block was locked.
timeStamp	The time stamp to be used when raising change events.
additionalEvents	Additional events to raise together with the change events.

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

handler

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

The 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

blockHandle

A 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

blockHandle	A handle to the block to unlock.
writeHandle	The 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

blockHandle	A handle to the block to unlock.
readHandle	The 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 beginRead() 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

blockHandle

A 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()