#include "steam/engine/buffer-metadata.hpp"

Description

Registry for managing buffer metadata.

This is an implementation level service, used by the standard BufferProvider implementation. Each metadata registry (instance) defines and maintains a family of "buffer types"; beyond the buffer storage size, the concrete meaning of those types is tied to the corresponding BufferProvider implementation and remains opaque. These types are represented as hierarchically linked hash keys. The implementation may bind a TypeHandler to a specific type, allowing automatic invocation of a "constructor" and "destructor" function on each buffer of this type, when locking or freeing the corresponding buffer.

Definition at line 535 of file buffer-metadata.hpp.

Public Types
using	Entry = metadata::Entry

using	Key = metadata::Key

Public Member Functions
	BufferMetadata (Literal implementationID)
	establish a metadata registry. More...

Entry &	get (HashVal hashID)
	access the metadata record registered with the given hash key. More...

bool	isKnown (HashVal key) const

bool	isLocked (HashVal key) const

Key	key (size_t storageSize, TypeHandler instanceFunc=TypeHandler::RAW, LocalTag specifics=LocalTag::UNKNOWN)
	combine the distinguishing properties into a single type key, which will be known/remembered from that point on. More...

Key	key (Key const &parentKey, TypeHandler const &instanceFunc)
	create a sub-type, using a different type/handler functor

Key	key (Key const &parentKey, LocalTag specifics)
	create a sub-type, using a different private-ID (implementation defined)

Key const &	key (Key const &parentKey, metadata::Buff *concreteBuffer, LocalTag const &specifics=LocalTag::UNKNOWN)
	shortcut to access the Key part of a (probably new) Entry describing a concrete buffer at the given address More...

Entry &	lock (Key const &parentKey, metadata::Buff *concreteBuffer, LocalTag const &specifics=LocalTag::UNKNOWN, bool onlyNew=false)
	core operation to access or create a concrete buffer metadata entry. More...

Entry &	markLocked (Key const &parentKey, metadata::Buff *buffer, LocalTag const &specifics=LocalTag::UNKNOWN)
	combine the type (Key) with a concrete buffer, thereby marking this buffer as locked. More...

void	release (HashVal key)
	purge the bare metadata Entry from the metadata tables. More...

void	release (Entry const &entry)

Private Member Functions
void	maybeStore (Key const &key)

Entry &	store_as_locked (Entry const &metadata)
	store a fully populated entry immediately starting with locked state More...

template<typename PAR , typename DEF >
Key	trackKey (PAR parent, DEF specialisation)

Private Member Functions inherited from NonCopyable
	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
HashVal	family_

Literal	id_

metadata::Table	table_

Constructor & Destructor Documentation

◆ BufferMetadata()

BufferMetadata ( Literal implementationID )

inline

establish a metadata registry.

Such will maintain a family of buffer type entries and provide a service for storing and retrieving metadata for concrete buffer entries associated with these types.

Parameters

implementationID to distinguish families of type keys belonging to different registries.

Definition at line 555 of file buffer-metadata.hpp.

Member Function Documentation

◆ key() [1/2]

Key key	(	size_t	storageSize,
		TypeHandler	instanceFunc = `TypeHandler::RAW`,
		LocalTag	specifics = `LocalTag::UNKNOWN`
	)

inline

combine the distinguishing properties into a single type key, which will be known/remembered from that point on.

Properties are combined according to a fixed type specialisation order, with the buffer size forming the base level, possible TypeHandler functors the second level, and implementation defined LocalTag entries the third level. All these levels describe abstract type keys, not entries for concrete buffers. The latter are always created as children of a known type key.

Definition at line 571 of file buffer-metadata.hpp.

◆ key() [2/2]

Key const& key	(	Key const &	parentKey,
		metadata::Buff *	concreteBuffer,
		LocalTag const &	specifics = `LocalTag::UNKNOWN`
	)

inline

shortcut to access the Key part of a (probably new) Entry describing a concrete buffer at the given address

Note: might create/register a new Entry as a side-effect

Definition at line 607 of file buffer-metadata.hpp.

References Table::fetch(), and Key::forEntry().

