A blackboard is a key/value store that provides OnChange events to be informed when a value changes. More...

#include <Blackboard.h>

Inheritance diagram for xiiBlackboard:

Classes
struct	Entry

struct	EntryEvent

Public Member Functions
bool	IsGlobalBlackboard () const

void	SetName (xiiStringView sName)
	Changes the name of the blackboard.

xiiStringView	GetName () const

const xiiHashedString &	GetNameHashed () const

void	RemoveEntry (const xiiHashedString &sName)
	Removes the named entry. Does nothing, if no such entry exists.

void	RemoveAllEntries ()
	Removes all entries.

bool	HasEntry (const xiiTempHashedString &sName) const
	Returns whether an entry with the given name already exists.

void	SetEntryValue (xiiStringView sName, const xiiVariant &value)
	Sets the value of the named entry. If the entry doesn't exist, yet, it will be created with default flags.

void	SetEntryValue (const xiiHashedString &sName, const xiiVariant &value)
	Overload of SetEntryValue() that takes a xiiHashedString rather than a xiiStringView.

const Entry *	GetEntry (const xiiTempHashedString &sName) const
	Returns a pointer to the named entry, or nullptr if no such entry was registered.

xiiBitflags< xiiBlackboardEntryFlags >	GetEntryFlags (const xiiTempHashedString &sName) const
	Returns the flags of the named entry, or xiiBlackboardEntryFlags::Invalid, if no such entry was registered.

xiiResult	SetEntryFlags (const xiiTempHashedString &sName, xiiBitflags< xiiBlackboardEntryFlags > flags)
	Sets the flags of an existing entry. Returns XII_FAILURE, if it wasn't created via SetEntryValue() or SetEntryValue() before.

xiiVariant	GetEntryValue (const xiiTempHashedString &sName, const xiiVariant &fallback=xiiVariant()) const
	Returns the value of the named entry, or the fallback xiiVariant, if no such entry was registered.

xiiVariant	IncrementEntryValue (const xiiTempHashedString &sName)
	Increments the value of the named entry. Returns the incremented value or an invalid variant if the entry does not exist or is not a number type.

xiiVariant	DecrementEntryValue (const xiiTempHashedString &sName)
	Decrements the value of the named entry. Returns the decremented value or an invalid variant if the entry does not exist or is not a number type.

const xiiHashTable< xiiHashedString, Entry > &	GetAllEntries () const
	Grants read access to the entire map of entries.

const xiiEvent< const EntryEvent & > &	OnEntryEvent () const
	Allows you to register to the OnEntryEvent. This is broadcast whenever an entry is modified that has the flag xiiBlackboardEntryFlags::OnChangeEvent.

xiiUInt32	GetBlackboardChangeCounter () const
	This counter is increased every time an entry is added or removed (but not when it is modified).

xiiUInt32	GetBlackboardEntryChangeCounter () const
	This counter is increased every time any entry's value is modified.

xiiResult	Serialize (xiiStreamWriter &ref_stream) const
	Stores all entries that have the 'Save' flag in the stream.

xiiResult	Deserialize (xiiStreamReader &ref_stream)
	Restores entries from the stream.

Public Member Functions inherited from xiiRefCounted
virtual	~xiiRefCounted ()=default
	Adds a virtual destructor.

Public Member Functions inherited from xiiRefCountingImpl
	xiiRefCountingImpl ()=default
	Constructor.

	xiiRefCountingImpl (const xiiRefCountingImpl &rhs)

void	operator= (const xiiRefCountingImpl &rhs)

xiiUInt32	AddRef () const
	Increments the reference counter. Returns the new reference count.

xiiUInt32	ReleaseRef () const
	Decrements the reference counter. Returns the new reference count.

bool	IsReferenced () const
	Returns true if the reference count is greater than 0, false otherwise.

xiiUInt32	GetRefCount () const
	Returns the current reference count.

Static Public Member Functions
static xiiSharedPtr< xiiBlackboard >	Create (xiiAllocatorBase *pAllocator=xiiFoundation::GetDefaultAllocator())
	Factory method to create a new blackboard.

static xiiSharedPtr< xiiBlackboard >	GetOrCreateGlobal (const xiiHashedString &sBlackboardName, xiiAllocatorBase *pAllocator=xiiFoundation::GetDefaultAllocator())
	Factory method to get access to a globally registered blackboard.

