diff --git a/src/proc/engine/buffer-metadata.hpp b/src/proc/engine/buffer-metadata.hpp new file mode 100644 index 000000000..ca9d5b734 --- /dev/null +++ b/src/proc/engine/buffer-metadata.hpp @@ -0,0 +1,135 @@ +/* + BUFFER-METADATA.hpp - internal metadata for data buffer providers + + Copyright (C) Lumiera.org + 2011, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + +/** @file buffer-metadate.hpp + ** Metadata for managing and accessing buffers. The Lumiera Engine uses the + ** Abstraction of an BufferProvider to handle various kinds of buffer organisation + ** and access in a uniform way. Actually, buffers can be exposed and provided by several + ** facilities, which might even be implemented through an external library. Thus the engine + ** and the abstraction placed in between needs a common set of control data, to be able to + ** expose the correct buffer for each request. Typically -- and independent of the actual + ** implementation -- the following properties need to be tracked + ** - that overall storage size available within the buffer + ** - a pair of custom \em creator and \em destructor functions to use together with this buffer + ** - an additional client key to distinguish otherwise otherwise identical client requests + ** These three distinctions are applied in sequence, thus forming a tree with 3 levels. + ** Only the first distinguishing level (the size) is mandatory. The others are provided, + ** because some of the foreseeable buffer providers allow to re-access the data placed + ** into the buffer, by assigning an internally managed ID to the buffer. The most + ** prominent example is the frame cache, which obviously needs to keep track of + ** the buffers after the render engine is finished, while the engine code + ** just accesses yet another buffer to place the results of calculations. + ** + ** These additional distinctions and properties are associated with the help of the + ** BufferDescriptor, embedded into each BuffHandle. While the engine just uses these + ** handles in the way of a pointer, the buffer descriptor acts as an additional tag + ** attached to the buffer access, allowing to re-access a context within the + ** buffer provider implementation. + ** + ** @see buffer-provider.hpp + ** @see BufferMetadata_test + ** @see BufferProviderProtocol_test + */ + +#ifndef PROC_ENGINE_BUFFR_METADATA_H +#define PROC_ENGINE_BUFFR_METADATA_H + + +#include "lib/error.hpp" + +//#include + + +namespace engine { + + + typedef uint64_t LocalKey; + typedef size_t HashVal; + + const LocalKey UNSPECIFIC = 0; + + struct TypeHandler + { + typedef void (*Ctor) (void*); + typedef void (*Dtor) (void*); + + Ctor createAttached; + Dtor destroyAttached; + + TypeHandler() + : createAttached (0) + , destroyAttached (0) + { } + + template + TypeHandler() + : createAttached (0) /////////TODO: how to attach the ctor function??? mabye better use a class with virtual functions? + , destroyAttached (0) + { } + }; + + const TypeHandler RAW_BUFFER; + + + class Metadata + { + public: + static HashVal + key ( size_t storageSize + , TypeHandler instanceFunc =RAW_BUFFER + , LocalKey specifics =UNSPECIFIC) + { + UNIMPLEMENTED ("combine the distinguishing properties into a single hash"); + } + + static Metadata& + get (HashVal key) + { + UNIMPLEMENTED ("access, possibly create metadata records"); + } + + BufferState + state () const + { + UNIMPLEMENTED ("buffer state accounting"); + } + + Metadata& + mark (BufferState newState) + { + UNIMPLEMENTED ("buffer state transitions"); + return *this; + } + }; + + + + + /* === Implementation === */ + + /** */ + + + + +} // namespace engine +#endif diff --git a/src/proc/engine/buffer-provider.cpp b/src/proc/engine/buffer-provider.cpp index 78cded609..d2820d211 100644 --- a/src/proc/engine/buffer-provider.cpp +++ b/src/proc/engine/buffer-provider.cpp @@ -22,6 +22,8 @@ #include "proc/engine/buffer-provider.hpp" +#include "proc/engine/buffer-metadata.hpp" + namespace engine { @@ -30,45 +32,6 @@ namespace engine { const uint DEFAULT_DESCRIPTOR = 0; - typedef uint64_t LocalKey; - typedef size_t HashVal; - - const LocalKey UNSPECIFIC = 0; - - struct TypeHandler - { - typedef void (*Ctor) (void*); - typedef void (*Dtor) (void*); - - Ctor createAttached; - Dtor destroyAttached; - - TypeHandler() - : createAttached (0) - , destroyAttached (0) - { } - - template - TypeHandler() - : createAttached (0) /////////TODO: how to attach the ctor function??? mabye better use a class with virtual functions? - , destroyAttached (0) - { } - }; - - const TypeHandler RAW_BUFFER; - - - class Metadata - { - public: - static HashVal - key ( size_t storageSize - , TypeHandler instanceFunc =RAW_BUFFER - , LocalKey specifics =UNSPECIFIC) - { - UNIMPLEMENTED ("combine the distinguishing properties into a single hash"); - } - }; } diff --git a/tests/46engine.tests b/tests/46engine.tests index bc4097114..2c9df05db 100644 --- a/tests/46engine.tests +++ b/tests/46engine.tests @@ -7,7 +7,11 @@ return: 0 END -PLANNED "BuffTable_test" BuffTable_test < + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/error.hpp" +#include "lib/test/run.hpp" +#include "lib/test/test-helper.hpp" +//#include "lib/util-foreach.hpp" +#include "lib/util.hpp" +//#include "proc/play/diagnostic-output-slot.hpp" +//#include "proc/engine/testframe.hpp" +//#include "proc/engine/diagnostic-buffer-provider.hpp" +#include "proc/engine/buffer-metadata.hpp" +//#include "proc/engine/buffhandle.hpp" +//#include "proc/engine/bufftable.hpp" + +//#include +#include +//#include + +//using boost::format; +//using std::string; +//using std::cout; +//using util::for_each; +using util::isnil; +using util::isSameObject; + + +namespace engine{ +namespace test { + +// using lib::AllocationCluster; +// using mobject::session::PEffect; +// using ::engine::BuffHandle; + using lumiera::error::LUMIERA_ERROR_INVALID; + using lumiera::error::LUMIERA_ERROR_LIFECYCLE; + + + namespace { // Test fixture + + const size_t TEST_MAX_SIZE = 1024 * 1024; + + const size_t SIZE_A = 1 + rand() % TEST_MAX_SIZE + const size_t SIZE_B = 1 + rand() % TEST_MAX_SIZE + + const HashVal JUST_SOMETHING = 123; +// const uint TEST_SIZE = 1024*1024; +// const uint TEST_ELMS = 20; + + bool + ensure_proper_fixture() + { + return (SIZE_A != SIZE_B) + && (JUST_SOMETHING != Metadata::key(SIZE_A)) + && (JUST_SOMETHING != Metadata::key(SIZE_B)) + ; + } + + } + + + /******************************************************************* + * @test verify the properties of the BufferMetadata records used + * internally within BufferProvider to attach additional + * organisational data to the exposed buffers. + */ + class BufferMetadata_test : public Test + { + virtual void + run (Arg) + { + UNIMPLEMENTED ("cover all metadata properties"); + CHECK (ensure_proper_fixture()); + verifyBasicProperties(); + verifyStandardCase(); + } + + + void + verifyBasicProperties() + { + HashVal key = Metadata::key(SIZE_A); + CHECK (key); + + HashVal key1 = Metadata::key(SIZE_A); + HashVal key2 = Metadata::key(SIZE_B); + CHECK (key1); + CHECK (key2); + CHECK (key == key1); + CHECK (key != key2); + + VERIFY_ERROR (INVALID, Metadata::get(0)) + VERIFY_ERROR (INVALID, Metadata::get(JUST_SOMETHING)); + CHECK ( & Metadata::get(key)); + CHECK ( & Metadata::get(key1)); + CHECK ( & Metadata::get(key2)); + + CHECK ( isSameObject (Metadata::get(key), Metadata::get(key))); + CHECK ( isSameObject (Metadata::get(key), Metadata::get(key1))); + CHECK (!isSameObject (Metadata::get(key), Metadata::get(key2))); + + Metadata& m1 = Metadata::get(key); + CHECK (NIL == m1.state()); + + VERIFY_ERROR (LIFECYCLE, m1.mark(EMITTED) ); + + m1.mark (LOCKED); + CHECK (LOCKED == m1.state()); + CHECK (LOCKED == Metadata::get(key1).state()); + } + + + void + verifyStandardCase() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #834 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #834 + } + }; + + + /** Register this test class... */ + LAUNCHER (BufferMetadata_test, "unit player"); + + + +}} // namespace engine::test