Template Struct Store
Defined in File asset-mgr.h
Nested Relationships
Nested Types
Inheritance Relationships
Base Type
public CE::Assets::Cache::Context(Class Context)
Struct Documentation
-
template<typename AssetType, typename Key = std::filesystem::path, typename Allocator = std::allocator<std::pair<const Key, std::shared_ptr<AssetType>>>>
struct Store : public CE::Assets::Cache::Context Caches constructed assets by key.
reserve() provides storage whose slots callers construct selectively with emplace(); the older allocate() interface returns unconstructed handles for manual construction. Publish complete assets under a unique lock; readers copy retained handles under a shared lock. Construction and final release happen outside the lock.
Public Types
-
using Handle = std::shared_ptr<AssetType>
Independent retained asset owner copied under the cache lock.
-
using key_type = Key
Exact unordered-map identity; normalization/aliases belong to a derived manager.
-
using Catalogue = AssetCatalogue<AssetType, Key>
CPU-only source, qualified by this asset namespace and exact key type.
Public Functions
-
Store() = default
Create an empty synchronized strong-handle cache with its own diagnostic identity; global provider binding is deferred until a derived loading operation.
-
inline virtual ~Store()
Clear this cache outside final-deleter lock scopes.
Quiesce users before facade destruction; independently retained handles may outlive it. Closes the retained catalogue source and discards pending observations without Reset or callbacks.
-
inline Catalogue catalogue() const noexcept
Declaration:
[[nodiscard]]Return a copyable CPU-only source.
Its snapshots/watch seeds contain exact keys, checked generations, revision/loss state and optional native-domain tokens. It retains no asset, provider or Context. Source destruction cleanup is silent; a retained source reports closed after Store destruction.
-
inline EntrySnapshot asset_snapshot(const Key &key) const
Declaration:
[[nodiscard]]Select the exact-key strong handle and its generation/provenance under one shared lock.
Missing keys have null asset/absent generation. Old snapshots retain old handles across replacement/clear; catalogue identity/revision does not authorize native use. Check the separate domain token.
-
inline virtual Handle get_asset(const Key &key) const
Declaration:
[[nodiscard]]Copy an exact-key strong owner under a shared lock.
- Parameters:
key – Stable exact map key; base lookup performs no normalization, load or fallback.
- Returns:
Retained handle or null when missing, independent of later replacement/clear. Derived managers may define explicit alias policies; native use retains backend-domain limits.
-
inline bool contains(const Key &key) const
Declaration:
[[nodiscard]]Test exact-key presence under a shared lock without retaining/loading the asset.
- Parameters:
key – Exact key; no derived get_asset() fallback is invoked.
- Returns:
Presence at this observation, not a reservation against later changes.
-
inline std::size_t size() const
Declaration:
[[nodiscard]]- Returns:
Copied current key count under a shared lock, not external owner/resource residency count.
-
inline Stats diagnostics() const
Declaration:
[[nodiscard]]- Returns:
Consistent copied map/count statistics under a shared lock, without logging/native calls.
-
inline virtual void clear_assets() noexcept
Detach every map entry under its write lock, then release retired handles after unlocking.
Commit derived clear_metadata() before one optional Reset observation with a new revision. Preserves allocator identity and cumulative publication/replacement counters. Independent readers retain old assets. Observation allocation/bus failure cannot escape; loss is visible in the catalogue snapshot. Allocator/locking failure or revision exhaustion terminates because this operation is noexcept.
Protected Functions
-
inline explicit Store(const Allocator &allocator)
Create an empty cache using the supplied map allocator identity.
- Parameters:
allocator – Copied allocator retained by the map; clear_assets() preserves this identity.
-
inline virtual void clear_metadata() noexcept
-
inline Handle publish_asset(const Key &key, Handle asset)
Publish a nonnull complete candidate only if the exact key is absent.
- Parameters:
key – Exact publication key.
asset – Retained candidate built before taking the cache write lock.
- Returns:
Existing winner or newly published handle. Null input throws failed_operation; required map/generation bookkeeping failure leaves existing entries unchanged and candidate destruction outside the write lock. Cache hits do not advance catalogue revision or emit a change. Optional payload allocation/notification failure cannot reject a successful commit.
-
template<typename Published>
inline Handle publish_asset(const Key &key, Handle asset, Published &&published) Publish-or-observe a key, then commit prepared derived metadata while holding the write lock.
- Template Parameters:
Published – Statically nothrow-invocable callback; it must not reenter this cache.
- Parameters:
key – Exact identity.
asset – Nonnull completed candidate.
published – Invoked after successful map lookup/insertion, including when an entry already existed.
- Returns:
Existing or newly inserted retained owner. Candidate construction and final release remain outside the lock; allocation failure occurs before the metadata callback.
-
inline Handle replace_asset(const Key &key, Handle asset)
Atomically replace/insert one exact key under the cache write lock.
- Parameters:
key – Exact identity.
asset – Nonnull completed candidate built before publication.
- Returns:
Retained new owner; old readers retain old generations. Null candidates throw failed_operation; map allocation failure preserves the previous entry. Final retired-owner release occurs after unlocking; no multi-key transaction is provided. Commits new generation/revision metadata with the handle, then attempts an isolated catalogue observation. Native provenance uses the bound provider’s token; unavailable domains reject publication.
-
template<typename Derived>
inline auto reserve(const std::size_t N) Reserve raw slots for selective construction with emplace().
Reserve unconstructed pool slots for selective construction with Reservation::emplace().
See also
- Template Parameters:
Derived – AssetType-derived object type.
- Parameters:
N – Slot count, zero creates an empty reservation.
- Returns:
Move-only reservation retaining its release context; constructed handles may outlive the cache/reservation. No cache key is published.
Provide raw object handles for callers that construct slots manually.
Legacy raw-slot allocation for callers that explicitly construct each object.
- Template Parameters:
Derived – AssetType-derived class.
- Parameters:
N – Requested slot count; zero returns an empty vector.
- Returns:
Independent per-slot handles retaining pool release context; this helper does not construct objects or publish cache entries. Callers must use the compatible construction tracker before dereferencing live objects. Final release destroys a tracked live slot and returns exactly that slot; allocation failures propagate. Prefer reserve()/emplace() for safe selective construction.
Protected Attributes
-
std::shared_mutex &assets_mutex_ = catalogue_.state_->mutex
Shared cache/catalogue commit lock.
-
std::unordered_map<Key, Handle, std::hash<Key>, std::equal_to<Key>, Allocator> loaded_assets = {}
Strong key-to-generation owners; direct access requires the corresponding lock.
-
const CE::Diagnostics::DomainId domain_ = catalogue_.state_->id
Checked catalogue/cache identity, separate from native provenance.
-
std::uint64_t publications_ = 0
New-key count protected by assets_mutex_.
-
std::uint64_t replacements_ = 0
Existing-key replacement count protected by assets_mutex_.
-
using Handle = std::shared_ptr<AssetType>