static xiiSharedPtr< xiiBlackboard >	FindGlobal (const xiiTempHashedString &sBlackboardName)
	Finds a global blackboard with the given name.

Detailed Description

A blackboard is a key/value store that provides OnChange events to be informed when a value changes.

Blackboards are used to gather typically small pieces of data. Some systems write the data, other systems read it. Through the blackboard, arbitrary systems can interact.

For example this is commonly used in game AI, where some system gathers interesting pieces of data about the environment, and then NPCs might use that information to make decisions.

Member Function Documentation

◆ Create()

xiiSharedPtr< xiiBlackboard > xiiBlackboard::Create ( xiiAllocatorBase * pAllocator = xiiFoundation::GetDefaultAllocator() )

static

Factory method to create a new blackboard.

Since blackboards use shared ownership we need to make sure that blackboards are created in xiiCore.dll. Some compilers (MSVC) create local v-tables which can become stale if a blackboard was registered as global but the DLL which created the blackboard is already unloaded.

See https://groups.google.com/g/microsoft.public.vc.language/c/atSh_2VSc2w/m/EgJ3r_7OzVUJ?pli=1

◆ Deserialize()

xiiResult xiiBlackboard::Deserialize ( xiiStreamReader & ref_stream )

Restores entries from the stream.

If the blackboard already contains entries, the deserialized data is ADDED to the blackboard. If deserialized entries overlap with existing ones, the deserialized entries will overwrite the existing ones (both values and flags).

◆ GetBlackboardChangeCounter()

xiiUInt32 xiiBlackboard::GetBlackboardChangeCounter ( ) const

inline

This counter is increased every time an entry is added or removed (but not when it is modified).

Comparing this value to a previous known value allows to quickly detect whether the set of entries has changed.

◆ GetBlackboardEntryChangeCounter()

xiiUInt32 xiiBlackboard::GetBlackboardEntryChangeCounter ( ) const

inline

This counter is increased every time any entry's value is modified.

Comparing this value to a previous known value allows to quickly detect whether any entry has changed recently.

◆ GetOrCreateGlobal()

xiiSharedPtr< xiiBlackboard > xiiBlackboard::GetOrCreateGlobal	(	const xiiHashedString &	sBlackboardName,
		xiiAllocatorBase *	pAllocator = xiiFoundation::GetDefaultAllocator() )

static

Factory method to get access to a globally registered blackboard.

If a blackboard with that name was already created globally before, its reference is returned. Otherwise it will be created and permanently registered under that name. Global blackboards cannot be removed. Although you can change their name via "SetName()", the name under which they are registered globally will not change.

If at some point you want to "remove" a global blackboard, instead call UnregisterAllEntries() to clear all its values.

◆ SetEntryValue() [1/2]

void xiiBlackboard::SetEntryValue	(	const xiiHashedString &	sName,
		const xiiVariant &	value )

Overload of SetEntryValue() that takes a xiiHashedString rather than a xiiStringView.

Using this function is more efficient, if you access the blackboard often, but you must ensure to only create the xiiHashedString once and cache it for reuse. Assigning a value to a xiiHashedString is an expensive operation, so if you do not cache the string, prefer to use the other overload.

◆ SetEntryValue() [2/2]

void xiiBlackboard::SetEntryValue	(	xiiStringView	sName,
		const xiiVariant &	value )

Sets the value of the named entry. If the entry doesn't exist, yet, it will be created with default flags.

If the 'OnChangeEvent' flag is set for this entry, OnEntryEvent() will be broadcast. However, if the new value is no different to the old, no event will be broadcast.

For new entries, no OnEntryEvent() is sent.

For best efficiency, cache the entry name in a xiiHashedString and use the other overload of this function. DO NOT RECREATE the xiiHashedString every time, though.

◆ SetName()

void xiiBlackboard::SetName ( xiiStringView sName )

Changes the name of the blackboard.

Note: For global blackboards this has no effect under which name they are found. A global blackboard continues to be found by the name under which it was originally registered.

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

/home/runner/work/XII/XII/Source/Engine/Core/Utils/Blackboard.h
/home/runner/work/XII/XII/Source/Engine/Core/Utils/Implementation/Blackboard.cpp

Classes

Public Member Functions

Static Public Member Functions