PhosphorConfig::IBackend Class Reference

Pluggable configuration backend. More...

#include <phosphor-config/include/PhosphorConfig/IBackend.h>

Inheritance diagram for PhosphorConfig::IBackend:

Public Member Functions
virtual	~IBackend ()=default
virtual std::unique_ptr< IGroup >	group (const QString &name)=0
	Return a scoped view into the named group.
virtual bool	isDirty () const
	Whether the in-memory document carries changes not yet committed to disk.
virtual void	reparseConfiguration ()=0
	Re-read configuration from disk, discarding any pending in-memory changes.
virtual bool	sync ()=0
	Request that pending writes reach disk.
virtual bool	commit ()
	Flush pending writes to disk NOW and report whether they landed.
virtual void	deleteGroup (const QString &name)=0
	Delete an entire group and everything inside it.
virtual QString	readRootString (const QString &key, const QString &defaultValue={}) const =0
	Read/write ungrouped (root-level) keys.
virtual void	writeRootString (const QString &key, const QString &value)=0
virtual void	removeRootKey (const QString &key)=0
virtual QStringList	groupList () const =0
	Enumerate every top-level group name.
virtual void	setPathResolver (std::shared_ptr< IGroupPathResolver >)
	Install a group-path resolver.
virtual std::shared_ptr< IGroupPathResolver >	pathResolver () const
	Currently-installed resolver, or nullptr when none is set (also the default for backends that ignore setPathResolver).
virtual void	setVersionStamp (const QString &, int)
	Install a "stamp on first sync" version annotation: if key is absent from the backend's root on the next flush, write key = version.
virtual std::pair< QString, int >	versionStamp () const
	Currently-installed version stamp as {key, version}.
virtual bool	applyMigration (const Schema &)
	Apply schema's migration chain against the backend's in-memory state and commit any resulting version bump.
	IBackend (const IBackend &)=delete
IBackend &	operator= (const IBackend &)=delete

Protected Member Functions
	IBackend ()=default

Detailed Description

Pluggable configuration backend.

Provides group-based access, persistence, and group enumeration. Concrete implementation: JsonBackend (atomic-write JSON file). Legacy INI files are not a backend — they are read once, through QSettingsBackend::readConfigFromDisk, by a migration chain.

Root-level ("ungrouped") access is provided via readRootString / writeRootString. How a backend stores root keys is implementation-defined: JsonBackend keeps them under a configurable root-group name (defaults to "General"), mirroring the [General] section an INI file would use.

Constructor & Destructor Documentation

~IBackend()

virtual PhosphorConfig::IBackend::~IBackend ( )

virtualdefault

IBackend() [1/2]

PhosphorConfig::IBackend::IBackend ( const IBackend &  )

delete

IBackend() [2/2]

PhosphorConfig::IBackend::IBackend ( )

protecteddefault

Member Function Documentation

applyMigration()

virtual bool PhosphorConfig::IBackend::applyMigration ( const Schema &  )

inlinevirtual

Apply schema's migration chain against the backend's in-memory state and commit any resulting version bump.

Returns true when the backend supports schema migrations (even if no step applied — e.g. the on-disk version already matches). Returns false when the backend has no concept of a JSON-root snapshot; callers should log that declared migrations will not run. Default: no-op returning false.

Reimplemented in PhosphorConfig::JsonBackend.

commit()

virtual bool PhosphorConfig::IBackend::commit ( )

inlinevirtual

Flush pending writes to disk NOW and report whether they landed.

Returns true when disk holds the current in-memory state on return (including when there was nothing to flush), false on an I/O error. Unlike sync() this never defers, so a true result is a commitment the caller can key state off.

The default forwards to sync(), which is correct for any backend whose sync() already writes inline. Backends that can defer must override it to bypass their deferral.

Reimplemented in PhosphorConfig::JsonBackend.

deleteGroup()

virtual void PhosphorConfig::IBackend::deleteGroup ( const QString &  name )

pure virtual

Delete an entire group and everything inside it.

Intermediate parents are pruned if they become empty (dot-path groups only).

Implemented in PhosphorConfig::JsonBackend.

group()

virtual std::unique_ptr< IGroup > PhosphorConfig::IBackend::group ( const QString &  name )

pure virtual

Return a scoped view into the named group.

Caller owns the pointer; destroy it before asking for another group on this backend.

Implemented in PhosphorConfig::JsonBackend.

groupList()

virtual QStringList PhosphorConfig::IBackend::groupList ( ) const

pure virtual

Enumerate every top-level group name.

Dot-path groups are returned with their full path ("Snapping", "Snapping.Behavior", ...). Groups produced by a plugged-in IGroupPathResolver appear in the resolver's preferred external form.

