#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	Key = metadata::Key

using	Entry = metadata::Entry

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

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.

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

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.

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

bool	isKnown (HashVal key) const

bool	isLocked (HashVal key) const

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.

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

void	release (Entry const &entry)

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

void	maybeStore (Key const &key)

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

Private Member Functions inherited from NonCopyable
	~NonCopyable ()=default

	NonCopyable ()=default

	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
Literal	id_

HashVal	family_

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 Typedef Documentation

◆ Key

using Key = metadata::Key

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

◆ Entry

using Entry = metadata::Entry

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

Member Function Documentation

◆ key() [1/4]

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.

References BufferMetadata::family_, and BufferMetadata::trackKey().

Referenced by BufferMetadata::isKnown(), BufferMetadata::isLocked(), BufferMetadata::maybeStore(), and BufferMetadata::release().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ key() [2/4]

Key key	(	Key const &	parentKey,
		TypeHandler const &	instanceFunc
	)

inline

create a sub-type, using a different type/handler functor

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

References BufferMetadata::trackKey().

Here is the call graph for this function:

◆ key() [3/4]

Key key	(	Key const &	parentKey,
		LocalTag	specifics
	)

inline

create a sub-type, using a different private-ID (implementation defined)

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

References BufferMetadata::trackKey().

Here is the call graph for this function:

◆ key() [4/4]

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(), Key::forEntry(), BufferMetadata::markLocked(), and BufferMetadata::table_.

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.

References Table::fetch(), Entry::isLocked(), LERR_, Entry::lock(), BufferMetadata::store_as_locked(), and BufferMetadata::table_.

Referenced by BufferMetadata::markLocked().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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 Table::fetch(), and BufferMetadata::table_.

Referenced by WrappedStandardExeBuilder::invokeOriginalBuilder().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isKnown()

bool isKnown ( HashVal key ) const

inline

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

References Table::fetch(), BufferMetadata::key(), and BufferMetadata::table_.

Referenced by BufferMetadata::maybeStore().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isLocked()

bool isLocked ( HashVal key ) const

inline

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

References Table::fetch(), BufferMetadata::key(), and BufferMetadata::table_.

Here is the call 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.

References LERR_, and BufferMetadata::lock().

Referenced by BufferMetadata::key().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ release() [1/2]

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 Table::fetch(), BufferMetadata::key(), BufferMetadata::release(), and BufferMetadata::table_.

Referenced by BufferMetadata::release().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ release() [2/2]

void release ( Entry const & entry )

inline

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

References steam::engine::FREE, LERR_, Table::remove(), and BufferMetadata::table_.

Here is the call graph for this function:

◆ trackKey()

template<typename PAR , typename DEF >

Key trackKey	(	PAR	parent,
		DEF	specialisation
	)

inlineprivate

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

References BufferMetadata::maybeStore().

Referenced by BufferMetadata::key(), BufferMetadata::key(), and BufferMetadata::key().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ maybeStore()

void maybeStore ( Key const & key )

inlineprivate

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

References BufferMetadata::isKnown(), BufferMetadata::key(), Table::store(), and BufferMetadata::table_.

Referenced by BufferMetadata::trackKey().

Here is the call graph for this function:

Here is the caller 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 Entry::access(), steam::engine::FREE, Entry::invokeEmbeddedCtor(), Entry::isLocked(), steam::engine::LOCKED, Entry::mark(), Entry::state(), Table::store(), and BufferMetadata::table_.

Referenced by BufferMetadata::lock().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ id_

Literal id_

private

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

◆ family_

HashVal family_

private

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

Referenced by BufferMetadata::key().

◆ table_

metadata::Table table_

private

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

Referenced by BufferMetadata::get(), BufferMetadata::isKnown(), BufferMetadata::isLocked(), BufferMetadata::key(), BufferMetadata::lock(), BufferMetadata::maybeStore(), BufferMetadata::release(), BufferMetadata::release(), and BufferMetadata::store_as_locked().

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 Typedef Documentation

◆ Key

◆ Entry

Member Function Documentation

◆ key() [1/4]

◆ key() [2/4]

◆ key() [3/4]

◆ key() [4/4]

◆ lock()

◆ get()

◆ isKnown()

◆ isLocked()

◆ markLocked()

◆ release() [1/2]

◆ release() [2/2]

◆ trackKey()

◆ maybeStore()

◆ store_as_locked()

Member Data Documentation

◆ id_

◆ family_

◆ table_