Elektra  0.9.7
Macros | Enumerations | Functions
kdbprivate.h File Reference

Private declarations. More...

#include <elektra.h>
#include <elektra/error.h>
#include <kdb.h>
#include <kdbextension.h>
#include <kdbhelper.h>
#include <kdbio.h>
#include <kdbmacros.h>
#include <kdbnotificationinternal.h>
#include <kdbplugin.h>
#include <kdbtypes.h>
#include <kdbglobal.h>
#include <limits.h>
Include dependency graph for kdbprivate.h:
This graph shows which files directly or indirectly include this file:

Macros

#define KEYSET_SIZE   16
 The minimal allocation size of a keyset inclusive NULL byte. More...
 
#define NR_OF_PLUGINS   10
 How many plugins can exist in an backend.
 
#define COMMIT_PLUGIN   7
 The index of the commit plugin.
 
#define STORAGE_PLUGIN   5
 The index of the storage plugin.
 
#define RESOLVER_PLUGIN   0
 The index of the resolver plugin.
 
#define APPROXIMATE_NR_OF_BACKENDS   16
 Trie optimization.
 
#define KDB_MAX_UCHAR   (UCHAR_MAX + 1)
 The maximum value of unsigned char+1, needed for iteration over trie children/values: More...
 
#define MAX_LEN_INT   31
 The maximum of how many characters an integer needs as decimal number.
 
#define KDB_SYSTEM_ELEKTRA   "system:/elektra"
 Backend mounting information. More...
 
#define KDB_CACHE_PREFIX   "system:/elektra/cache"
 All keys below this are used for cache metadata in the global keyset.
 
#define test_bit(var, bit)   (((unsigned long long) (var)) & ((unsigned long long) (bit)))
 Test a bit. More...
 
#define set_bit(var, bit)   ((var) |= ((unsigned long long) (bit)))
 Set a bit. More...
 
#define clear_bit(var, bit)   ((var) &= ~((unsigned long long) (bit)))
 Clear a bit. More...
 

Enumerations

enum  keyflag_t {
  KEY_FLAG_SYNC = 1 , KEY_FLAG_RO_NAME = 1 << 1 , KEY_FLAG_RO_VALUE = 1 << 2 , KEY_FLAG_RO_META = 1 << 3 ,
  KEY_FLAG_MMAP_STRUCT = 1 << 4 , KEY_FLAG_MMAP_KEY = 1 << 5 , KEY_FLAG_MMAP_DATA = 1 << 6
}
 Key Flags. More...
 
enum  ksflag_t { KS_FLAG_SYNC = 1 , KS_FLAG_MMAP_STRUCT = 1 << 2 , KS_FLAG_MMAP_ARRAY = 1 << 3 }
 Advanced KS Flags. More...
 
enum  splitflag_t { SPLIT_FLAG_SYNC = 1 , SPLIT_FLAG_CASCADING = 1 << 1 }
 

Functions

Split * splitNew (void)
 Allocates a new split object. More...
 
void splitDel (Split *keysets)
 Delete a split object. More...
 
void splitRemove (Split *split, size_t where)
 Remove one part of split. More...
 
ssize_t splitAppend (Split *split, Backend *backend, Key *parentKey, int syncbits)
 Increases the size of split and appends a new empty keyset. More...
 
int splitBuildup (Split *split, KDB *handle, Key *parentKey)
 Walks through kdb->split and adds all backends below parentKey to split. More...
 
void splitUpdateFileName (Split *split, KDB *handle, Key *key)
 Update the (configuration) file name for the parent key. More...
 
int splitAppoint (Split *split, KDB *handle, KeySet *ks)
 Appoints all keys from ks to yet unsynced splits. More...
 
int splitGet (Split *split, Key *warningKey, KDB *handle)
 Does some work after getting of backends is finished. More...
 
int splitMergeBackends (Split *split, KeySet *dest)
 Merges together the backend based parts of split into dest, but bypasses the default split. More...
 
int splitMergeDefault (Split *split, KeySet *dest)
 Merges the default split into dest. More...
 
