Merge pull request #3651 from kodebach/kodebach/issue2764

Integrate kdbEnsure into kdbOpen

benchmarks/kdb.c

@@ -32,7 +32,7 @@ int main (void)
 		Key * parentKey = keyNew ("user:/", KEY_END);
 
 		timeInit ();
-		KDB * handle = kdbOpen (parentKey);
+		KDB * handle = kdbOpen (NULL, parentKey);
 		fprintf (stdout, CSV_STR_FMT, "core", "kdbOpen", timeGetDiffMicroseconds ());
 
 		kdbGet (handle, returned, parentKey);
@@ -50,7 +50,7 @@ int main (void)
 	{
 		timeInit ();
 		Key * parentKey = keyNew ("user:/benchmark", KEY_END);
-		KDB * handle = kdbOpen (parentKey);
+		KDB * handle = kdbOpen (NULL, parentKey);
 		fprintf (stdout, CSV_STR_FMT, "core", "kdbOpen", timeGetDiffMicroseconds ());
 
 		KeySet * returned = ksNew (0, KS_END);

benchmarks/large.c

@@ -13,7 +13,7 @@ Key * key;
 
 void benchmarkOpen (void)
 {
-	kdb = kdbOpen (key);
+	kdb = kdbOpen (NULL, key);
 }
 
 void benchmarkInread (void)

benchmarks/memoryleak.c

@@ -23,7 +23,7 @@ int main (void)
 
 	for (size_t i = 0; i < NUM_RUNS; ++i)
 	{
-		KDB * handle = kdbOpen (parentKey);
+		KDB * handle = kdbOpen (NULL, parentKey);
 
 		KeySet * ks = ksNew (0, KS_END);
 

doc/VISION.md

@@ -123,7 +123,7 @@ int main (void)
 {
 	KeySet * myConfig = ksNew (0, KS_END);
 	Key * key = keyNew ("/sw/samba/#0/current", KEY_END);
-	KDB * handle = kdbOpen (key);
+	KDB * handle = kdbOpen (NULL, key);
 	kdbGet (handle, myConfig, key);
 
 	Key * result = ksLookupByName (myConfig, "/sw/samba/#0/current/global/workgroup", 0);

doc/decisions/ensure.md

@@ -42,23 +42,24 @@ Integrate `kdbEnsure` in `kdbOpen(Key *errorKey, KeySet *contract)` but only all
 
 ## Implications
 
-`elektraNotificationOpen` will only return a contract KeySet:
+`elektraNotificationOpen` will be renamed and only return a contract KeySet:
 
 ```c
+KeySet * errorKey = keyNew ("/", KEY_END);
 KeySet * contract = ksNew (0, KS_END);
-elektraNotificationContract (contract, iobinding);
+elektraNotificationContract (contract, iobinding, errorKey);
 ```
 
 The same for gopts:
 
 ```c
-elektraGOptsContract (contract, argc, argv, environ);
+elektraGOptsContract (contract, argc, argv, environ, errorKey);
 ```
 
 Finally, we create `KDB` with the contracts we got before:
 
 ```c
-KDB * kdb = kdbOpen (key, contract);
+KDB * kdb = kdbOpen (contract, parentKey);
 ```
 
 Opening `KDB` will fail if any of the contracts cannot be ensured.
@@ -77,7 +78,8 @@ kdbClose (kdb, errorKey);
 ```
 
 It is safe to use the contract `KeySet` also for `kdbGet` and `kdbSet`
-invocations.
+invocations. Contract `KeySet`s only contain `Key`s below
+`system:/elektra/contract`. Therefore, normal `KeySet`s should not interfere.
 
 ## Related Decisions
 

doc/dev/README.md

@@ -10,6 +10,7 @@ It complements the man pages found [here](/doc/help).
 
 ## Concepts
 
+- [KDB Contracts](kdb-contracts.md)
 - [Logging](logging.md)
 - [Error Handling](error-handling.md)
 - [Error Message](error-message.md)

doc/dev/kdb-contracts.md

@@ -0,0 +1,43 @@
+# KDB Contracts
+
+The `kdbOpen()` function accepts a `KeySet * contract` parameter.
+This parameter allows you to extend and configure the KDB within your application without permanently changing files on disk.
+
+## Contract Structure
+
+The contract consists of Keys below `system:/elektra/contract/<type>`, where `<type>` is one of a set of predefined contract types.
+Currently, the types `globalkeyset` and `mountglobal` are supported.
+
+### Global KeySet Contracts
+
+To insert data into the global KeySet during `kdbOpen`, you can add keys below `system:/elektra/contract/globalkeyset`.
+All these keys will be renamed and copied into the global KeySet that is passed to all plugins.
+
+Specifically, the subset below `system:/elektra/contract/globalkeyset` is moved to `system:/elektra` and then inserted into the global KeySet.
+
+### Mounting Global Plugins
+
+You can also mount a global plugin with a contract.
+To do this, add a key `system:/elektra/contract/mountglobal/<plugin>` where `<plugin>` is the name of the plugin you want to mount.
+The keys below `system:/elektra/contract/mountglobal/<plugin>` will be moved to `user:/` and used as the config for `<plugin>`.
+
+## Pre-defined Contracts
+
+There are a few pre-defined contracts that can be accessed via helper functions.
+
+### GOpts
+
+To mount and configure the `gopts` plugin you can use `elektraGOptsContract`.
+There is also `elektraGOptsContractFromStrings`, but its use is discouraged unless you really need it.
+It mainly exists for use from various bindings.
+
+### I/O binding
+
+To set the I/O binding to be used in a KDB instance, use `elektraIoContract`.
+
+### Notification
+
+To set up notifications use the `elektraNotificationContract` function.
+It automatically sets up the `internalnotification` plugin.
+
+If you also need to set up notification transport plugins, you should manually add the relevant `system:/elektra/contract/mountglobal/<plugin>` keys and the required config below.

doc/news/_preparation_next_release.md

@@ -29,11 +29,44 @@ This is the quickest way to get started with Elektra without compiling and other
 
 ## Highlights
 
-- <<HIGHLIGHT1>>
+- Breaking change to `kdbOpen`. _[see below](#hl-1)_
 - <<HIGHLIGHT2>>
 - <<HIGHLIGHT3>>
 
-### <<HIGHLIGHT1>>
+<a id="hl-1"></a>
+
+### `kdbOpen` Contracts
+
+The signature of `kdbOpen` has been changed from
+
+```c
+KDB *  kdbOpen (Key * errorKey);
+```
+
+to
+
+```c
+KDB * kdbOpen(const KeySet * contract, Key *parentKey);
+```
+
+You can use `kdbOpen (NULL, errorKey)` to get the same behaviour as before.
+
+The new parameter `contract` is similar to what could be done via `kdbEnsure` (which has been removed).
+Currently, the contract allows you to mount global plugins and add data into the global KeySet (passed to all plugins)
+during `kdbOpen`. This alone is already quite powerful, but we might more functionality in future releases.
+
+For now, there are three use cases for the `contract` parameter. All of them are covered by helper functions:
+
+```c
+int elektraGOptsContract (KeySet * contract, int argc, const char * const * argv, const char * const * envp, const Key * parentKey, KeySet * goptsConfig);
+int elektraIoContract (KeySet * contract, ElektraIoInterface * ioBinding);
+int elektraNotificationContract (KeySet * contract);
+```
+
+With `elektraGOptsContract` you can mount and set up the `gopts` plugin used for command-line argument parsing.
+The other two functions are the new way to configure Elektra's notification feature.
+
+For more information take a look at [doc/dev/kdb-contracts.md](../dev/kdb-contracts.md)
 
 ### <<HIGHLIGHT2>>
 
@@ -43,17 +76,29 @@ This is the quickest way to get started with Elektra without compiling and other
 
 The following section lists news about the [plugins](https://www.libelektra.org/plugins/readme) we updated in this release.
 
-### <<Plugin1>>
+### Cache
 
-- <<TODO>>
+- The `cache` plugin now only caches the parts of the global keyset that are below `system:/elektra/cache` or below
+  `system:/elektra/cached`. The part below `system:/elektra/cache` is meant for internal data of the `cache`, so you
+  should put data below `system:/elektra/cached`, if you want it to be cached. _(Klemens Böswirth)_
 - <<TODO>>
 - <<TODO>>
 
-### <<Plugin2>>
+### Dbus
 
-- <<TODO>>
-- <<TODO>>
-- <<TODO>>
+- Internal changes to ensure compatibility with the new `elektraNotificationContract`. _(Klemens Böswirth)_
+
+### Dbusrecv
+
+- Internal changes to ensure compatibility with the new `elektraNotificationContract`. _(Klemens Böswirth)_
+
+### Zeromqsend
+
+- Internal changes to ensure compatibility with the new `elektraNotificationContract`. _(Klemens Böswirth)_
+
+### Zeromqrecv
+
+- Internal changes to ensure compatibility with the new `elektraNotificationContract`. _(Klemens Böswirth)_
 
 ### <<Plugin3>>
 
@@ -67,31 +112,37 @@ The text below summarizes updates to the [C (and C++)-based libraries](https://w
 
 ### Compatibility
 
-- <<TODO>>
-- <<TODO>>
+- `keyCopy` and `keyDup` now take an additional flag. See [below](#key-copy).
+- `kdbEnsure` was removed and integrated into `kdbOpen`, which now takes an additional `KeySet * contract` parameter. See [above](#hl-1)
 - <<TODO>>
 
 ### Core
 
+<a id="key-copy"></a>
+
 - The `keyCopy` and `keyDup` functions have been changed. They now take a `flags` argument which specifies which parts
   of the `Key` should be copied.
   The API also changed slightly. Most importantly `NULL` values are handled differently. For example, `keyDup (NULL, KEY_CP_ALL)`
   returns a key similar to what `keyNew ("/", KEY_END)` produces, whereas previously `keyDup (NULL)` returned `NULl`.
   _(Klemens Böswirth)_
 - <<TODO>>
-- <<TODO>>
+- We added `keyReplacePrefix`, a function that allows you to easily move a key from one parent to another. _(Klemens Böswirth)_
+- `kdbEnsure` was removed and replaced by similar functionality added to `kdbOpen`. _[see above](#hl-1)_ _(Klemens Böswirth)_
+- `KEY_END` is now defined as `(void *) 0` instead of `0`. This allows us to mark `keyNew` with the GCC attribute
+  `__attribute__ ((sentinel))`, which causes a compiler warning, if `keyNew` calls don't use `KEY_END` as their last argument.
+  _(Klemens Böswirth)_
 
-### <<Library1>>
+### Io
 
-- <<TODO>>
-- <<TODO>>
-- <<TODO>>
+- `elektraSetIoBinding` has been removed. Use `elektraIoContract` instead. _(Klemens Böswirth)_
 
-### <<Library2>>
+### Notification
 
-- <<TODO>>
-- <<TODO>>
-- <<TODO>>
+- `elektraNotificationOpen` has been removed. Use `elektraNotificationContract` instead.
+  `elektraNotificationClose` has also been removed. There is no replacement, cleanup now happens automatially during
+  `kdbClose`. _(Klemens Böswirth)_
+- The contract for transport plugins has been changed. The exported functions `"openNotification"`, `"closeNotification" and`"setIoBinding"`are no longer used. Instead, plugins should retrieve the I/O binding from the key`system:/elektra/io/binding`in the global keyset. The notification callback and context that were passed to`"openNotification"`, can now be read from the global keyset as well. The keys are`system:/elektra/notification/callback`and`system:/elektra/notification/context` respectively.
+  _(Klemens Böswirth)_
 
 ### <<Library3>>