A registry whose live values are qualified by a monotonically increasing runtime generation. 更多...

#include <VersionedRegistry.h>

类
struct	Entry
	One stored key slot; absent value means the slot is a tombstone. 更多...

struct	Event
	One canonical mutation event retained by the registry. 更多...

struct	Handle
	Generation-qualified identity of one live incarnation or tombstone. 更多...

struct	State
	Owning state image used for transactional snapshot/restore. 更多...

Public 类型
using	GenerationProjector = std::function< void(Value &, Generation)>
	Callback used to keep a legacy value field as a read-only projection of generation.

using	ChangeCallback = std::function< void(const Event &)>

Public 成员函数
	VersionedRegistry (GenerationProjector generationProjector={})
	Constructs an empty registry.

	VersionedRegistry (const VersionedRegistry &)=delete

VersionedRegistry &	operator= (const VersionedRegistry &)=delete

	VersionedRegistry (VersionedRegistry &&)=delete

VersionedRegistry &	operator= (VersionedRegistry &&)=delete

	~VersionedRegistry ()=default

Result< Handle >	insert (Key key, Value value, EventData data={}, std::string label={})
	Inserts a new live value, or revives a tombstoned key.

Result< Handle >	replace (Key key, Value value, EventData data={}, std::string label={})
	Replaces an existing live value and invalidates its old handle.

Result< Handle >	remove (Key key, EventData data={}, std::string label={})
	Removes a live value while retaining its generation tombstone.

ResultRef< const Value >	resolve (const Key &key) const
	Resolves a live key to a borrowed value.

ResultRef< const Value >	resolve (const Handle &handle) const
	Resolves a generation-qualified handle.

Result< Handle >	handle (const Key &key) const
	Returns the current live handle for a key.

Result< Generation >	generationOf (const Key &key) const
	Returns the latest generation for a live key or tombstone.

bool	contains (const Key &key) const noexcept
	Returns whether a key currently has a live value.

bool	isTombstone (const Key &key) const noexcept
	Returns whether a key is retained as a removal tombstone.

bool	isStale (const Handle &handle) const noexcept
	Returns true when a handle cannot resolve to its exact live incarnation.

std::size_t	size () const noexcept
	Number of live values, excluding tombstones.

std::size_t	tombstoneCount () const noexcept
	Number of retained tombstone slots.

const Value *	at (std::size_t index) const noexcept
	Returns a live value by deterministic key order.

const Key *	keyAt (std::size_t index) const noexcept
	Returns the key for a live enumeration index, or nullptr.

const Event *	eventAt (std::size_t index) const noexcept
	Returns a retained event by insertion sequence order, or nullptr.

std::size_t	eventCount () const noexcept
	Number of retained mutation events.

void	clearEvents () noexcept
	Clears retained events without changing entries or sequence monotonicity.

State	snapshotState () const
	Takes an owning copy of live entries, tombstones and event history.

Result< void >	restoreState (State candidate)
	Transactionally replaces all registry state from an owning image.

Subscription	subscribe (ChangeCallback callback)
	Subscribes to successful insert, replace and remove events.

详细描述

template<class Key, class Value, class EventData = std::monostate, class Compare = std::less<Key>>
class eve::VersionedRegistry< Key, Value, EventData, Compare >

A registry whose live values are qualified by a monotonically increasing runtime generation.

Value is the live domain value. EventData is an optional, domain-owned immutable projection payload for event history; it is not interpreted by this class. The registry owns all live values, tombstones and canonical mutation events. Consumers must not maintain a second mutable map.

The class is owner-thread affine, matching eve::Observer. It is not an ECS container and does not perform structural mutation deferral.

Mutations have the strong state guarantee: all fallible value, event and generation-projection work is prepared in a detached State and committed with a nothrow swap. Observer dispatch happens after commit. If dispatch throws, the mutation remains applied and the Result is successful with an Applied status and a CallbackFailure warning; the committed state is never rolled back.