int splitDivide (Split *split, KDB *handle, KeySet *ks)
 Splits up the keysets and search for a sync bit in every key. More...
 
int splitSync (Split *split)
 Add sync bits everywhere keys were removed/added. More...
 
void splitPrepare (Split *split)
 Prepares for kdbSet() mainloop afterwards. More...
 
int splitUpdateSize (Split *split)
 Also update sizes after kdbSet() to recognize multiple kdbSet() attempts. More...
 
Backend * backendOpen (KeySet *elektra_config, KeySet *modules, KeySet *global, Key *errorKey)
 Builds a backend out of the configuration supplied from: More...
 
Backend * backendOpenDefault (KeySet *modules, KeySet *global, const char *file, Key *errorKey)
 Opens a default backend using the plugin named KDB_RESOLVER and KDB_STORAGE. More...
 
Backend * backendOpenModules (KeySet *modules, KeySet *global, Key *errorKey)
 
Backend * backendOpenVersion (KeySet *global, Key *errorKey)
 Opens the internal version backend. More...
 
int backendUpdateSize (Backend *backend, Key *parent, int size)
 Update internal size in backend. More...
 
Plugin * elektraPluginOpen (const char *backendname, KeySet *modules, KeySet *config, Key *errorKey)
 Opens a plugin. More...
 
int elektraProcessPlugin (Key *cur, int *pluginNumber, char **pluginName, char **referenceName, Key *errorKey)
 
int elektraProcessPlugins (Plugin **plugins, KeySet *modules, KeySet *referencePlugins, KeySet *config, KeySet *systemConfig, KeySet *global, Key *errorKey)
 Load a plugin. More...
 
size_t elektraPluginGetFunction (Plugin *plugin, const char *name)
 Retrieves a function exported by a plugin. More...
 
Plugin * elektraPluginFindGlobal (KDB *handle, const char *pluginName)
 Searches the global plugins for a given plugin name. More...
 
int trieClose (Trie *trie, Key *errorKey)
 Closes the trie and all opened backends within. More...
 
Backend * trieLookup (Trie *trie, const char *name)
 The Trie structure. More...
 
Trie * trieInsert (Trie *trie, const char *name, Backend *value)
 Insert into trie. More...
 
int mountOpen (KDB *kdb, KeySet *config, KeySet *modules, Key *errorKey)
 Creates a trie from a given configuration. More...
 
int mountDefault (KDB *kdb, KeySet *modules, int inFallback, Key *errorKey)
 Reopens the default backend and mounts the default backend if needed. More...
 
int mountModules (KDB *kdb, KeySet *modules, Key *errorKey)
 Mount all module configurations. More...
 
int mountVersion (KDB *kdb, Key *errorKey)
 Mount the version backend. More...
 
int mountBackend (KDB *kdb, Backend *backend, Key *errorKey)
 Mounts a backend into the trie. More...
 
Key * mountGetMountpoint (KDB *handle, const char *where)
 Lookup a mountpoint in a handle for a specific key. More...
 
Backend * mountGetBackend (KDB *handle, const char *where)
 Lookup a backend handle for a specific key. More...
 
int keyReplacePrefix (Key *key, const Key *oldPrefix, const Key *newPrefix)
 Replaces a prefix of the key name of key. More...
 
Key * elektraKsPopAtCursor (KeySet *ks, elektraCursor pos)
 Pop key at given cursor position. More...
 
ssize_t elektraMemcpy (Key **array1, Key **array2, size_t size)
 Internal Methods for Elektra. More...
 
ssize_t elektraMemmove (Key **array1, Key **array2, size_t size)
 Copies the key array2 into where array1 points. More...
 
KeySet * ksRenameKeys (KeySet *config, const char *name)
 Takes the first key and cuts off this common part for all other keys, instead name will be prepended. More...
 
ssize_t ksRename (KeySet *ks, const Key *root, const Key *newRoot)
 Moves all keys below root to below newRoot. More...
 
elektraCursor ksFindHierarchy (const KeySet *ks, const Key *root, elektraCursor *end)
 Searches for the start and optionally end of the key hierachy rooted at root in ks. More...
 
