benn/lumiera_documentation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

BufferProvider: reorder validity handle validity checks

Browse source 
These were defined in a confusing and implementation-oriented way.
Since we have now mostly abstracted away the metadata handling from the
`BufferProvider` front-end, a more succinct definition was chosen
 * a ''Descriptor'' is valid when the lookup succeeds
 * a ''Handle'' is likewise valid when the underlying
   state-Key can be resolved, and the memory address is given

Some aspects regarding the state remain unresolved though.
Ideally we'd want a `BuffHandle` to be valid preciselc when
it ''is in valid state to be accessed''
This commit is contained in:
Fischlurch 2026-02-15 23:39:13 +01:00
parent 1230cbae12
commit c0e2d3b70e
7 changed files with 97 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
src/steam/engine/buffer-metadata.hpp
View file

@ -149,6 +149,10 @@ namespace engine {
public:
/** Generic marker for an impossible / rejected type */
static const Key INVALID;
/** build a standard basic key describing a kind of Buffer.
* @param familyID basic hash seed value to distinguish
* families of buffer types managed by
@ -237,6 +241,19 @@ namespace engine {
HashVal parentKey() const { return parent_;}
operator HashVal() const { return hashID_;}
friend bool
operator== (Key const& k1, Key const& k2)
{
return k1.hashID_ == k2.hashID_
and k1.parent_ == k2.parent_;
}
explicit
operator bool() const
{
return *this != INVALID;
}
};

57
src/steam/engine/buffer-provider.cpp
View file

@ -31,7 +31,7 @@ namespace engine {
// storage for the default-marker constants
const TypeHandler TypeHandler::RAW{};
const LocalTag LocalTag::UNKNOWN{};
const metadata::Key SimpleBufferStateRegistry::NULL_KEY{HashVal(0), size_t(0)}; //////OOO try to make this init into a constexpr and then do it in-class!
const metadata::Key metadata::Key::INVALID{HashVal(0), size_t(0)}; //////OOO consider to relocate those marker constants to somewhere more obvious
namespace { // impl. details and definitions
@ -51,11 +51,19 @@ namespace engine {
* currently locked and usable by client code
*/
bool
BufferProvider::verifyValidity (BuffDescr const& bufferID) const
BufferProvider::verifyValidity (HashVal id) const
{
return bufferStage_->isLocked (bufferID);
return bool (bufferStage_->lookup (id));
}
size_t
BufferProvider::getBufferSize (HashVal id) const
{
auto& key = bufferStage_->lookup (id);
return key.storageSize();
}
BuffDescr
BufferProvider::getDescriptorFor (size_t storageSize)
@ -73,14 +81,6 @@ namespace engine {
}
size_t
BufferProvider::getBufferSize (HashVal typeID) const
{
auto& typeKey = bufferStage_->lookup (typeID);
return typeKey.storageSize();
}
/** 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
@ -132,7 +132,7 @@ namespace engine {
auto& stateKey = bufferStage_->mark_locked (typeKey, storage, localTag);
return BuffHandle (BuffDescr(*this, HashVal(stateKey)), storage);
}
} // NOTE: not the underlying parent descriptor!
/** BufferProvider API: state transition to \em emitted state.
@ -205,11 +205,35 @@ namespace engine {
/* === BuffDescr and BuffHandle === */
/**
* A Buffer Descriptor is considered _valid_
* iff it represents a registered buffer type.
* @note this implies that the buffer size is not zero.
*/
bool
BuffDescr::verifyValidity() const
BuffDescr::isValid() const
{
ENSURE (provider_);
return provider_->verifyValidity(*this);
return provider_->verifyValidity (*this);
}
/**
* A concrete Buffer Handle is considered valid,
* iff it is currently registered in the buffer metadata table.
* @note this implies also that it is in some active state, and
* indirectly (due to the _Buffer Provider Protocol_) also
* that the _parent type_ is valid, which means that it was
* created from a valid BuffDescr. But note that we can not
* see this parent type without lookup by the BufferProvider;
* The embedded #descriptor_ is synthetic, and reflects the
* handle's _state-key_ (⟶ registry Entry) not the type-key.
*/
bool
BuffHandle::isValid() const
{
ENSURE (descriptor_.provider_);
return bool(pBuffer_)
and descriptor_.provider_->verifyValidity (*this);
}
@ -220,6 +244,11 @@ namespace engine {
return provider_->getBufferSize (*this);
}
size_t
BuffHandle::size() const
{
return descriptor_.buffSize();
}
uint
BuffDescr::announce (uint count)

28
src/steam/engine/buffhandle.hpp
View file

@ -91,7 +91,7 @@ namespace engine {
public:
// using standard copy operations
bool verifyValidity() const;
bool isValid() const;
size_t buffSize() const;
operator HashVal() const { return subClassification_; }
@ -126,16 +126,17 @@ namespace engine {
// using standard copy operations
explicit operator bool() const { return isValid(); }
explicit
operator bool() const { return isValid(); }
operator HashVal() const { return descriptor_; }
bool isValid() const;
size_t size() const;
void emit();
void release();
template<typename BU>
BU& create(); /////////////////////TICKET #1410 : this API needs to be retracted; it does not fit into the concept!
template<typename BU>
BU& accessAs();
@ -146,21 +147,6 @@ namespace engine {
return pBuffer_;
}
operator HashVal() const { return descriptor_; }
bool
isValid() const
{
return bool(pBuffer_)
and descriptor_.verifyValidity();
}
size_t
size() const
{
return descriptor_.buffSize();
}
private:
void emergencyCleanup();
};

3
src/steam/engine/simple-buffer-state-registry.hpp
View file

@ -50,7 +50,6 @@ namespace engine {
: public BufferProviderSetup::Stage
{
///////////////////////////////////////////////////////////////////////////////////////////////////////TICKET 1410 : rather hold BufferMetatdata object here
static const metadata::Key NULL_KEY; ////////////////////////////OOO better init directly here as constexpr (to keep it really an implementation detail)
/* === BufferStage interface === */
@ -58,7 +57,7 @@ namespace engine {
lookup (HashVal key) override
{
return this->isKnown(key)? this->get (key)
: NULL_KEY;
: metadata::Key::INVALID;
}
ID

7
tests/core/steam/engine/buffer-provider-protocol-test.cpp
View file

@ -126,9 +126,9 @@ namespace test {
BuffDescr desc1 = provider.getDescriptor<size_t>();
BuffDescr desc2 = provider.getDescriptor<TestFrame>(); // note: implies also sizeof(TestFrame)
BuffDescr desc3 = provider.getDescriptorFor(BUFFSIZ); // Can also request fixed sized raw storage.
// CHECK (desc1.verifyValidity()); /////////////////////////////////////////////////////////////////////////////OOO fails (which is wrong)
// CHECK (desc2.verifyValidity());
// CHECK (desc3.verifyValidity());
CHECK (desc1.isValid());
CHECK (desc2.isValid());
CHECK (desc3.isValid());
uint num1 = desc1.announce(TEST_ELMS);
uint num2 = desc1.announce(TEST_ELMS + 1);
@ -171,6 +171,7 @@ namespace test {
CHECK (workBuff.isValid());
auto endSum = workBuff.accessAs<TestFrame>().getChecksum();
workBuff.release(); // note: not every buffer need be emitted.
CHECK (!workBuff);
auto diagnostic = watch(provider);
CHECK (diagnostic.buffer_was_used (0));

1
tests/core/steam/engine/diagnostic-buffer-provider-test.cpp
View file

@ -97,6 +97,7 @@ namespace test {
provider.emitBuffer (testBuff);
provider.releaseBuffer(testBuff);
CHECK (not testBuff);
SHOW_EXPR(watch(provider).created.cnt())
SHOW_EXPR(watch(provider).emitted.cnt())
SHOW_EXPR(watch(provider).released.cnt())

30
wiki/thinkPad.ichthyo.mm
View file

@ -112871,6 +112871,17 @@ StM_bind(Builder&lt;R1&gt; b1, Extension&lt;R1,R2&gt; extension)
<arrowlink COLOR="#6b5f81" DESTINATION="ID_17538120" ENDARROW="Default" ENDINCLINATION="107;-147;" ID="Arrow_ID_196819766" STARTARROW="None" STARTINCLINATION="253;20;"/>
<icon BUILTIN="flag-yellow"/>
</node>
<node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1771195835031" ID="ID_465237496" MODIFIED="1771195857844" TEXT="BufferProvider &#x27f6; in Vault umziehen">
<icon BUILTIN="yes"/>
<node CREATED="1771196048101" ID="ID_1022260808" MODIFIED="1771196056256" TEXT="TypeHandler kann auch dorting"/>
<node CREATED="1771196057238" ID="ID_1561084245" MODIFIED="1771196061567" TEXT="LocalTag ebenfalls"/>
<node CREATED="1771196092641" ID="ID_1744271206" MODIFIED="1771196101419" TEXT="selbst BufferMetadata w&#xe4;re denkbar">
<node CREATED="1771196102899" ID="ID_840400814" MODIFIED="1771196126219" TEXT="es h&#xe4;ngt nur an dem Typ Buffer (opaque marker)"/>
<node CREATED="1771196377439" ID="ID_505136785" MODIFIED="1771196409447" TEXT="die Idee gef&#xe4;lt mir immer besser....">
<linktarget COLOR="#2016a3" DESTINATION="ID_505136785" ENDARROW="Default" ENDINCLINATION="-51;243;" ID="Arrow_ID_407734805" SOURCE="ID_1008519841" STARTARROW="None" STARTINCLINATION="-44;3;"/>
</node>
</node>
</node>
</node>
<node CREATED="1770590206837" ID="ID_933010628" MODIFIED="1770590228576" TEXT="den DiagnosticOutputSlot seitw&#xe4;rts abspalten">
<node CREATED="1770686001136" ID="ID_936149730" MODIFIED="1770686019100" TEXT="der mu&#xdf; dann u.U auf den DiagnosticBufferProvider aufsetzen"/>
@ -112898,8 +112909,8 @@ StM_bind(Builder&lt;R1&gt; b1, Extension&lt;R1,R2&gt; extension)
<node BACKGROUND_COLOR="#b7c4da" COLOR="#435e98" CREATED="1771012551876" HGAP="35" ID="ID_335656320" MODIFIED="1771012599378" TEXT="auch unterliegende Implementierung entfernt" VSHIFT="-1"/>
</node>
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1770857874819" ID="ID_17538120" MODIFIED="1771188423612" TEXT="Test-Pr&#xe4;dikate auf den Handles nachsch&#xe4;rfen">
<linktarget COLOR="#f03963" DESTINATION="ID_17538120" ENDARROW="Default" ENDINCLINATION="-605;990;" ID="Arrow_ID_600202029" SOURCE="ID_200153250" STARTARROW="None" STARTINCLINATION="-309;23;"/>
<linktarget COLOR="#6b5f81" DESTINATION="ID_17538120" ENDARROW="Default" ENDINCLINATION="107;-147;" ID="Arrow_ID_196819766" SOURCE="ID_809940304" STARTARROW="None" STARTINCLINATION="253;20;"/>
<linktarget COLOR="#f03963" DESTINATION="ID_17538120" ENDARROW="Default" ENDINCLINATION="-605;990;" ID="Arrow_ID_600202029" SOURCE="ID_200153250" STARTARROW="None" STARTINCLINATION="-309;23;"/>
<icon BUILTIN="flag-yellow"/>
<node CREATED="1770857900164" ID="ID_65421257" MODIFIED="1770857904935" TEXT="Buffer-Descriptor">
<node CREATED="1770857906234" ID="ID_1594660218" MODIFIED="1770857923105" TEXT="bool &#x2259; isValid"/>
@ -112930,13 +112941,20 @@ StM_bind(Builder&lt;R1&gt; b1, Extension&lt;R1,R2&gt; extension)
</node>
</node>
</node>
<node CREATED="1770859462386" ID="ID_1297864624" MODIFIED="1770859465934" TEXT="BuffHandle">
<node COLOR="#435e98" CREATED="1770859462386" ID="ID_1297864624" MODIFIED="1771199252122" TEXT="BuffHandle">
<node CREATED="1770857906234" ID="ID_805276321" MODIFIED="1770857923105" TEXT="bool &#x2259; isValid"/>
<node CREATED="1770859477409" ID="ID_516152791" MODIFIED="1770859484272" TEXT="Lookup per Key"/>
<node CREATED="1770859485339" ID="ID_834373171" MODIFIED="1770859494334" TEXT="Buffer-Speicher ist zug&#xe4;nglich">
<node CREATED="1770859498975" ID="ID_1377114926" MODIFIED="1770859505962" TEXT="also bereits alloziert und initialisiert"/>
<node CREATED="1770859506933" ID="ID_757349315" MODIFIED="1770859520599" TEXT="aber noch nicht &#xbb;emitted&#xab; oder &#xbb;discarded&#xab;"/>
<node COLOR="#338800" CREATED="1770859477409" ID="ID_516152791" MODIFIED="1771199260220" TEXT="Lookup per Key">
<icon BUILTIN="button_ok"/>
</node>
<node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1770859485339" ID="ID_834373171" MODIFIED="1771199569873" STYLE="fork" TEXT="Buffer-Speicher ist zug&#xe4;nglich">
<icon BUILTIN="flag-pink"/>
<node CREATED="1770859498975" ID="ID_1377114926" MODIFIED="1771199273091" TEXT="also bereits alloziert und initialisiert"/>
<node CREATED="1770859506933" ID="ID_757349315" MODIFIED="1771199273091" TEXT="aber noch nicht &#xbb;emitted&#xab; oder &#xbb;discarded&#xab;"/>
</node>
</node>
<node COLOR="#435e98" CREATED="1771199175381" ID="ID_525994985" MODIFIED="1771199244429" TEXT="size-Pr&#xe4;dikate"/>
<node COLOR="#435e98" CREATED="1771199190419" ID="ID_1603489467" MODIFIED="1771199245611" TEXT="bool-Check auch auf dem Key-Lookup">
<arrowlink COLOR="#3a6ae9" DESTINATION="ID_1934796966" ENDARROW="Default" ENDINCLINATION="-302;16;" ID="Arrow_ID_1829822624" STARTARROW="None" STARTINCLINATION="88;7;"/>
</node>
</node>
<node BACKGROUND_COLOR="#e0ceaa" COLOR="#690f14" CREATED="1770933762544" ID="ID_389070880" MODIFIED="1770933775068" TEXT="Tendenzen zeichnen sich ab...">