Settings Management

Modules
	File Operations
	Variable Binding
	Settings Access

Data Structures
struct	SetsBindSpec

Typedefs
typedef struct SetsBindSpec	SetsBindSpec

Detailed Description

The Settings module extends the SSD tree system to provide persistent configuration storage with automatic background flushing and optional variable binding.

Key Features:

• JSON-backed SSD trees stored in a VFS (Virtual File System)
• Automatic background thread that periodically flushes changes to disk
• Variable binding: bind setting paths directly to static/global variables for automatic synchronization
• Two-way binding: changes to bound variables are detected and written back to settings
• Thread-safe operations inherited from SSD tree locking

Basic Usage:

// Open settings file from VFS
VFS *vfs = vfsCreate();
SSDNode *settings = setsOpen(vfs, _S"config.json", timeS(30));
 
// Read/write settings like a normal SSD tree
setsSet(settings, _S"window/width", int32, 1920);
setsSet(settings, _S"window/height", int32, 1080);
 
int32 width = setsGet(settings, _S"window/width", int32, 800);
 
// Changes are automatically flushed to disk every 30 seconds
// When done, close to ensure final flush
setsClose(&settings);
objRelease(&vfs);

Variable Binding:

The settings module can bind specific paths to program variables, allowing automatic two-way synchronization. When a setting is read, the bound variable is updated. When the bound variable changes, the setting is updated at the next flush interval.

// Define variables to bind
static struct {
    int32 width;
    int32 height;
    string theme;
} config;
 
// Define binding specifications
static SetsBindSpec bindings[] = {
    { .name = _S"window/width",  .offset = offsetof(typeof(config), width),  
      .deftyp = stvar(int32, 1024) },
    { .name = _S"window/height", .offset = offsetof(typeof(config), height), 
      .deftyp = stvar(int32, 768) },
    { .name = _S"display/theme", .offset = offsetof(typeof(config), theme),  
      .deftyp = stvar(string, _S"dark") },
    { 0 }  // NULL terminator
};
 
// Bind settings to variables
setsBind(settings, bindings, &config);
 
// Now config.width/height/theme are automatically synchronized
config.width = 1920;  // Will be written to settings at next flush

Supported Types for Binding:

• bool
• All integer types: int8, int16, int32, int64, uint8, uint16, uint32 (but not uint64)
• Floating-point: float32 (float), float64 (double)
• string (copy-on-write strings)

Integration with SSD Tree:

The settings module is built on top of the SSD tree system and uses specialized node classes:

• SettingsTree: Extends SSDTree to add file persistence, flush intervals, and background thread management
• SettingsHashNode: Extends SSDHashNode to add variable binding capabilities

All standard SSD tree operations work on settings trees, including path-based access, subtree operations, and locking. The settings module overrides node factories to ensure hashtable nodes are created as SettingsHashNode instances with binding support.

Thread Safety:

Settings trees inherit the thread-safe locking mechanisms from SSD trees. A dedicated background thread monitors all open settings trees and periodically checks for changes and flushes modified trees to disk.

Typedef Documentation

SetsBindSpec

typedef struct SetsBindSpec SetsBindSpec

Binding specification for connecting settings paths to program variables.

Used with setsBind() to establish two-way synchronization between settings and variables. The array must be terminated with a {0} entry (NULL name).