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

Description

Interface: a facility providing and managing working buffers for media calculations.

The pointer to actual buffer storage can be retrieved by

optionally announcing the required buffer(s) beforehand
"locking" a buffer to yield a buffer handle
then dereferencing the obtained smart-handle

Warning: all of BufferProvider is assumed to run within a threadsafe environment.

Todo:

as of 6/2011 buffer management within the engine is still a bit vague

as of 11/11 thread safety within the engine remains to be clarified ///////////////////////////TICKET #854

Definition at line 75 of file buffer-provider.hpp.

Public Member Functions
virtual	~BufferProvider ()
	this is an ABC

uint	announce (uint count, BuffDescr const &)
	BufferProvider API: declare in advance the need for working buffers.

BuffHandle	lockBuffer (BuffDescr const &)
	BufferProvider API: retrieve a single buffer for exclusive use.

void	emitBuffer (BuffHandle const &)
	BufferProvider API: state transition to emitted state.

void	releaseBuffer (BuffHandle const &)
	BufferProvider API: declare done and detach.

template<typename BU , typename... ARGS>
BuffHandle	lockBufferFor (ARGS ...args)
	convenience shortcut: prepare and claim ("lock") a buffer suitable to hold an object of the given type.

void	attachTypeHandler (BuffHandle const &target, BuffDescr const &reference)
	allow for attaching and owing an object within an already created buffer

void	emergencyCleanup (BuffHandle const &target, bool invokeDtor=false)

BuffDescr	getDescriptorFor (size_t storageSize=0)
	describe the kind of buffer managed by this provider

BuffDescr	getDescriptorFor (size_t storageSize, TypeHandler specialTreatment)

template<typename BU , typename... ARGS>
BuffDescr	getDescriptor (ARGS ...args)
	define a "buffer type" for automatically creating an instance of the template type embedded into the buffer and destroying that embedded object when releasing the buffer.

bool	verifyValidity (BuffDescr const &) const

size_t	getBufferSize (HashVal typeID) const

Protected Types
using	Buff = StreamType::ImplFacade::DataBuffer
	placeholder marker type for an actual data buffer

Protected Member Functions
	BufferProvider (Literal implementationID)
	build a new provider instance, managing a family of buffers.

virtual uint	prepareBuffers (uint count, HashVal typeID)=0

virtual BuffHandle	provideLockedBuffer (HashVal typeID)=0

virtual void	mark_emitted (HashVal, LocalTag const &)=0

virtual void	detachBuffer (HashVal, LocalTag const &, Buff &)=0

BuffHandle	buildHandle (HashVal typeID, Buff *storage, LocalTag const &=LocalTag::UNKNOWN)
	callback from implementation to build and enrol a BufferHandle, to be returned to the client as result of the lockBuffer call.

bool	was_created_by_this_provider (BuffDescr const &) const

Private Attributes
unique_ptr< BufferMetadata >	meta_

Additional Inherited Members
Private Member Functions inherited from NonCopyable
	~NonCopyable ()=default

	NonCopyable ()=default

	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Constructor & Destructor Documentation

◆ BufferProvider()

BufferProvider ( Literal implementationID )

protected

build a new provider instance, managing a family of buffers.

The metadata of these buffers is organised hierarchically based on chained hash values, using the #implementationID as a seed.

Parameters

implementationID symbolic ID setting these family of buffers apart.

Definition at line 49 of file buffer-provider.cpp.

◆ ~BufferProvider()

~BufferProvider ( )

virtual

this is an ABC

Definition at line 53 of file buffer-provider.cpp.

Member Typedef Documentation

◆ Buff

using Buff = StreamType::ImplFacade::DataBuffer

protected

placeholder marker type for an actual data buffer

Definition at line 84 of file buffer-provider.hpp.

Member Function Documentation

◆ prepareBuffers()

virtual uint prepareBuffers	(	uint	count,
		HashVal	typeID
	)

protectedpure virtual

Implemented in TrackingHeapBlockProvider, and BufferProxyProvider::ForwardingBufferProvider.

Referenced by BufferProvider::announce().

Here is the caller graph for this function:

◆ provideLockedBuffer()

virtual BuffHandle provideLockedBuffer ( HashVal typeID )