模板参数

Key	Stable registry key. It must be copyable and orderable through `Compare`.
Value	Stored domain value. It must be copyable when State snapshots are copied.
EventData	Domain event projection data; defaults to no extra data.
Compare	Strict weak ordering for keys; its State must be nothrow-swappable so the commit boundary cannot throw.

VersionedRegistry public API.

在文件 VersionedRegistry.h 第 134 行定义.

成员类型定义说明

◆ ChangeCallback

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

using eve::VersionedRegistry< Key, Value, EventData, Compare >::ChangeCallback = std::function<void(const Event&)>

在文件 VersionedRegistry.h 第 194 行定义.

◆ GenerationProjector

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

using eve::VersionedRegistry< Key, Value, EventData, Compare >::GenerationProjector = std::function<void(Value&, Generation)>

Callback used to keep a legacy value field as a read-only projection of generation.

在文件 VersionedRegistry.h 第 193 行定义.

构造及析构函数说明

◆ VersionedRegistry() [1/3]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

eve::VersionedRegistry< Key, Value, EventData, Compare >::VersionedRegistry ( GenerationProjector generationProjector = {} )

inlineexplicit

Constructs an empty registry.

参数

generationProjector Optional compatibility projection invoked before a value enters storage and after restore. It must not change domain identity or schema version.

在文件 VersionedRegistry.h 第 202 行定义.

◆ VersionedRegistry() [2/3]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

eve::VersionedRegistry< Key, Value, EventData, Compare >::VersionedRegistry ( const VersionedRegistry< Key, Value, EventData, Compare > & )

delete

◆ VersionedRegistry() [3/3]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

eve::VersionedRegistry< Key, Value, EventData, Compare >::VersionedRegistry ( VersionedRegistry< Key, Value, EventData, Compare > && )

delete

◆ ~VersionedRegistry()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

eve::VersionedRegistry< Key, Value, EventData, Compare >::~VersionedRegistry ( )

default

成员函数说明

◆ at()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

const Value * eve::VersionedRegistry< Key, Value, EventData, Compare >::at ( std::size_t index ) const

inlinenoexcept

Returns a live value by deterministic key order.

参数

index Zero-based index among live entries; out of range returns nullptr.

返回: Borrowed value, valid until the next mutation/restore.

备注: This is a read-only compatibility enumeration primitive; use the checked resolve operation for key/handle access. @ownership Borrowed; the registry owns the returned value. @nullable Yes when index is out of range. @lifetime Valid until the next mutation or restore, and only while this registry lives. @thread Owner-thread affine; no concurrent mutation is supported. @reentrancy Does not invoke observers.

在文件 VersionedRegistry.h 第 368 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, index , 以及 key.

被这些函数引用 eve::definitions::DefinitionRegistry::at(), eve::policyregistry::PolicyRegistry::at(), eve::policyregistry::PolicyRegistry::atDomain(), eve::definitions::DefinitionRegistry::atType() , 以及 eve::policyregistry::PolicyRegistry::select().

◆ clearEvents()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

void eve::VersionedRegistry< Key, Value, EventData, Compare >::clearEvents ( )

inlinenoexcept

Clears retained events without changing entries or sequence monotonicity.

在文件 VersionedRegistry.h 第 410 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::events.

被这些函数引用 eve::definitions::DefinitionRegistry::clearEvents() , 以及 eve::policyregistry::PolicyRegistry::clearEvents().

◆ contains()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

bool eve::VersionedRegistry< Key, Value, EventData, Compare >::contains ( const Key & key ) const

inlinenoexcept

Returns whether a key currently has a live value.

在文件 VersionedRegistry.h 第 322 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries , 以及 key.

◆ eventAt()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

const Event * eve::VersionedRegistry< Key, Value, EventData, Compare >::eventAt ( std::size_t index ) const

inlinenoexcept

Returns a retained event by insertion sequence order, or nullptr.

