Locking

Macros
#define	ssdLockRead(root)   _ssdLockRead(SSDNode(root), _ssdCurrentLockState)
#define	ssdLockWrite(root)   _ssdLockWrite(SSDNode(root), _ssdCurrentLockState)
#define	ssdUnlock(root)   _ssdUnlock(SSDNode(root), (SSDLockState*)&_ssdCurrentLockState->_is_SSDLockState)
#define	ssdLockEnd(root)   _ssdLockEnd(SSDNode(root), (SSDLockState*)&_ssdCurrentLockState->_is_SSDLockState)
#define	ssdLockedTransaction(root)

Detailed Description

Manual locking functions for fine-grained control over thread synchronization.

NOTE: Most users should use ssdLockedTransaction() instead of manual locking. Manual locking is only needed for advanced scenarios where you need explicit control over lock acquisition and release.

Lock upgrade warning: When upgrading from read to write lock, the read lock is briefly dropped. Other threads may acquire the write lock in between, so do not assume the tree state remains unchanged during the upgrade.

Macro Definition Documentation

ssdLockedTransaction

#define ssdLockedTransaction

(

root

)

Value:

    _blkStart                                                    \
    _inhibitReturn                                                                              \
    _blkFull(SSDLockState _ssdTransientLockState = { 0 }, (root),                               \
        _ssdLockEnd(SSDNode(root), &_ssdTransientLockState))                                    \
    _blkBefore(SSDLockState *_ssdCurrentLockStateShadow = (SSDLockState*)_ssdCurrentLockState)  \
    _blkBefore(SSDLockState *_ssdCurrentLockState = _ssdCurrentLockStateShadow ?                \
        _ssdCurrentLockStateShadow : _ssdLockStateInit(&_ssdTransientLockState))                \
    _blkEnd

ssdLockedTransaction(root)

Wraps a group of SSD operations in an automatically managed lock transaction.

This is the recommended way to perform multiple SSD operations that should execute together atomically. The lock is automatically acquired at the start of the block and released at the end, even if the block exits early.

Functions that return pointers to internal storage (like ssdPtr(), ssdStrRef(), ssdObjPtr(), etc.) MUST be used within a locked transaction.

Parameters

root	The root node of the tree to lock

Example:

ssdLockedTransaction(root) {
    // Read lock acquired automatically
    strref name = ssdStrRef(root, _S"user/name");
    int32 age = ssdVal(int32, root, _S"user/age", 0);
    
    // Can upgrade to write lock if needed
    ssdSet(root, _S"user/lastAccess", true, stvar(int64, clockTimer()));
}  // Lock released automatically

Definition at line 186 of file ssdshared.h.

ssdLockEnd

#define ssdLockEnd

(

root

)

_ssdLockEnd(SSDNode(root), (SSDLockState*)&_ssdCurrentLockState->_is_SSDLockState)

bool ssdLockEnd(SSDNode *root)

Ends a locked operation and destroys the lock state.

This releases the lock and cleans up the associated lock state. Always call this when done with a manually acquired lock.

Parameters

root	The root node of the tree to unlock

Returns

true on success

Definition at line 159 of file ssdshared.h.

ssdLockRead

#define ssdLockRead

(

root

)

_ssdLockRead(SSDNode(root), _ssdCurrentLockState)

bool ssdLockRead(SSDNode *root)

Starts a locked operation in read mode.

Acquires a read lock on the tree. Multiple threads can hold read locks simultaneously, but write operations will block until all read locks are released.

Parameters

root	The root node of the tree to lock

Returns

true on success

Example:

ssdLockRead(root);
// perform read operations
ssdLockEnd(root);

Definition at line 102 of file ssdshared.h.

ssdLockWrite

#define ssdLockWrite

(

root

)

_ssdLockWrite(SSDNode(root), _ssdCurrentLockState)

bool ssdLockWrite(SSDNode *root)

Starts an operation in write mode or upgrades a read lock to write.

Acquires a write lock on the tree. Only one thread can hold a write lock at a time, and no read locks can be held while a write lock is active.

CRITICAL: If upgrading from a read lock, the lock is briefly dropped during the upgrade. Do not assume that no other thread obtained the write lock in between! The tree state may have changed between dropping the read lock and acquiring the write lock.

Parameters

root	The root node of the tree to lock

Returns

true on success

Example:

ssdLockWrite(root);
// perform write operations
ssdLockEnd(root);

Definition at line 132 of file ssdshared.h.

ssdUnlock

#define ssdUnlock

(

root

)

_ssdUnlock(SSDNode(root), (SSDLockState*)&_ssdCurrentLockState->_is_SSDLockState)

bool ssdUnlock(SSDNode *root)

Temporarily unlocks the lock while preserving lock state for later reuse.

This allows other threads to access the tree while maintaining the lock state structure for potential reacquisition. Use this when you need to temporarily release the lock within a longer operation.

Parameters

root	The root node of the tree to unlock

Returns

true on success

Definition at line 147 of file ssdshared.h.