protectedpure virtual

Implemented in BufferProxyProvider::ForwardingBufferProvider, and TrackingHeapBlockProvider.

Referenced by BufferProvider::lockBuffer().

Here is the caller graph for this function:

◆ mark_emitted()

virtual void mark_emitted	(	HashVal	,
		LocalTag const &
	)

protectedpure virtual

Implemented in BufferProxyProvider::ForwardingBufferProvider, and TrackingHeapBlockProvider.

Referenced by BufferProvider::emitBuffer().

Here is the caller graph for this function:

◆ detachBuffer()

virtual void detachBuffer	(	HashVal	,
		LocalTag const &	,
		Buff &
	)

protectedpure virtual

Implemented in BufferProxyProvider::ForwardingBufferProvider, and TrackingHeapBlockProvider.

Referenced by BufferProvider::emergencyCleanup(), and BufferProvider::releaseBuffer().

Here is the caller graph for this function:

◆ announce()

uint announce	(	uint	count,
		BuffDescr const &	type
	)

BufferProvider API: declare in advance the need for working buffers.

This optional call allows client code to ensure the availability of the necessary working space, prior to starting the actual operations. The client may reasonably assume to get the actual number of buffers, as indicated by the return value. A provider may be able to handle various kinds of buffers (e.g. of differing size), which are distinguished by the type embodied into the BuffDescr.

Returns: maximum number of simultaneously usable buffers of this type, to be retrieved later through calls to lockBuffer.

Exceptions

error::State when no buffer of this kind can be provided

Note: the returned count may differ from the requested count.

Definition at line 118 of file buffer-provider.cpp.

References BufferProvider::prepareBuffers().

Referenced by BuffDescr::announce(), BufferProviderProtocol_test::verifyStandardCase(), and TrackingHeapBlockProvider_test::verifyStandardCase().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lockBuffer()

BuffHandle lockBuffer ( BuffDescr const & type )

BufferProvider API: retrieve a single buffer for exclusive use.

This call actually claims a buffer of this type and marks it for use by client code. The returned handle allows for convenient access, but provides no automatic tracking or memory management. The client is explicitly responsible to invoke releaseBuffer (which can be done directly on the BuffHandle).

Returns: a copyable handle, representing this buffer and this usage transaction.

Exceptions

error::State when unable to provide this buffer

Note: this function may be used right away, without prior announcing, but then the client should be prepared for exceptions. The announce operation allows to establish a reliably available baseline.

Todo:: 2/2025 might need to accept a cache key as additional parameter //////////////////////////////////TICKET #1392 : get cache key from computation to the cache backend

Definition at line 142 of file buffer-provider.cpp.

References BufferProvider::provideLockedBuffer(), and BufferProvider::was_created_by_this_provider().

Referenced by TrackingInMemoryBlockSequence::claimBufferFor(), BuffDescr::lockBuffer(), BufferProvider::lockBufferFor(), NodeDevel_test::testRand_buildFilterNode(), NodeDevel_test::testRand_buildMixNode(), NodeDevel_test::testRand_simpleUsage(), NodeLink_test::trigger_node_port_invocation(), BufferProviderProtocol_test::verifyObjectAttachment(), BufferProviderProtocol_test::verifyObjectAttachmentFailure(), TrackingHeapBlockProvider_test::verifyStandardCase(), and TrackingHeapBlockProvider_test::verifyTestProtocol().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ emitBuffer()

void emitBuffer ( BuffHandle const & handle )

BufferProvider API: state transition to emitted state.

Client code may signal a state transition through this optional operation. The actual meaning of an "emitted" buffer is implementation defined; similarly, some back-ends may actually do something when emitting a buffer (e.g. commit data to cache), while others just set a flag or do nothing at all. This state transition may be invoked at most once per locked buffer.

Exceptions

error::Fatal in case of invalid state transition sequence. Only a locked buffer may be emitted, and at most once.

Warning: by convention, emitting a buffer implies that the contained data is ready and might be used by other parts of the application. While an emitted buffer should not be modified anymore, it can still be accessed.

Definition at line 163 of file buffer-provider.cpp.

