Base class for storing persistent binary data to a file or retained memory. More...

#include <StorageHelperRK.h>

Inheritance diagram for StorageHelperRK::PersistentDataBase:

Data Structures
class	SavedDataHeader
	Header at the beginning of all saved data stored in RAM, retained memory, or a file. More...

Public Member Functions
	PersistentDataBase (SavedDataHeader *savedDataHeader, size_t savedDataSize, uint32_t savedDataMagic, uint16_t savedDataVersion)
	Base class for persistent data saved in file or RAM. More...

PersistentDataBase &	withSaveDelayMs (uint32_t value)
	Sets the wait to save delay. Default is 1000 milliseconds. More...

virtual void	setup ()
	Initialize this object for use in StorageHelperRK. More...

virtual bool	load ()
	Load the persistent data file. You normally do not need to call this; it will be loaded automatically. More...

virtual void	save ()
	Save the persistent data file. You normally do not need to call this; it will be saved automatically. More...

virtual void	flush (bool force)
	Write the settings to disk if changed and the wait to save time has expired. More...

virtual void	saveOrDefer ()
	Either saves data or immediately, or defers until later, based on saveDelayMs. More...

template<class T >
T	getValue (size_t offset) const
	Templated class for getting integral values (uint32_t, float, double, etc.) More...

template<class T >
void	setValue (size_t offset, T value)
	Templated class for setting integral values (uint32_t, float, double, etc.) More...

bool	getValueString (size_t offset, size_t size, String &value) const
	Get the value of a string. More...

bool	setValueString (size_t offset, size_t size, const char *value)
	Set the value of a string. More...

uint32_t	getHash () const
	Get the hash valid for data integrity checking.

Public Member Functions inherited from StorageHelperRK::CustomRecursiveMutex
	CustomRecursiveMutex (os_mutex_recursive_t handle)
	Construct a CustomRecursiveMutex wrapper object from an existing recursive mutex. More...

	CustomRecursiveMutex ()
	Default constructor with no mutex - one will be created on first lock.

	~CustomRecursiveMutex ()
	Destroys the underlying mutex object.

void	dispose ()
	Destroys the mutex object.

void	lock () const
	Locks the mutex. Creates a new recursive mutex object if it does not exist yet. More...

bool	trylock () const
	Attempts to lock the mutex. Creates a new recursive mutex object if it does not exist yet. More...

bool	try_lock () const
	Attempts to lock the mutex. Creates a new recursive mutex object if it does not exist yet. More...

void	unlock () const
	Unlocks the mutex. More...

Static Public Attributes
static const uint32_t	HASH_SEED = 0x851c2a3f
	Murmur32 hash seed value (randomly generated)

Protected Member Functions
	PersistentDataBase (const PersistentDataBase &)=delete

PersistentDataBase &	operator= (const PersistentDataBase &)=delete

virtual bool	validate (size_t dataSize)
	Used to validate the saved data structure. Used internally by load(). More...

virtual void	initialize ()
	Used to allow subclasses to initialize the saved data structure. Called internally by load(). More...

Protected Attributes
SavedDataHeader *	savedDataHeader = 0
	Pointer to the saved data header, which is followed by the data.

uint32_t	savedDataSize = 0
	Size of the saved data (header + actual data)

uint32_t	savedDataMagic
	Magic bytes for the saved data.

uint16_t	savedDataVersion
	Version number for the saved data.

uint32_t	lastUpdate = 0
	Last time the file was updated. 0 = file has not changed since writing to disk.

uint32_t	saveDelayMs = 1000
	How long to wait to save before writing file to disk. Set to 0 to write immediately.

Detailed Description

Base class for storing persistent binary data to a file or retained memory.

This class is separate from PersistentData so you can subclass it to hold your own application-specific data as well.

See PersistentDataFile for saving data to a file on the flash file system.

Constructor & Destructor Documentation

◆ PersistentDataBase() [1/2]

StorageHelperRK::PersistentDataBase::PersistentDataBase	(	SavedDataHeader *	savedDataHeader,
		size_t	savedDataSize,
		uint32_t	savedDataMagic,
		uint16_t	savedDataVersion
	)

inline

Base class for persistent data saved in file or RAM.

Parameters

savedDataHeader	Pointer to the header
savedDataSize	size of the whole structure, including the user data after it
savedDataMagic	Magic bytes to use for this data
savedDataVersion	Version to use for this data

◆ PersistentDataBase() [2/2]

StorageHelperRK::PersistentDataBase::PersistentDataBase ( const PersistentDataBase & )

protecteddelete

This class cannot be copied

Note that subclasses don't need to do include a definition like this because as long as the base class is copy-prevented subclasses by default cannot be copied.

