This concrete class implements a simple Model Database. More...

Detailed Description

This concrete class implements a simple Model Database.

Note: The model point instances are contained in SList. This is to reduce the RAM overhead on each Model Point instance (e.g. a MapItem has 32 bytes of overhead vs. 8 bytes for Item). This means that looking up a model point by name is not efficient. However, the typically use case for the look-up function is when reading/writing model point via the TShell command shell the performance impact should not be noticeable.

The SList is sorted alphabetically on the first call to getFirstByName().

Note: All of the methods are thread safe. However, since the Model Database instances are typically created statically and statically allocated Model point self-register there is race condition on when the Model Database instance's Mutex is created/initialize. As a result mutex is dynamically created/initialized on its first usage.

#include <ModelDatabase.h>

Inheritance diagram for Cpl::Dm::ModelDatabase:

[legend]

Collaboration diagram for Cpl::Dm::ModelDatabase:

[legend]

Public Member Functions
	ModelDatabase () noexcept
	Constructor.

	ModelDatabase (const char *ignoreThisParameter_usedToCreateAUniqueConstructor) noexcept
	This is a special constructor for when the Model Database is statically declared (i.e.

	~ModelDatabase () noexcept
	Destructor.

ModelPoint *	lookupModelPoint (const char *modelPointName) noexcept
	See Cpl::Dm::ModelDatabaseApi.

ModelPoint *	getFirstByName () noexcept
	See Cpl::Dm::ModelDatabaseApi.

ModelPoint *	getNextByName (ModelPoint &currentModelPoint) noexcept
	See Cpl::Dm::ModelDatabaseApi.

bool	fromJSON (const char src, Cpl::Text::String errorMsg=0, ModelPoint *retMp=0, uint16_t retSequenceNumber=0) noexcept
	See Cpl::Dm::ModelDatabaseApi.

void	insert_ (ModelPoint &mpToAdd) noexcept
	This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

void	lock_ () noexcept
	This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

void	unlock_ () noexcept
	This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

Public Member Functions inherited from Cpl::Dm::ModelDatabaseApi
virtual	~ModelDatabaseApi ()
	Virtual destructor to make the compiler happy.

Static Public Member Functions
static void	globalLock_ () noexcept
	This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

static void	globalUnlock_ () noexcept
	This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

Static Public Attributes
static StaticJsonDocument< OPTION_CPL_DM_MODEL_DATABASE_MAX_CAPACITY_JSON_DOC >	g_doc_
	This variable has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

Protected Member Functions
bool	createLock ()
	Helper method to create the database lock.

virtual void	sortList () noexcept
	Helper method to sort the model point list alphabetical.

virtual ModelPoint *	find (const char *name) noexcept
	Helper method to find a point by name.

Protected Attributes
Cpl::Container::SList< ModelPoint >	m_list
	Map to the store the Model Points.

Cpl::System::Mutex *	m_lock
	Mutex for making the Database thread safe.

bool	m_listSorted
	Keep track if the point list has beed sorted.

Constructor & Destructor Documentation

◆ ModelDatabase() [1/2]

Cpl::Dm::ModelDatabase::ModelDatabase ( )

noexcept

Constructor.

◆ ModelDatabase() [2/2]

Cpl::Dm::ModelDatabase::ModelDatabase ( const char * ignoreThisParameter_usedToCreateAUniqueConstructor )

noexcept

This is a special constructor for when the Model Database is statically declared (i.e.

it is initialized as part of C++ startup BEFORE main() is executed. C/C++ does NOT guarantee the order of static initializers. Since the Model Database contains a list of model points - and one or more of those model points can be statically created/initialized - we need to do something to ensure my internal list is properly initialized for this scenario - hence this constructor.

◆ ~ModelDatabase()

Cpl::Dm::ModelDatabase::~ModelDatabase ( )

noexcept

Destructor.

Member Function Documentation

◆ createLock()

bool Cpl::Dm::ModelDatabase::createLock ( )

protected

Helper method to create the database lock.

◆ find()

virtual ModelPoint * Cpl::Dm::ModelDatabase::find ( const char * name )

protectedvirtualnoexcept

Helper method to find a point by name.

◆ fromJSON()

bool Cpl::Dm::ModelDatabase::fromJSON	(	const char *	src,
		Cpl::Text::String *	errorMsg = `0`,
		ModelPoint **	retMp = `0`,
		uint16_t *	retSequenceNumber = `0`
	)

virtualnoexcept

See Cpl::Dm::ModelDatabaseApi.

Implements Cpl::Dm::ModelDatabaseApi.

◆ getFirstByName()

ModelPoint * Cpl::Dm::ModelDatabase::getFirstByName ( )

virtualnoexcept

See Cpl::Dm::ModelDatabaseApi.

Implements Cpl::Dm::ModelDatabaseApi.

◆ getNextByName()

ModelPoint * Cpl::Dm::ModelDatabase::getNextByName ( ModelPoint & currentModelPoint )

virtualnoexcept

See Cpl::Dm::ModelDatabaseApi.

Implements Cpl::Dm::ModelDatabaseApi.

◆ globalLock_()

static void Cpl::Dm::ModelDatabase::globalLock_ ( )

staticnoexcept

This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

It is ONLY public to avoid the tight coupling of C++ friend mechanism.

This method provides a single global lock for ALL Model Database instances. The method is used to protect global Model Database (e.g. the global parse buffer).

This method locks the global Model Database lock. For every call to globalLock_() there must be corresponding call to globalUnlock_();

◆ globalUnlock_()

static void Cpl::Dm::ModelDatabase::globalUnlock_ ( )

staticnoexcept

This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

It is ONLY public to avoid the tight coupling of C++ friend mechanism.

This method unlocks the global Model Database lock

◆ insert_()

void Cpl::Dm::ModelDatabase::insert_ ( ModelPoint & mpToAdd )

noexcept

This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

It is ONLY public to avoid the tight coupling of C++ friend mechanism.

This method inserts a new Model Point into the Model Database.

◆ lock_()

void Cpl::Dm::ModelDatabase::lock_ ( )

noexcept

This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

It is ONLY public to avoid the tight coupling of C++ friend mechanism.

This method locks the Model Database. For every call to lock() there must be corresponding call to unlock();

◆ lookupModelPoint()

ModelPoint * Cpl::Dm::ModelDatabase::lookupModelPoint ( const char * modelPointName )

virtualnoexcept

See Cpl::Dm::ModelDatabaseApi.

Implements Cpl::Dm::ModelDatabaseApi.

◆ sortList()

virtual void Cpl::Dm::ModelDatabase::sortList ( )

protectedvirtualnoexcept

Helper method to sort the model point list alphabetical.

◆ unlock_()

void Cpl::Dm::ModelDatabase::unlock_ ( )

noexcept

This method has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

It is ONLY public to avoid the tight coupling of C++ friend mechanism.

This method unlocks the Model Database.

Member Data Documentation

◆ g_doc_

StaticJsonDocument<OPTION_CPL_DM_MODEL_DATABASE_MAX_CAPACITY_JSON_DOC> Cpl::Dm::ModelDatabase::g_doc_

static

This variable has 'PACKAGE Scope' in that is should only be called by other classes in the Cpl::Dm namespace.

It is ONLY public to avoid the tight coupling of C++ friend mechanism.

Global/single instance of a JSON document. Model Point's need to have acquired the global lock before using this buffer

◆ m_list

Cpl::Container::SList<ModelPoint> Cpl::Dm::ModelDatabase::m_list

protected

Map to the store the Model Points.

◆ m_listSorted

bool Cpl::Dm::ModelDatabase::m_listSorted

protected

Keep track if the point list has beed sorted.

◆ m_lock

Cpl::System::Mutex* Cpl::Dm::ModelDatabase::m_lock

protected

Mutex for making the Database thread safe.

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

Cpl/Dm/ModelDatabase.h

Detailed Description

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ ModelDatabase() [1/2]

◆ ModelDatabase() [2/2]

◆ ~ModelDatabase()

Member Function Documentation

◆ createLock()

◆ find()

◆ fromJSON()

◆ getFirstByName()

◆ getNextByName()

◆ globalLock_()

◆ globalUnlock_()

◆ insert_()

◆ lock_()

◆ lookupModelPoint()

◆ sortList()

◆ unlock_()

Member Data Documentation

◆ g_doc_

◆ m_list

◆ m_listSorted

◆ m_lock