References steam::engine::EMITTED, BuffHandle::entryID(), Key::localTag(), Entry::mark(), BufferProvider::mark_emitted(), BufferProvider::meta_, and Key::parentKey().

Referenced by BuffHandle::emit(), TrackingInMemoryBlockSequence::pushout(), TrackingHeapBlockProvider_test::simpleExample(), TrackingHeapBlockProvider_test::verifyStandardCase(), and TrackingHeapBlockProvider_test::verifyTestProtocol().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ releaseBuffer()

void releaseBuffer ( BuffHandle const & handle )

BufferProvider API: declare done and detach.

Client code is required to release each previously locked buffer eventually.

Warning: invalidates the BuffHandle, clients mustn't access the buffer anymore. Right after releasing, an access through the handle will throw; yet the buffer might be re-used and the handle become valid later on accidentally.

Note: EX_FREE

Definition at line 180 of file buffer-provider.cpp.

References BufferProvider::detachBuffer(), BuffHandle::entryID(), steam::engine::FREE, Key::localTag(), Entry::mark(), BufferProvider::meta_, and Key::parentKey().

Referenced by TrackingInMemoryBlockSequence::discard(), TrackingInMemoryBlockSequence::pushout(), BuffHandle::release(), TrackingHeapBlockProvider_test::simpleExample(), and TrackingHeapBlockProvider_test::verifyStandardCase().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lockBufferFor()

template<typename BU , typename... ARGS>

BuffHandle lockBufferFor ( ARGS ... args )

convenience shortcut: prepare and claim ("lock") a buffer suitable to hold an object of the given type.

Returns: a handle embedding a suitably configured buffer descriptor. The corresponding buffer has been allocated and marked for exclusive use

Definition at line 148 of file buffer-provider.hpp.

References BufferProvider::lockBuffer().

Referenced by NodeLink_test::build_connected_nodes(), NodeFeed_test::feedParamNode(), NodeBuilder_test::invokeRenderNode(), TrackingHeapBlockProvider_test::simpleExample(), NodeBase_test::verify_FeedManifold(), NodeBase_test::verify_FeedPrototype(), NodeBase_test::verify_NodeStructure(), and BufferProviderProtocol_test::verifySimpleUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ attachTypeHandler()

void attachTypeHandler	(	BuffHandle const &	target,
		BuffDescr const &	reference
	)

allow for attaching and owing an object within an already created buffer

Warning: this operation locally modifies the metadata entry of a single buffer to attach a TypeHandler taking ownership of an object embedded within the buffer. The client is responsible for actually placement-constructing the object; moreover the client is responsible for any damage done to already existing buffer content.

Note: the buffer must be in locked state and the underlying buffer type must not define an non-trivial TypeDescriptor, because there is no clean way of superseding an existing TypeDescriptor, which basically is just a functor and possibly could perform any operation on buffer clean-up.; EX_STRONG

Definition at line 202 of file buffer-provider.cpp.

References Entry::isLocked(), Entry::isTypeKey(), LERR_, and Key::useTypeHandlerFrom().

Referenced by BuffHandle::takeOwnershipFor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ emergencyCleanup()

void emergencyCleanup	(	BuffHandle const &	target,
		bool	invokeDtor = `false`
	)

abort normal lifecycle, reset the underlying buffer and detach from it. This allows to break out of normal usage and reset the handle to invalid state

Parameters

invokeDtor if possibly the clean-up function of an TypeHandler registered with the buffer metadata should be invoked prior to resetting the metadata state. Default is not to invoke anything

Note: EX_FREE

Definition at line 224 of file buffer-provider.cpp.

References BufferProvider::detachBuffer(), BuffHandle::entryID(), Entry::invalidate(), Key::localTag(), BufferProvider::meta_, and Key::parentKey().

Referenced by BuffHandle::emergencyCleanup().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getDescriptorFor() [1/2]

BuffDescr getDescriptorFor ( size_t storageSize = 0 )

describe the kind of buffer managed by this provider

Definition at line 68 of file buffer-provider.cpp.

References BufferProvider::meta_.