返回: Borrowed pointer into registry state; nullptr when index is out of range. @ownership Borrowed; the registry owns the event. @nullable Yes. @lifetime Valid until the next mutation or restore, and only while this registry lives. @thread Owner-thread affine; no concurrent mutation is supported. @reentrancy Does not invoke observers.

在文件 VersionedRegistry.h 第 402 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::events , 以及 index.

被这些函数引用 eve::definitions::DefinitionRegistry::eventAt() , 以及 eve::policyregistry::PolicyRegistry::eventAt().

◆ eventCount()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

std::size_t eve::VersionedRegistry< Key, Value, EventData, Compare >::eventCount ( ) const

inlinenoexcept

Number of retained mutation events.

在文件 VersionedRegistry.h 第 407 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::events.

被这些函数引用 eve::definitions::DefinitionRegistry::eventAt(), eve::policyregistry::PolicyRegistry::eventAt(), eve::definitions::DefinitionRegistry::eventCount(), eve::policyregistry::PolicyRegistry::eventCount(), eve::definitions::DefinitionRegistry::snapshotJson() , 以及 eve::policyregistry::PolicyRegistry::snapshotJson().

◆ generationOf()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Result< Generation > eve::VersionedRegistry< Key, Value, EventData, Compare >::generationOf ( const Key & key ) const

inline

Returns the latest generation for a live key or tombstone.

备注: This is deliberately not a SchemaVersion.

在文件 VersionedRegistry.h 第 313 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, eve::Diagnostic::error(), eve::Result< T >::failure(), key, eve::NotFound , 以及 eve::Result< T >::success().

被这些函数引用 eve::policyregistry::PolicyRegistry::generationOf() , 以及 eve::definitions::DefinitionRegistry::generationOf().

◆ handle()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Result< Handle > eve::VersionedRegistry< Key, Value, EventData, Compare >::handle ( const Key & key ) const

inline

Returns the current live handle for a key.

在文件 VersionedRegistry.h 第 302 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::VersionedRegistry< Key, Value, EventData, Compare >::Handle::generation, key, eve::NotFound , 以及 eve::Result< T >::success().

被这些函数引用 eve::policyregistry::PolicyRegistry::enable(), eve::policyregistry::PolicyRegistry::handle() , 以及 eve::definitions::DefinitionRegistry::handle().

◆ insert()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Result< Handle > eve::VersionedRegistry< Key, Value, EventData, Compare >::insert	(	Key	key,
		Value	value,
		EventData	data = `{}`,
		std::string	label = `{}`
	)

inline

Inserts a new live value, or revives a tombstoned key.

参数

key	Stable key to insert.
value	Owning value to store.
data	Domain data retained with the mutation event.
label	Optional domain event label; the operation remains Insert.

返回: A handle for the new incarnation, or Conflict/Failed.

在文件 VersionedRegistry.h 第 219 行定义.

被这些函数引用 eve::policyregistry::PolicyRegistry::insert() , 以及 eve::definitions::DefinitionRegistry::insert().

◆ isStale()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

bool eve::VersionedRegistry< Key, Value, EventData, Compare >::isStale ( const Handle & handle ) const

inlinenoexcept

Returns true when a handle cannot resolve to its exact live incarnation.

在文件 VersionedRegistry.h 第 334 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries , 以及 handle.

◆ isTombstone()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

bool eve::VersionedRegistry< Key, Value, EventData, Compare >::isTombstone ( const Key & key ) const

inlinenoexcept

Returns whether a key is retained as a removal tombstone.

在文件 VersionedRegistry.h 第 328 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries , 以及 key.

◆ keyAt()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

const Key * eve::VersionedRegistry< Key, Value, EventData, Compare >::keyAt ( std::size_t index ) const

inlinenoexcept

Returns the key for a live enumeration index, or nullptr.

返回: Borrowed pointer into registry state; nullptr when index is out of range. @ownership Borrowed; the registry owns the key. @nullable Yes. @lifetime Valid until the next mutation or restore, and only while this registry lives. @thread Owner-thread affine; no concurrent mutation is supported. @reentrancy Does not invoke observers.

