.TH "split.c" 3elektra "Sat Oct 8 2022" "Version 0.9.11" "Elektra" \" -*- nroff -*- .ad l .nh .SH NAME split.c \- Interna of splitting functionality\&. .SH SYNOPSIS .br .PP \fC#include \fP .br \fC#include \fP .br \fC#include \fP .br .SS "Functions" .in +1c .ti -1c .RI "Split * \fBsplitNew\fP (void)" .br .RI "Allocates a new split object\&. " .ti -1c .RI "void \fBsplitDel\fP (Split *keysets)" .br .RI "Delete a split object\&. " .ti -1c .RI "void \fBsplitRemove\fP (Split *split, size_t where)" .br .RI "Remove one part of split\&. " .ti -1c .RI "ssize_t \fBsplitAppend\fP (Split *split, Backend *backend, Key *parentKey, int syncbits)" .br .RI "Increases the size of split and appends a new empty keyset\&. " .ti -1c .RI "int \fBsplitBuildup\fP (Split *split, KDB *kdb, Key *parentKey)" .br .RI "Walks through kdb->split and adds all backends below parentKey to split\&. " .ti -1c .RI "int \fBsplitDivide\fP (Split *split, KDB *handle, KeySet *ks)" .br .RI "Splits up the keysets and search for a sync bit in every key\&. " .ti -1c .RI "void \fBsplitUpdateFileName\fP (Split *split, KDB *handle, Key *key)" .br .RI "Update the (configuration) file name for the parent key\&. " .ti -1c .RI "int \fBsplitAppoint\fP (Split *split, KDB *handle, KeySet *ks)" .br .RI "Appoints all keys from ks to yet unsynced splits\&. " .ti -1c .RI "int \fBsplitGet\fP (Split *split, Key *warningKey, KDB *handle)" .br .RI "Does some work after getting of backends is finished\&. " .ti -1c .RI "int \fBsplitUpdateSize\fP (Split *split)" .br .RI "Also update sizes after \fBkdbSet()\fP to recognize multiple \fBkdbSet()\fP attempts\&. " .ti -1c .RI "int \fBsplitMergeBackends\fP (Split *split, KeySet *dest)" .br .RI "Merges together the backend based parts of split into dest, but bypasses the default split\&. " .ti -1c .RI "int \fBsplitMergeDefault\fP (Split *split, KeySet *dest)" .br .RI "Merges the default split into dest\&. " .ti -1c .RI "int \fBsplitSync\fP (Split *split)" .br .RI "Add sync bits everywhere keys were removed/added\&. " .ti -1c .RI "void \fBsplitPrepare\fP (Split *split)" .br .RI "Prepares for \fBkdbSet()\fP mainloop afterwards\&. " .in -1c .SH "Detailed Description" .PP Interna of splitting functionality\&. .PP \fBCopyright\fP .RS 4 BSD License (see LICENSE\&.md or https://www.libelektra.org) .RE .PP .SH "Function Documentation" .PP .SS "ssize_t splitAppend (Split * split, Backend * backend, Key * parentKey, int syncbits)" .PP Increases the size of split and appends a new empty keyset\&. Initializes the element with the given parameters at size-1 to be used\&. .PP Will automatically resize split if needed\&. .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIbackend\fP the backend which should be appended .br \fIparentKey\fP the parentKey which should be appended .br \fIsyncbits\fP the initial syncstate which should be appended .RE .PP \fBReturn values\fP .RS 4 \fI-1\fP if no split is found .RE .PP \fBReturns\fP .RS 4 the position of the new element: size-1 .RE .PP .SS "int splitAppoint (Split * split, KDB * handle, KeySet * ks)" .PP Appoints all keys from ks to yet unsynced splits\&. .PP \fBPrecondition\fP .RS 4 \fBsplitBuildup()\fP need to be executed before\&. .RE .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIhandle\fP to determine to which backend a key belongs .br \fIks\fP the keyset to appoint to split .RE .PP \fBReturn values\fP .RS 4 \fI1\fP on success .br \fI-1\fP if no backend was found for a key .RE .PP .SS "int splitBuildup (Split * split, KDB * kdb, Key * parentKey)" .PP 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\&. .PP \fBPrecondition\fP .RS 4 split needs to be empty, directly after creation with \fBsplitNew()\fP\&. .PP there needs to be a valid defaultBackend but its ok not to have a trie inside KDB\&. .PP parentKey must be a valid key! (could be implemented more generally, but that would require splitting up of keysets of the same backend) .RE .PP \fBParameters\fP .RS 4 \fIsplit\fP will get all backends appended .br \fIkdb\fP the handle to get information about backends .br \fIparentKey\fP the information below which key the backends are from interest .RE .PP \fBReturn values\fP .RS 4 \fI1\fP always .RE .PP .SS "void splitDel (Split * keysets)" .PP Delete a split object\&. Will free all allocated resources of a split keyset\&. .PP \fBParameters\fP .RS 4 \fIkeysets\fP the split object to work with .RE .PP .SS "int splitDivide (Split * split, KDB * handle, KeySet * ks)" .PP Splits up the keysets and search for a sync bit in every key\&. It does not check if there were removed keys, see \fBsplitSync()\fP for the next step\&. .PP It does not create new backends, this has to be done by buildup before\&. .PP \fBPrecondition\fP .RS 4 \fBsplitBuildup()\fP need to be executed before\&. .RE .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIhandle\fP to get information where the individual keys belong .br \fIks\fP the keyset to divide .RE .PP \fBReturn values\fP .RS 4 \fI0\fP if there were no sync bits .br \fI1\fP if there were sync bits .br \fI-1\fP if no backend was found for any key .RE .PP .SS "int splitGet (Split * split, Key * warningKey, KDB * handle)" .PP Does some work after getting of backends is finished\&. .IP "\(bu" 2 Update sizes .IP "\(bu" 2 Removal of wrong keys .PP .PP \fBPrecondition\fP .RS 4 \fBsplitAppoint()\fP needs to be executed before\&. .RE .PP .IP "\(bu" 2 check if keys are in correct backend .IP "\(bu" 2 remove syncbits .IP "\(bu" 2 update sizes in the backends .PP .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIwarningKey\fP postcondition violations are reported here .br \fIhandle\fP the handle to preprocess the keys .RE .PP \fBReturn values\fP .RS 4 \fI1\fP on success .br \fI-1\fP if no backend was found for a key or split->parents has invalid namespace .RE .PP .SS "int splitMergeBackends (Split * split, KeySet * dest)" .PP Merges together the backend based parts of split into dest, but bypasses the default split\&. .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIdest\fP the destination keyset where all keysets are appended\&. .RE .PP \fBReturn values\fP .RS 4 \fI1\fP on success .RE .PP .SS "int splitMergeDefault (Split * split, KeySet * dest)" .PP Merges the default split into dest\&. .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIdest\fP the destination keyset where all keysets are appended\&. .RE .PP \fBReturn values\fP .RS 4 \fI1\fP on success .RE .PP .SS "Split* splitNew (void)" .PP Allocates a new split object\&. Splits up a keyset into multiple keysets where each of them will passed to the correct \fBkdbSet()\fP\&. .PP Initially the size is 0 and alloc is APPROXIMATE_NR_OF_BACKENDS\&. .PP \fBReturns\fP .RS 4 a fresh allocated split object .RE .PP \fBSee also\fP .RS 4 \fBsplitDel()\fP .RE .PP .SS "void splitPrepare (Split * split)" .PP Prepares for \fBkdbSet()\fP mainloop afterwards\&. All splits which do not need sync are removed and a deep copy of the remaining keysets is done\&. .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .RE .PP .SS "void splitRemove (Split * split, size_t where)" .PP Remove one part of split\&. .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .br \fIwhere\fP the position to cut away .RE .PP \fBPrecondition\fP .RS 4 where must be within the size of the split .RE .PP \fBPostcondition\fP .RS 4 split will be removed .RE .PP .SS "int splitSync (Split * split)" .PP Add sync bits everywhere keys were removed/added\&. .IP "\(bu" 2 checks if the size of a previous \fBkdbGet()\fP is unchanged\&. .IP "\(bu" 2 checks if in correct state (\fBkdbGet()\fP needs to be executed before) .PP .PP Only \fBsplitDivide()\fP together with this function can really decide if sync is needed or not\&. .PP \fBPrecondition\fP .RS 4 split needs to be processed with \fBsplitDivide()\fP before\&. .RE .PP \fBReturn values\fP .RS 4 \fI0\fP if \fBkdbSet()\fP is not needed .br \fI1\fP if \fBkdbSet()\fP is needed .br \fI-1\fP on wrong keys (also has assert, should not happen) .br \fI-2\fP wrong spec state: \fBkdbGet()\fP was not executed before .br \fI-3\fP wrong dir state: \fBkdbGet()\fP was not executed before .br \fI-4\fP wrong user state: \fBkdbGet()\fP was not executed before .br \fI-5\fP wrong system state: \fBkdbGet()\fP was not executed before .RE .PP \fBPrecondition\fP .RS 4 user:/system was split before\&. .RE .PP \fBParameters\fP .RS 4 \fIsplit\fP the split object to work with .RE .PP .SS "void splitUpdateFileName (Split * split, KDB * handle, Key * key)" .PP Update the (configuration) file name for the parent key\&. .PP \fBParameters\fP .RS 4 \fIsplit\fP the split to work with .br \fIhandle\fP the handle to work with .br \fIkey\fP the parentKey that should be updated (name must be correct) .RE .PP .SS "int splitUpdateSize (Split * split)" .PP Also update sizes after \fBkdbSet()\fP to recognize multiple \fBkdbSet()\fP attempts\&. .PP \fBWarning\fP .RS 4 cant use the same code with splitGet because there is no default split part for \fBkdbSet()\fP\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Elektra from the source code\&.