bool elektraKeyNameValidate (const char *name, bool isComplete)
 Takes an escaped key name and validates it. More...
 
void elektraKeyNameCanonicalize (const char *name, char **canonicalName, size_t *canonicalSizePtr, size_t offset, size_t *usizePtr)
 Takes a valid (non-)canonical key name and produces its canonical form. More...
 
void elektraKeyNameUnescape (const char *name, char *unescapedName)
 Takes a canonical key name and unescapes it. More...
 
size_t elektraKeyNameEscapePart (const char *part, char **escapedPart)
 Takes a single key name part and produces its escaped form. More...
 
ElektraError * elektraErrorCreate (const char *code, const char *description, const char *module, const char *file, kdb_long_t line)
 Creates a new ElektraError using the provided values. More...
 
void elektraErrorAddWarning (ElektraError *error, ElektraError *warning)
 Adds a warning to an existing ElektraError struct. More...
 
ElektraError * elektraErrorFromKey (Key *key)
 Extracts the error and all warnings from the given key. More...
 
ElektraError * elektraErrorKeyNotFound (const char *keyname)
 Creates a "Key not found" error. More...
 
ElektraError * elektraErrorWrongType (const char *keyname, KDBType expectedType, KDBType actualType)
 Creates a "Wrong type" error. More...
 
ElektraError * elektraErrorNullError (const char *function)
 Creates a "Null error argument" error. More...
 
ElektraError * elektraErrorMinimalValidationFailed (const char *function)
 Creates a "minimal validation failed" error. More...
 

Detailed Description

Private declarations.

Macro Definition Documentation

◆ clear_bit

#define clear_bit (   var,
  bit 
)    ((var) &= ~((unsigned long long) (bit)))

Clear a bit.

See also
set_bit()

◆ KDB_MAX_UCHAR

#define KDB_MAX_UCHAR   (UCHAR_MAX + 1)

The maximum value of unsigned char+1, needed for iteration over trie children/values:

for (i=0; i<KDB_MAX_UCHAR; ++i)

◆ KDB_SYSTEM_ELEKTRA

#define KDB_SYSTEM_ELEKTRA   "system:/elektra"

Backend mounting information.

This key directory tells you where each backend is mounted to which mountpoint.

◆ KEYSET_SIZE

#define KEYSET_SIZE   16

The minimal allocation size of a keyset inclusive NULL byte.

ksGetAlloc() will return one less because it says how much can actually be stored.

◆ set_bit

#define set_bit (   var,
  bit 
)    ((var) |= ((unsigned long long) (bit)))

Set a bit.

See also
clear_bit()

◆ test_bit

#define test_bit (   var,
  bit 
)    (((unsigned long long) (var)) & ((unsigned long long) (bit)))

Test a bit.

See also
set_bit(), clear_bit()

Enumeration Type Documentation

◆ keyflag_t

enum keyflag_t

Key Flags.

Store a synchronizer state so that the Elektra knows if something has changed or not.

Enumerator
KEY_FLAG_SYNC 

Key need sync. If name, value or metadata are changed this flag will be set, so that the backend will sync the key to database.

KEY_FLAG_RO_NAME 

Read only flag for name. Key name is read only and not allowed to be changed. All attempts to change the name will lead to an error. Needed for metakeys and keys that are in a data structure that depends on name ordering.

KEY_FLAG_RO_VALUE 

Read only flag for value. Key value is read only and not allowed to be changed. All attempts to change the value will lead to an error. Needed for metakeys

KEY_FLAG_RO_META 

Read only flag for meta. Key meta is read only and not allowed to be changed. All attempts to change the value will lead to an error. Needed for metakeys.

KEY_FLAG_MMAP_STRUCT 

Key struct lies inside a mmap region. This flag is set for Keys inside a mapped region. It prevents erroneous free() calls on these keys.

KEY_FLAG_MMAP_KEY 

Key name lies inside a mmap region. This flag is set once a Key name has been moved to a mapped region, and is removed if the name moves out of the mapped region. It prevents erroneous free() calls on these keys.