在文件 VersionedRegistry.h 第 385 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, index , 以及 key.

被这些函数引用 eve::policyregistry::PolicyRegistry::atDomain(), eve::definitions::DefinitionRegistry::atType(), eve::policyregistry::PolicyRegistry::countDomain(), eve::definitions::DefinitionRegistry::countType() , 以及 eve::policyregistry::PolicyRegistry::select().

◆ operator=() [1/2]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

VersionedRegistry & eve::VersionedRegistry< Key, Value, EventData, Compare >::operator= ( const VersionedRegistry< Key, Value, EventData, Compare > & )

delete

◆ operator=() [2/2]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

VersionedRegistry & eve::VersionedRegistry< Key, Value, EventData, Compare >::operator= ( VersionedRegistry< Key, Value, EventData, Compare > && )

delete

◆ remove()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Result< Handle > eve::VersionedRegistry< Key, Value, EventData, Compare >::remove	(	Key	key,
		EventData	data = `{}`,
		std::string	label = `{}`
	)

inline

Removes a live value while retaining its generation tombstone.

参数

key	Key to remove.
data	Domain data describing the removed value.
label	Optional domain event label; the operation remains Remove.

返回: A tombstone handle, or NotFound/Failed.

在文件 VersionedRegistry.h 第 260 行定义.

被这些函数引用 eve::policyregistry::PolicyRegistry::remove() , 以及 eve::definitions::DefinitionRegistry::remove().

◆ replace()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Result< Handle > eve::VersionedRegistry< Key, Value, EventData, Compare >::replace	(	Key	key,
		Value	value,
		EventData	data = `{}`,
		std::string	label = `{}`
	)

inline

Replaces an existing live value and invalidates its old handle.

参数

key	Stable registry key to replace.
value	Owning replacement value.
data	Domain data retained with the mutation event.
label	Optional domain event label; the operation remains Replace.

返回: A handle for the replacement incarnation, or NotFound/Failed.

在文件 VersionedRegistry.h 第 240 行定义.

被这些函数引用 eve::policyregistry::PolicyRegistry::enable(), eve::policyregistry::PolicyRegistry::replace() , 以及 eve::definitions::DefinitionRegistry::replace().

◆ resolve() [1/2]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

ResultRef< const Value > eve::VersionedRegistry< Key, Value, EventData, Compare >::resolve ( const Handle & handle ) const

inline

Resolves a generation-qualified handle.

返回: A borrowed reference for the exact live incarnation, or StaleHandle/NotFound.

在文件 VersionedRegistry.h 第 290 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, eve::Diagnostic::error(), handle, eve::NotFound, eve::StaleHandle , 以及 eve::Result< T >::success().

◆ resolve() [2/2]

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

ResultRef< const Value > eve::VersionedRegistry< Key, Value, EventData, Compare >::resolve ( const Key & key ) const

inline

Resolves a live key to a borrowed value.

返回: A borrowed reference valid until the next mutation/restore, or NotFound when the key is absent or tombstoned.

在文件 VersionedRegistry.h 第 277 行定义.

引用了 eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, eve::Diagnostic::error(), key, eve::NotFound , 以及 eve::Result< T >::success().

被这些函数引用 eve::policyregistry::PolicyRegistry::enable(), eve::policyregistry::PolicyRegistry::remove(), eve::definitions::DefinitionRegistry::remove(), eve::policyregistry::PolicyRegistry::resolve(), eve::definitions::DefinitionRegistry::resolve(), eve::definitions::DefinitionRegistry::resolveHandle() , 以及 eve::policyregistry::PolicyRegistry::resolveHandle().

◆ restoreState()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Result< void > eve::VersionedRegistry< Key, Value, EventData, Compare >::restoreState ( State candidate )

inline

Transactionally replaces all registry state from an owning image.

参数