Member Function Documentation

◆ flush()

void StorageHelperRK::PersistentDataBase::flush ( bool force )

virtual

Write the settings to disk if changed and the wait to save time has expired.

Parameters

force Pass true to ignore the wait to save time and save immediately if necessary. This is used when you're about to sleep or reset, for example.

This call is fast if a save is not required so you can call it frequently, even every loop.

◆ getValue()

template<class T >

T StorageHelperRK::PersistentDataBase::getValue ( size_t offset ) const

inline

Templated class for getting integral values (uint32_t, float, double, etc.)

Template Parameters

T

Parameters

offset

Returns: T

◆ getValueString()

bool StorageHelperRK::PersistentDataBase::getValueString	(	size_t	offset,
		size_t	size,
		String &	value
	)		const

Get the value of a string.

Parameters

offset
size
value

Returns: true; false

The templated getValue method doesn't work with String values, so this version should be used instead.

◆ initialize()

void StorageHelperRK::PersistentDataBase::initialize ( )

protectedvirtual

Used to allow subclasses to initialize the saved data structure. Called internally by load().

If you subclass this, be sure to call the superclass initialize() after you update your fields short so the hash value can be updated.

◆ load()

bool StorageHelperRK::PersistentDataBase::load ( )

virtual

Load the persistent data file. You normally do not need to call this; it will be loaded automatically.

Returns: true; false

Reimplemented in StorageHelperRK::PersistentDataEEPROM, and StorageHelperRK::PersistentDataFileSystem.

◆ operator=()

PersistentDataBase & StorageHelperRK::PersistentDataBase::operator= ( const PersistentDataBase & )

protecteddelete

This class cannot be copied

◆ save()

virtual void StorageHelperRK::PersistentDataBase::save ( )

inlinevirtual

Save the persistent data file. You normally do not need to call this; it will be saved automatically.

Save does nothing in this base class, but for PersistentDataFile it saves to a file

Reimplemented in StorageHelperRK::PersistentDataEEPROM, and StorageHelperRK::PersistentDataFileSystem.

◆ saveOrDefer()

void StorageHelperRK::PersistentDataBase::saveOrDefer ( )

virtual

Either saves data or immediately, or defers until later, based on saveDelayMs.

If saveDelayMs == 0, then always saves immediately. Otherwise, waits that amount of time before saving to allow multiple saves to be batch and to not block the updating thread.

◆ setup()

void StorageHelperRK::PersistentDataBase::setup ( )

virtual

Initialize this object for use in StorageHelperRK.

This is used from StorageHelperRK::setup(). You should not use this if you are creating your own PersistentData object; this is only used to hook this class into StorageHelperRK/

◆ setValue()

template<class T >

void StorageHelperRK::PersistentDataBase::setValue	(	size_t	offset,
		T	value
	)

inline

Templated class for setting integral values (uint32_t, float, double, etc.)

Template Parameters

T	An integral types

Parameters

offset	Offset into the structure, normally offsetof(field, T)
value	The value to set

◆ setValueString()

bool StorageHelperRK::PersistentDataBase::setValueString	(	size_t	offset,
		size_t	size,
		const char *	value
	)

Set the value of a string.

Parameters

offset
size
value

Returns: true; false

The templated setValue method doesn't work with string values, so this version should be used instead.

◆ validate()

bool StorageHelperRK::PersistentDataBase::validate ( size_t dataSize )

protectedvirtual

Used to validate the saved data structure. Used internally by load().

Returns: true; false

If you subclass this, be sure to call the superclass validate() first. If it returns false, you should just return false and skip your own validation since the outer headers were not valid and the structure cannot be used until reinitialized.

◆ withSaveDelayMs()

PersistentDataBase & StorageHelperRK::PersistentDataBase::withSaveDelayMs ( uint32_t value )

inline

Sets the wait to save delay. Default is 1000 milliseconds.

Parameters

value Value is milliseconds, or 0

Returns: PersistentData&

Normally, if the value is changed by a set call, then about one second later the change will be saved to disk from the loop thread. The storageHelperRKData is also saved before sleep or reset if changed.

You can change the save delay by using withSaveDelayMs(). If you set it to 0, then the data is saved within the setValue call immediately, which will make all set calls run more slowly.

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

src/StorageHelperRK.h
src/StorageHelperRK.cpp

Data Structures

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PersistentDataBase() [1/2]

◆ PersistentDataBase() [2/2]

Member Function Documentation

◆ flush()

◆ getValue()

◆ getValueString()

◆ initialize()

◆ load()

◆ operator=()

◆ save()

◆ saveOrDefer()

◆ setup()

◆ setValue()

◆ setValueString()

◆ validate()

◆ withSaveDelayMs()