KEY_FLAG_MMAP_DATA 

Key value lies inside a mmap region. This flag is set once a Key value has been moved to a mapped region, and is removed if the value moves out of the mapped region. It prevents erroneous free() calls on these keys.

◆ ksflag_t

enum ksflag_t

Advanced KS Flags.

Store a synchronizer state so that the Elektra knows if something has changed or not.

Enumerator
KS_FLAG_SYNC 

KeySet need sync. If keys were popped from the Keyset this flag will be set, so that the backend will sync the keys to database.

KS_FLAG_MMAP_STRUCT 

KeySet struct lies inside a mmap region. This flag is set for KeySets inside a mapped region. It prevents erroneous free() calls on these KeySets.

KS_FLAG_MMAP_ARRAY 

Array of the KeySet lies inside a mmap region. This flag is set for KeySets where the array is in a mapped region, and is removed if the array is moved out from the mapped region. It prevents erroneous free() calls on these arrays.

◆ splitflag_t

Enumerator
SPLIT_FLAG_SYNC 

KeySet in Split need sync. Is there any key in there which need to be synced? If keys were popped from the Keyset this flag will be set, so that the backend will sync the keys to database.

SPLIT_FLAG_CASCADING 

Do we need relative checks? Is this a cascading backend?

Function Documentation

◆ backendOpen()

Backend* backendOpen ( KeySet *  elektraConfig,
KeySet *  modules,
KeySet *  global,
Key *  errorKey 
)

Builds a backend out of the configuration supplied from:

system:/elektra/mountpoints/<name>

The root key must be like the above example. You do not need to rewind the keyset. But every key must be below the root key.

The internal consistency will be checked in this function. If necessary parts are missing, like no plugins, they cant be loaded or similar 0 will be returned.

ksCut() is perfectly suitable for cutting out the configuration like needed.

Note
The given KeySet will be deleted within the function, don't use it afterwards.
Parameters
elektraConfigthe configuration to work with. It is used to build up this backend.
modulesused to load new modules or get references to existing one
globalthe global keyset of the KDB instance
errorKeythe key where an error and warnings are added
Returns
a pointer to a freshly allocated backend this could be the requested backend or a so called "missing backend".
Return values
0if out of memory

◆ backendOpenDefault()

Backend* backendOpenDefault ( KeySet *  modules,
KeySet *  global,
const char *  file,
Key *  errorKey 
)

Opens a default backend using the plugin named KDB_RESOLVER and KDB_STORAGE.

Parameters
modulesthe modules to work with
globalthe global keyset of the KDB instance
errorKeythe key to issue warnings and errors to
Returns
the fresh allocated default backend or 0 if it failed

◆ backendOpenModules()

Backend* backendOpenModules ( KeySet *  modules,
KeySet *  global,
Key *  errorKey 
)
Returns
a backend which gives plugin configuration of the module which is currently point to.
Parameters
modulesthe modules to work with
globalthe global keyset of the KDB instance
errorKeythe key to issue warnings and errors to

◆ backendOpenVersion()

Backend* backendOpenVersion ( KeySet *  global,
Key *  errorKey 
)

Opens the internal version backend.

Parameters
globalthe global keyset of the KDB instance
errorKeythe key to issue warnings and errors to
Returns
the fresh allocated default backend or 0 if it failed

◆ backendUpdateSize()

int backendUpdateSize ( Backend *  backend,
Key *  parent,
int  size 
)

Update internal size in backend.

Parameters
backendthe backend to update
parentfor parent
sizeto update (-1 default, 0 empty, >0 otherwise)
Precondition
parent must be serializable namespace
Return values
-1if invalid parent (assert)
0on success

◆ elektraErrorAddWarning()

void elektraErrorAddWarning ( ElektraError *  error,
ElektraError *  warning 
)

Adds a warning to an existing ElektraError struct.

If you want to report a warning without an error, create a dummy error with elektraErrorPureWarning() and then add a warning to it.