candidate State to validate and install.

返回: Success, or ParseError/Failed without changing current state.

备注: Generation projection is applied only to the candidate. If it throws, the current state remains installed and the exception is returned as a Failed diagnostic.

在文件 VersionedRegistry.h 第 423 行定义.

引用了 eve::detail::EventLogValidator::accept(), boundary, eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries, eve::Diagnostic::error(), eve::VersionedRegistry< Key, Value, EventData, Compare >::State::events, eve::Failed, eve::Result< T >::failure(), eve::detail::EventLogValidator::finish(), key, eve::VersionedRegistry< Key, Value, EventData, Compare >::State::nextEventSequence, eve::ParseError, eve::Remove, eve::Result< T >::success(), eve::VersionedRegistry< Key, Value, EventData, Compare >::State::swap() , 以及 eve::detail::validateRegistryNextSequence().

被这些函数引用 eve::definitions::DefinitionRegistry::restoreJson() , 以及 eve::policyregistry::PolicyRegistry::restoreJson().

◆ size()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

std::size_t eve::VersionedRegistry< Key, Value, EventData, Compare >::size ( ) const

inlinenoexcept

Number of live values, excluding tombstones.

在文件 VersionedRegistry.h 第 341 行定义.

引用了 count, eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries , 以及 key.

被这些函数引用 eve::definitions::DefinitionRegistry::size(), eve::policyregistry::PolicyRegistry::size(), eve::definitions::DefinitionRegistry::snapshotJson() , 以及 eve::policyregistry::PolicyRegistry::snapshotJson().

◆ snapshotState()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

State eve::VersionedRegistry< Key, Value, EventData, Compare >::snapshotState ( ) const

inline

Takes an owning copy of live entries, tombstones and event history.

在文件 VersionedRegistry.h 第 413 行定义.

被这些函数引用 eve::definitions::DefinitionRegistry::snapshotJson() , 以及 eve::policyregistry::PolicyRegistry::snapshotJson().

◆ subscribe()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

Subscription eve::VersionedRegistry< Key, Value, EventData, Compare >::subscribe ( ChangeCallback callback )

inline

Subscribes to successful insert, replace and remove events.

参数

callback Synchronously invoked after a successful state commit.

返回: Move-only owner-thread-affine cancellation token.

警告: Callback exceptions are caught by the mutation operation and reported as an Applied Result with a CallbackFailure warning.

在文件 VersionedRegistry.h 第 461 行定义.

引用了 callback.

被这些函数引用 eve::definitions::DefinitionRegistry::subscribe() , 以及 eve::policyregistry::PolicyRegistry::subscribe().

◆ tombstoneCount()

template<class Key , class Value , class EventData = std::monostate, class Compare = std::less<Key>>

std::size_t eve::VersionedRegistry< Key, Value, EventData, Compare >::tombstoneCount ( ) const

inlinenoexcept

Number of retained tombstone slots.

在文件 VersionedRegistry.h 第 349 行定义.

引用了 count, eve::VersionedRegistry< Key, Value, EventData, Compare >::State::entries , 以及 key.

该类的文档由以下文件生成:

src/engine/common/VersionedRegistry.h

类

Public 类型

Public 成员函数

详细描述

成员类型定义说明

◆ ChangeCallback

◆ GenerationProjector

构造及析构函数说明

◆ VersionedRegistry() [1/3]

◆ VersionedRegistry() [2/3]

◆ VersionedRegistry() [3/3]

◆ ~VersionedRegistry()

成员函数说明

◆ at()

◆ clearEvents()

◆ contains()

◆ eventAt()

◆ eventCount()

◆ generationOf()

◆ handle()

◆ insert()

◆ isStale()

◆ isTombstone()

◆ keyAt()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ remove()

◆ replace()

◆ resolve() [1/2]

◆ resolve() [2/2]

◆ restoreState()

◆ size()

◆ snapshotState()

◆ subscribe()

◆ tombstoneCount()