#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
dereferencing this smart-handle class

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 81 of file buffer-provider.hpp.

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

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

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

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

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

size_t	getBufferSize (HashVal typeID) const

template<typename BU >
BufferDescriptor	getDescriptor ()
	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.

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

BufferDescriptor	getDescriptorFor (size_t storageSize, TypeHandler specialTreatment)

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

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

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

bool	verifyValidity (BufferDescriptor const &) const

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

BuffHandle	buildHandle (HashVal typeID, void *storage, LocalKey const &)
	callback from implementation to build and enrol a BufferHandle, to be returned to the client as result of the lockBuffer call. More...

virtual void	detachBuffer (HashVal typeID, LocalKey const &)=0

virtual void	mark_emitted (HashVal typeID, LocalKey const &)=0

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

virtual BuffHandle	provideLockedBuffer (HashVal typeID)=0

bool	was_created_by_this_provider (BufferDescriptor const &) const

Private Attributes
unique_ptr< BufferMetadata >	meta_

Additional Inherited Members
Private Member Functions inherited from NonCopyable
	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 54 of file buffer-provider.cpp.

Member Function Documentation

◆ announce()

uint announce	(	uint	count,
		BufferDescriptor 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 BufferDescriptor.

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 123 of file buffer-provider.cpp.

◆ lockBuffer()

BuffHandle lockBuffer ( BufferDescriptor 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.

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

Referenced by BufferProvider::lockBufferFor().

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. An emitted buffer should not be modified anymore.

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

References steam::engine::EMITTED, and Entry::mark().

Here is the call 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 184 of file buffer-provider.cpp.

References ERROR_LOG_AND_IGNORE, steam::engine::FREE, and Entry::mark().

Here is the call graph for this function:

◆ lockBufferFor()

BuffHandle lockBufferFor ( )

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 151 of file buffer-provider.hpp.

References BufferProvider::lockBuffer().

Here is the call graph for this function:

◆ attachTypeHandler()

void attachTypeHandler	(	BuffHandle const &	target,
		BufferDescriptor 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 206 of file buffer-provider.cpp.

References Entry::isLocked(), and Entry::isTypeKey().

Here is the call 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 228 of file buffer-provider.cpp.

References ERROR_LOG_AND_IGNORE.

◆ verifyValidity()

bool verifyValidity ( BufferDescriptor 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 66 of file buffer-provider.cpp.

◆ buildHandle()

BuffHandle buildHandle	(	HashVal	typeID,
		void *	storage,
		LocalKey const &	implID
	)

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 101 of file buffer-provider.cpp.

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

Here is the call graph for this function:

Inheritance diagram for BufferProvider:

Collaboration diagram for BufferProvider:

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

Description

Public Member Functions

Protected Member Functions

Private Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ BufferProvider()

Member Function Documentation

◆ announce()

◆ lockBuffer()

◆ emitBuffer()

◆ releaseBuffer()

◆ lockBufferFor()

◆ attachTypeHandler()

◆ emergencyCleanup()

◆ verifyValidity()

◆ buildHandle()