Parameters
errorThe error to which warning shall be added.
warningThe warning to add. Once added it is owned by error. DO NOT call elektraErrorReset() on it afterwards.

◆ elektraErrorCreate()

ElektraError* elektraErrorCreate ( const char *  code,
const char *  description,
const char *  module,
const char *  file,
kdb_long_t  line 
)

Creates a new ElektraError using the provided values.

The returned value will be allocated with elektraCalloc().

Parameters
codeThe error code of the error. Must be compile-time constant.
descriptionThe description of the error. Will be copied and stored in the struct.
moduleThe module that raised the error. Must be compile-time constant.
fileThe file that raised the error. Must be compile-time constant.
lineThe line in which the error was raised.
Returns
A newly allocated ElektraError (free with elektraErrorReset()).

◆ elektraErrorFromKey()

ElektraError* elektraErrorFromKey ( Key *  key)

Extracts the error and all warnings from the given key.

If no error exists, a pure warning error will be used.

See also
elektraErrorPureWarning
Parameters
keyThe to extract error and warnings from.
Returns
A newly allocated ElektraError (free with elektraErrorReset()).

◆ elektraErrorKeyNotFound()

ElektraError* elektraErrorKeyNotFound ( const char *  keyname)

Creates a "Key not found" error.

Parameters
keynameThe name of the key that wasn't found.
Returns
A newly allocated ElektraError (free with elektraErrorReset()).

◆ elektraErrorMinimalValidationFailed()

ElektraError* elektraErrorMinimalValidationFailed ( const char *  application)

Creates a "minimal validation failed" error.

Parameters
applicationparent key as passed to elektraOpen()
Returns
A newly allocated ElektraError (free with elektraErrorReset()).

◆ elektraErrorNullError()

ElektraError* elektraErrorNullError ( const char *  function)

Creates a "Null error argument" error.

Parameters
functionThe name of the function that was called with a null pointer error argument.
Returns
A newly allocated ElektraError (free with elektraErrorReset()).

◆ elektraErrorWrongType()

ElektraError* elektraErrorWrongType ( const char *  keyname,
KDBType  expectedType,
KDBType  actualType 
)

Creates a "Wrong type" error.

Parameters
keynameThe name of the key that had the wrong type.
expectedTypeThe type that was expected.
actualTypeThe type that was actually found.
Returns
A newly allocated ElektraError (free with elektraErrorReset()).

◆ elektraKsPopAtCursor()

Key* elektraKsPopAtCursor ( KeySet *  ks,
elektraCursor  pos 
)

Pop key at given cursor position.

Parameters
ksthe keyset to pop key from
cwhere to pop

The internal cursor will be rewinded using ksRewind(). You can use ksGetCursor() and ksSetCursor() jump back to the previous position. e.g. to pop at current position within ksNext() loop:

cursor_t c = ksGetCursor(ks);
ksSetCursor(ks, c);
ksPrev(ks); // to have correct key after next ksNext()
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:500
int ksSetCursor(KeySet *ks, elektraCursor cursor)
Set the KeySet internal cursor to cursor.
Definition: keyset.c:1742
elektraCursor ksGetCursor(const KeySet *ks)
Get the internal cursor of the KeySet.
Definition: keyset.c:1671
Key * elektraKsPopAtCursor(KeySet *ks, elektraCursor pos)
Pop key at given cursor position.
Definition: proposal.c:35
Warning
do not use, will be superseded by external iterator API
Returns
the popped key
Return values
0if ks is 0

◆ elektraMemcpy()

ssize_t elektraMemcpy ( Key **  array1,
Key **  array2,
size_t  size 
)

Internal Methods for Elektra.

To use them:

#include <kdbinternal.h>
Includes most internal header files.

There are some areas where libraries have to reimplement some basic functions to archive support for non-standard systems, for testing purposes or to provide a little more convenience. Copies the key array2 into where array1 points. It copies size elements.

Overlapping is prohibited, use elektraMemmove() instead.

Parameters
array1the destination
array2the source
sizehow many pointer to Keys to copy
Return values
-1on null pointers
0if nothing was done
Returns
size how many keys were copied