CONTRACT — reserved names. Whatever container an implementation uses to hold the ungrouped keys that readRootString / writeRootString / removeRootKey address must NOT appear in this list, nor may any of its descendants. Ungrouped keys are not addressable through group() and no caller can tell them apart from a real group by name, so a consumer that sweeps groupList() and calls deleteGroup on every name it does not recognise would wipe them. Enforcing it here rather than asking every consumer to know each backend's container name is what makes such a sweep safe.

The same applies to any root key an IGroupPathResolver reserves: the resolver owns that subtree exclusively and enumerates it itself.

Implementations: JsonBackend filters its rootGroupName (and the version stamp, and the resolver's reserved roots) out of the enumeration.

Implemented in PhosphorConfig::JsonBackend.

isDirty()

virtual bool PhosphorConfig::IBackend::isDirty ( ) const

inlinevirtual

Whether the in-memory document carries changes not yet committed to disk.

A clean backend may be re-read from disk without losing state; a dirty one may not. The default true is deliberate: a backend that cannot answer must report dirty, so callers treating "clean" as the licence to reload never discard state they cannot see.

Reimplemented in PhosphorConfig::JsonBackend.

operator=()

IBackend & PhosphorConfig::IBackend::operator= ( const IBackend &  )

delete

pathResolver()

virtual std::shared_ptr< IGroupPathResolver > PhosphorConfig::IBackend::pathResolver ( ) const

inlinevirtual

Currently-installed resolver, or nullptr when none is set (also the default for backends that ignore setPathResolver).

Reimplemented in PhosphorConfig::JsonBackend.

readRootString()

virtual QString PhosphorConfig::IBackend::readRootString ( const QString &  key, const QString &  defaultValue = {}  ) const

pure virtual

Read/write ungrouped (root-level) keys.

Implemented in PhosphorConfig::JsonBackend.

removeRootKey()

virtual void PhosphorConfig::IBackend::removeRootKey ( const QString &  key )

pure virtual

Implemented in PhosphorConfig::JsonBackend.

reparseConfiguration()

virtual void PhosphorConfig::IBackend::reparseConfiguration ( )

pure virtual

Re-read configuration from disk, discarding any pending in-memory changes.

Must not be called while a group view is live.

Discarding is load-bearing, not incidental: callers use this to roll back after a failed write, so an implementation that instead FLUSHED the pending changes would persist the very mutations the caller is asking it to drop. A store that cannot drop unsaved writes therefore cannot implement IBackend — which is why QSettings, whose destructor flushes and which offers no discard API, is confined to the read-only QSettingsBackend::readConfigFromDisk helper.

Implemented in PhosphorConfig::JsonBackend.

setPathResolver()

virtual void PhosphorConfig::IBackend::setPathResolver ( std::shared_ptr< IGroupPathResolver >  )

inlinevirtual

Install a group-path resolver.

The caller shares ownership via shared_ptr so multiple Stores/backends can reference the same instance. Backends that have no resolver concept return without storing the pointer.

Reimplemented in PhosphorConfig::JsonBackend.

setVersionStamp()

virtual void PhosphorConfig::IBackend::setVersionStamp ( const QString &  , int    )

inlinevirtual

Install a "stamp on first sync" version annotation: if key is absent from the backend's root on the next flush, write key = version.

Backends without a stamp concept ignore the call. Passing an empty key disables the stamp.

Reimplemented in PhosphorConfig::JsonBackend.

sync()

virtual bool PhosphorConfig::IBackend::sync ( )

pure virtual

Request that pending writes reach disk.

No-op when nothing is dirty. Returns true on success (or when there was nothing to flush), false on an I/O error — backends log the reason before returning.

true means "accepted", NOT "committed": a backend is free to satisfy this by scheduling the write (JsonBackend's Deferred sync policy debounces it), in which case the write has not happened yet and may still fail. Callers that must know the bytes landed — anything moving a baseline or reporting success to a user — call commit() instead.

Implemented in PhosphorConfig::JsonBackend.

versionStamp()

virtual std::pair< QString, int > PhosphorConfig::IBackend::versionStamp ( ) const

inlinevirtual

Currently-installed version stamp as {key, version}.

Empty key means "no stamp installed" (also the default for backends that ignore setVersionStamp).

Reimplemented in PhosphorConfig::JsonBackend.

writeRootString()

virtual void PhosphorConfig::IBackend::writeRootString ( const QString &  key, const QString &  value  )

pure virtual

Implemented in PhosphorConfig::JsonBackend.

---

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

• phosphor-config/include/PhosphorConfig/IBackend.h