Referenced by BufferProvider::getDescriptor(), NodeDevel_test::testRand_buildFilterNode(), NodeDevel_test::testRand_buildMixNode(), NodeDevel_test::testRand_simpleUsage(), BufferProviderProtocol_test::verifyObjectAttachment(), BufferProviderProtocol_test::verifyObjectAttachmentFailure(), BufferProviderProtocol_test::verifyStandardCase(), TrackingHeapBlockProvider_test::verifyStandardCase(), and TrackingHeapBlockProvider_test::verifyTestProtocol().

Here is the caller graph for this function:

◆ getDescriptorFor() [2/2]

BuffDescr getDescriptorFor	(	size_t	storageSize,
		TypeHandler	specialTreatment
	)

Definition at line 75 of file buffer-provider.cpp.

References BufferProvider::meta_.

◆ getDescriptor()

template<typename BU , typename... ARGS>

BuffDescr getDescriptor ( ARGS ... args )

define a "buffer type" for automatically creating an instance of the template type embedded into the buffer and destroying that embedded object when releasing the buffer.

Definition at line 161 of file buffer-provider.hpp.

References BufferProvider::getDescriptorFor().

Referenced by NodeFeed_test::feedParam(), BuffHandle::takeOwnershipFor(), NodeLink_test::trigger_node_port_invocation(), BufferProviderProtocol_test::verifyObjectAttachment(), and BufferProviderProtocol_test::verifyStandardCase().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifyValidity()

bool verifyValidity ( BuffDescr const & bufferID ) const

verify the given descriptor.

Returns: true if it corresponds to a buffer currently locked and usable by client code

Definition at line 61 of file buffer-provider.cpp.

References BufferProvider::meta_.

Referenced by BuffDescr::verifyValidity().

Here is the caller graph for this function:

◆ getBufferSize()

size_t getBufferSize ( HashVal typeID ) const

Definition at line 82 of file buffer-provider.cpp.

References BufferProvider::meta_, and Key::storageSize().

Referenced by BuffDescr::determineBufferSize(), and TrackingHeapBlockProvider::getBlockPoolFor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ buildHandle()

BuffHandle buildHandle	(	HashVal	typeID,
		Buff *	storage,
		LocalTag const &	localTag = `LocalTag::UNKNOWN`
	)

protected

callback from implementation to build and enrol a BufferHandle, to be returned to the client as result of the lockBuffer call.

Performs the necessary metadata state transition leading from an abstract buffer type to a metadata::Entry corresponding to an actual buffer, which is locked for exclusive use by one client.

Definition at line 96 of file buffer-provider.cpp.

References BufferProvider::meta_.

Referenced by TrackingHeapBlockProvider::provideLockedBuffer().

Here is the caller graph for this function:

◆ was_created_by_this_provider()

bool was_created_by_this_provider ( BuffDescr const & descr ) const

protected

Definition at line 236 of file buffer-provider.cpp.

Referenced by BufferProvider::lockBuffer().

Here is the caller graph for this function:

Member Data Documentation

◆ meta_

unique_ptr<BufferMetadata> meta_

private

Definition at line 78 of file buffer-provider.hpp.

Referenced by BufferProvider::buildHandle(), BufferProvider::emergencyCleanup(), BufferProvider::emitBuffer(), BufferProvider::getBufferSize(), BufferProvider::getDescriptorFor(), BufferProvider::getDescriptorFor(), BufferProvider::releaseBuffer(), and BufferProvider::verifyValidity().

Inheritance diagram for BufferProvider:

Collaboration diagram for BufferProvider:

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

Description

Public Member Functions

Protected Types

Protected Member Functions

Private Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ BufferProvider()

◆ ~BufferProvider()

Member Typedef Documentation

◆ Buff

Member Function Documentation

◆ prepareBuffers()

◆ provideLockedBuffer()

◆ mark_emitted()

◆ detachBuffer()

◆ announce()

◆ lockBuffer()

◆ emitBuffer()

◆ releaseBuffer()

◆ lockBufferFor()

◆ attachTypeHandler()

◆ emergencyCleanup()

◆ getDescriptorFor() [1/2]

◆ getDescriptorFor() [2/2]

◆ getDescriptor()

◆ verifyValidity()

◆ getBufferSize()

◆ buildHandle()

◆ was_created_by_this_provider()

Member Data Documentation

◆ meta_