◆ elektraMemmove()

ssize_t elektraMemmove ( Key **  array1,
Key **  array2,
size_t  size 
)

Copies the key array2 into where array1 points.

It copies size elements.

Overlapping is ok. If they do not overlap consider elektraMemcpy() instead.

Parameters
array1the destination
array2the source
sizehow many pointer to Keys to copy
Return values
-1on null pointers
0if nothing was done
Returns
size how many keys were copied

◆ elektraPluginFindGlobal()

Plugin* elektraPluginFindGlobal ( KDB *  handle,
const char *  pluginName 
)

Searches the global plugins for a given plugin name.

NOTE: if the list plugin occupies the prerollback position, this queries the list plugin first, and only if we don't find anything there, we look directly in the global plugins array

Parameters
handleThe KDB handle to search
pluginNameThe plugin name to look for
Returns
the plugin handle, if found or NULL otherwise

◆ elektraPluginGetFunction()

size_t elektraPluginGetFunction ( Plugin *  plugin,
const char *  name 
)

Retrieves a function exported by a plugin.

Parameters
pluginPlugin handle
nameFunction name
Returns
Pointer to function. NULL if function not found or not enough memory available

◆ elektraPluginOpen()

Plugin* elektraPluginOpen ( const char *  name,
KeySet *  modules,
KeySet *  config,
Key *  errorKey 
)

Opens a plugin.

The config will be used as is. So be sure to transfer ownership of the config to it, with e.g. ksDup(). elektraPluginClose() will delete the config.

Returns
a pointer to a new created plugin or 0 on error

◆ elektraProcessPlugin()

int elektraProcessPlugin ( Key *  cur,
int *  pluginNumber,
char **  pluginName,
char **  referenceName,
Key *  errorKey 
)
Return values
1and an allocated string of the pluginName if a new plugins should be created.
2and an allocated string of the referenceName if an old plugin should be used
3and both if a new plugin should be created and made available for later back referencing.
-1on error

◆ elektraProcessPlugins()

int elektraProcessPlugins ( Plugin **  plugins,
KeySet *  modules,
KeySet *  referencePlugins,
KeySet *  config,
KeySet *  systemConfig,
KeySet *  global,
Key *  errorKey 
)

Load a plugin.

The array of plugins must be set to 0. Its length is NR_OF_PLUGINS.

systemConfig will only be used, not deleted.

Parameters
configthe config with the information how the plugins should be put together
systemConfigthe shared (system) config for the plugins. Every plugin additional get this config.
globalthe global keyset of the KDB instance
Return values
-1on failure

◆ mountBackend()

int mountBackend ( KDB *  kdb,
Backend *  backend,
Key *  errorKey 
)

Mounts a backend into the trie.

Precondition
user must pass correctly allocated backend
Postcondition
sets reference counter of backend
Warning
in case of init and default backends, the reference counter needs to be modified after calling mountBackend.
Parameters
kdbthe handle to work with
backendthe backend to mount
errorKeythe key used to report warnings
Return values
-1on failure
1on success

◆ mountDefault()

int mountDefault ( KDB *  kdb,
KeySet *  modules,
int  inFallback,
Key *  errorKey 
)

Reopens the default backend and mounts the default backend if needed.

Precondition
Default Backend is closed. mountOpen was executed before.
Parameters
kdbthe handle to work with
modulesthe current list of loaded modules
errorKeythe key used to report warnings
Return values
-1on error
0on success

◆ mountGetBackend()

Backend* mountGetBackend ( KDB *  handle,
const char *  where 
)

Lookup a backend handle for a specific key.

The required canonical name is ensured by using a key as parameter, which will transform the key to canonical representation.

Will return handle when no more specific KDB could be found.

If key is 0 or invalid the default backend will be returned.

Parameters
handleis the data structure, where the mounted directories are saved.
wherethe key name, that should be looked up.
Returns
the backend handle associated with the key

◆ mountGetMountpoint()

Key* mountGetMountpoint ( KDB *  handle,
const char *  where 
)

Lookup a mountpoint in a handle for a specific key.