Here is the call graph for this function:

◆ lock()

Entry& lock	(	Key const &	parentKey,
		metadata::Buff *	concreteBuffer,
		LocalTag const &	specifics = `LocalTag::UNKNOWN`,
		bool	onlyNew = `false`
	)

inline

core operation to access or create a concrete buffer metadata entry.

The hashID of the entry in question is built, based on the parentKey, which denotes a buffer type, optionally a implementation defined LocalTag, and the concrete buffer address. If yet unknown, a new concrete buffer metadata Entry is created and initialised to LOCKED state. Otherwise just the existing Entry is fetched and locked.

Note: this function really activates the buffer. In case the type (Key) involves a TypeHandler (functor), its constructor function will be invoked, if actually a new entry gets created. Typically this mechanism will be used to placement-create an object into the buffer.

Parameters

parentKey	a key describing the type of the buffer
concreteBuffer	storage pointer, must not be NULL
specifics	an implementation defined tag
onlyNew	disallow fetching an existing entry

Exceptions

error::Logic	when #onlyNew is set, but an equivalent entry was registered previously. This indicates a serious error in buffer lifecycle management.
error::Invalid	when invoked with NULL buffer. Use the key functions instead to register and track type keys.

Returns: reference to the entry stored in the metadata table.

Warning: the exposed reference might become invalid when the buffer is released or re-used later.

Definition at line 641 of file buffer-metadata.hpp.

◆ get()

Entry& get ( HashVal hashID )

inline

access the metadata record registered with the given hash key.

This might be a pseudo entry in case of a Key describing a buffer type. Otherwise, the entry associated with a concrete buffer pointer is returned by reference, an can be modified (e.g. state change)

Parameters

hashID which can be calculated from the Key

Exceptions

error::Invalid when there is no such entry

Note: use #isKnown to check existence

Definition at line 676 of file buffer-metadata.hpp.

References steam::mobject::session::query::anonymous_namespace{fake-configrules.cpp}::entry(), and Table::fetch().

Referenced by WrappedStandardExeBuilder::__call__().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ markLocked()

Entry& markLocked	(	Key const &	parentKey,
		metadata::Buff *	buffer,
		LocalTag const &	specifics = `LocalTag::UNKNOWN`
	)

inline

combine the type (Key) with a concrete buffer, thereby marking this buffer as locked.

Store a concrete metadata Entry to account for this fact. This might include invoking a constructor function, in case the type (Key) defines a (nontrivial) TypeHandler.

Exceptions

error::Fatal	when locking a NULL buffer
exceptions	which might be raised by a TypeHandler's constructor function. In this case, the Entry remains created, but is marked as FREE

Definition at line 714 of file buffer-metadata.hpp.

◆ release()

void release ( HashVal key )

inline

purge the bare metadata Entry from the metadata tables.

Exceptions

error::Logic if the entry isn't marked FREE already

Definition at line 727 of file buffer-metadata.hpp.

References steam::mobject::session::query::anonymous_namespace{fake-configrules.cpp}::entry(), Table::fetch(), and steam::engine::FREE.

Here is the call graph for this function:

◆ store_as_locked()

Entry& store_as_locked ( Entry const & metadata )

inlineprivate

store a fully populated entry immediately starting with locked state

Remarks: the (optional) constructor function for a type embedded into the buffer is invoked when a persistent entry transitions to locked state; since a new buffer created with storage location is already marked as locked, for sake of consistency the embedded constructor must now be invoked; if this fails, the state has to be transitioned back to FREE before re-throwing.

Definition at line 774 of file buffer-metadata.hpp.

References steam::engine::FREE, Entry::invokeEmbeddedCtor(), Entry::isLocked(), steam::engine::LOCKED, and Table::store().

Here is the call graph for this function:

Inheritance diagram for BufferMetadata:

Collaboration diagram for BufferMetadata:

The documentation for this class was generated from the following file:

buffer-metadata.hpp

Description

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ BufferMetadata()

Member Function Documentation

◆ key() [1/2]

◆ key() [2/2]

◆ lock()

◆ get()

◆ markLocked()

◆ release()

◆ store_as_locked()