Will return a key representing the mountpoint or null if there is no appropriate mountpoint e.g. its the root mountpoint.

Example:
KDB * handle = kdbOpen();
Key *mountpoint=0;
mountpoint=kdbGetMountpoint(handle, "system:/template");
printf("The backend I am using is %s mounted in %s\n",
keyValue(mountpoint),
keyName(mountpoint));
kdbClose (handle);
KDB * kdbOpen(const KeySet *contract, Key *errorKey)
Opens the session with the Key database.
Definition: kdb.c:417
int kdbClose(KDB *handle, Key *errorKey)
Closes the session with the Key database.
Definition: kdb.c:590
const char * keyName(const Key *key)
Returns a pointer to the abbreviated real internal key name.
Definition: elektra/keyname.c:254
const void * keyValue(const Key *key)
Return a pointer to the real internal key value.
Definition: keyvalue.c:164
Parameters
handleis the data structure, where the mounted directories are saved.
wherethe key name, that should be looked up.
Returns
the mountpoint associated with the key

◆ mountModules()

int mountModules ( KDB *  kdb,
KeySet *  modules,
Key *  errorKey 
)

Mount all module configurations.

Parameters
kdbthe handle to work with
modulesthe current list of loaded modules
errorKeythe key used to report warnings
Return values
-1if not rootkey was found
0otherwise

◆ mountOpen()

int mountOpen ( KDB *  kdb,
KeySet *  config,
KeySet *  modules,
Key *  errorKey 
)

Creates a trie from a given configuration.

The config will be deleted within this function.

Note
mountDefault is not allowed to be executed before
Parameters
kdbthe handle to work with
modulesthe current list of loaded modules
configthe configuration which should be used to build up the trie.
errorKeythe key used to report warnings
Return values
-1on failure
0on success

◆ mountVersion()

int mountVersion ( KDB *  kdb,
Key *  errorKey 
)

Mount the version backend.

Parameters
kdbthe handle to work with
errorKeythe key used to report warnings
Return values
0on success

◆ splitAppend()

ssize_t splitAppend ( Split *  split,
Backend *  backend,
Key *  parentKey,
int  syncbits 
)

Increases the size of split and appends a new empty keyset.

Initializes the element with the given parameters at size-1 to be used.

Will automatically resize split if needed.

Parameters
splitthe split object to work with
backendthe backend which should be appended
parentKeythe parentKey which should be appended
syncbitsthe initial syncstate which should be appended
Return values
-1if no split is found
Returns
the position of the new element: size-1

◆ splitAppoint()

int splitAppoint ( Split *  split,
KDB *  handle,
KeySet *  ks 
)

Appoints all keys from ks to yet unsynced splits.

Precondition
splitBuildup() need to be executed before.
Parameters
splitthe split object to work with
handleto determine to which backend a key belongs
ksthe keyset to appoint to split
Return values
1on success
-1if no backend was found for a key

◆ splitBuildup()

int splitBuildup ( Split *  split,
KDB *  kdb,
Key *  parentKey 
)

Walks through kdb->split and adds all backends below parentKey to split.

Sets syncbits to 2 if it is a default or root backend (which needs splitting). The information is copied from kdb->split.

Precondition
split needs to be empty, directly after creation with splitNew().
there needs to be a valid defaultBackend but its ok not to have a trie inside KDB.
parentKey must be a valid key! (could be implemented more generally, but that would require splitting up of keysets of the same backend)
Parameters
splitwill get all backends appended
kdbthe handle to get information about backends
parentKeythe information below which key the backends are from interest
Return values
1always

◆ splitDel()

void splitDel ( Split *  keysets)

Delete a split object.

Will free all allocated resources of a split keyset.

Parameters
keysetsthe split object to work with

◆ splitDivide()

int splitDivide ( Split *  split,
KDB *  handle,
KeySet *  ks 
)

Splits up the keysets and search for a sync bit in every key.

It does not check if there were removed keys, see splitSync() for the next step.

It does not create new backends, this has to be done by buildup before.

Precondition
splitBuildup() need to be executed before.
Parameters
splitthe split object to work with
handleto get information where the individual keys belong
ksthe keyset to divide
Return values
0if there were no sync bits
1if there were sync bits
-1if no backend was found for any key

◆ splitGet()

int splitGet ( Split *  split,
Key *  warningKey,
KDB *  handle 
)

Does some work after getting of backends is finished.

  • Update sizes
  • Removal of wrong keys
Precondition
splitAppoint() needs to be executed before.
  • check if keys are in correct backend
  • remove syncbits
  • update sizes in the backends
Parameters
splitthe split object to work with
warningKeypostcondition violations are reported here
handlethe handle to preprocess the keys
Return values
1on success
-1if no backend was found for a key or split->parents has invalid namespace

◆ splitMergeBackends()

int splitMergeBackends ( Split *  split,
KeySet *  dest 
)

Merges together the backend based parts of split into dest, but bypasses the default split.

Parameters
splitthe split object to work with
destthe destination keyset where all keysets are appended.
Return values
1on success

◆ splitMergeDefault()

int splitMergeDefault ( Split *  split,
KeySet *  dest 
)

Merges the default split into dest.

Parameters
splitthe split object to work with
destthe destination keyset where all keysets are appended.
Return values
1on success

◆ splitNew()

Split* splitNew ( void  )

Allocates a new split object.

Splits up a keyset into multiple keysets where each of them will passed to the correct kdbSet().

Initially the size is 0 and alloc is APPROXIMATE_NR_OF_BACKENDS.

Returns
a fresh allocated split object
See also
splitDel()

◆ splitPrepare()

void splitPrepare ( Split *  split)

Prepares for kdbSet() mainloop afterwards.

All splits which do not need sync are removed and a deep copy of the remaining keysets is done.

Parameters
splitthe split object to work with

◆ splitRemove()

void splitRemove ( Split *  split,
size_t  where 
)

Remove one part of split.

Parameters
splitthe split object to work with
wherethe position to cut away
Precondition
where must be within the size of the split
Postcondition
split will be removed

◆ splitSync()

int splitSync ( Split *  split)

Add sync bits everywhere keys were removed/added.

  • checks if the size of a previous kdbGet() is unchanged.
  • checks if in correct state (kdbGet() needs to be executed before)

Only splitDivide() together with this function can really decide if sync is needed or not.

Precondition
split needs to be processed with splitDivide() before.
Return values
0if kdbSet() is not needed
1if kdbSet() is needed
-1on wrong keys (also has assert, should not happen)
-2wrong spec state: kdbGet() was not executed before
-3wrong dir state: kdbGet() was not executed before
-4wrong user state: kdbGet() was not executed before
-5wrong system state: kdbGet() was not executed before
Precondition
user:/system was split before.
Parameters
splitthe split object to work with

◆ splitUpdateFileName()

void splitUpdateFileName ( Split *  split,
KDB *  handle,
Key *  key 
)

Update the (configuration) file name for the parent key.

Parameters
splitthe split to work with
handlethe handle to work with
keythe parentKey that should be updated (name must be correct)

◆ splitUpdateSize()

int splitUpdateSize ( Split *  split)

Also update sizes after kdbSet() to recognize multiple kdbSet() attempts.

Warning
cant use the same code with splitGet because there is no default split part for kdbSet().

◆ trieClose()

int trieClose ( Trie *  trie,
Key *  errorKey 
)

Closes the trie and all opened backends within.

Parameters
triethe trie to close
errorKeythe key used to report warnings
Return values
0on success

◆ trieInsert()

Trie* trieInsert ( Trie *  trie,
const char *  name,
Backend *  value 
)

Insert into trie.

Parameters
triethe trie to insert to (0 to create a new trie)
namethe key's name to insert
valuethe value to insert
Return values
trieon success

◆ trieLookup()

Backend* trieLookup ( Trie *  trie,
const char *  name 
)

The Trie structure.

Lookups a backend inside the trie.

Returns
the backend if found
0 otherwise
Parameters
triethe trie object to work with
keythe name of this key will be looked up