Merge pull request #1850 from waht/notification_api2

notification: improved API

doc/Doxyfile

@@ -2039,7 +2039,7 @@ PREDEFINED             = "ELEKTRA_UNUSED="
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = "ELEKTRA_NOTIFICATION_TYPE_DECLARATION"
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have

doc/decisions/deferred_plugin_calls.md

@@ -15,8 +15,9 @@ required to be able to defer these calls until the plugins are loaded.
 
 For example when setting I/O bindings with `elektraIoSetBinding()` the exported
 function `setIoBinding` is called for all globally mounted plugins.
-Since global mounting is implemented using the "list" plugin the exported
-functions from the plugins are unavailable.
+Since global mounting is implemented using the "list" plugin which uses
+lazy-loading for its plugins the exported functions from the plugins are
+unavailable.
 
 Other examples are the "dini" and "multifile" plugins which use multiple plugins
 to support different file formats.
@@ -31,7 +32,8 @@ These plugins also "hide" functions exported by encapsulated plugins.
 
 ## Assumptions
 
-1. The called functions do not return a value (e.g. `set`, `open`, `close`, ...)
+1. The called functions do not return a value (e.g. `set`, `open`, `close`, ...).
+   Callbacks can be used as return channel (see "Implications")
 
 ## Considered Alternatives
 
@@ -67,14 +69,14 @@ These plugins also "hide" functions exported by encapsulated plugins.
 
 Encapsulating plugins export a function called `deferredCall` with the
 declaration
-`void ElektraDeferredCall (Plugin * plugin, char * name, KeySet * parameters)`.
+`void elektraDeferredCall (Plugin * plugin, char * name, KeySet * parameters)`.
 Encapsulating plugins shall save multiple deferred calls and call the exported
 functions specified by `name` passing the `parameters` KeySet when a plugin is
 initialized in the same order as received.
 
 Plugins that support deferred calls shall have the following declaration for
 their functions
-`void ElektraDeferredCallable (Plugin * plugin, KeySet * parameters)`.
+`void somePluginFunction (Plugin * plugin, KeySet * parameters)`.
 The calling developer is responsible for ensuring that the called functions have
 a compatible declaration.
 Encapsulated plugins that do not export a specified function name are omitted.
@@ -89,15 +91,15 @@ breaking callers.
 The called function receive their parameters via a KeySet.
 
 While called functions could return data using the `parameters` KeySet (or a
-seperate KeySet) there is no defined moment when the data can be collected.
+separate KeySet) there is no defined moment when the data can be collected.
 Defining such a moment would break the lazy-loading constraint.
 It is recommended to use callbacks passed as `parameters`.
-The callback function declaration is not affected by this decision.
+Callback function declarations are not limited by this decision.
 
 ## Related decisions
 
-- Elektra's invoke functionality will be extended to also allow use of deferred
-calls with new functions:
+- Elektra's invoke functionality will be extended to also allow us to use
+  deferred calls with new functions:
 
 - `int elektraInvokeFunctionDeferred (ElektraInvokeHandle * handle, const char * elektraPluginFunctionName, KeySet * ks)`
   which defers a call if the plugin exports `deferredCall`.
@@ -106,7 +108,7 @@ calls with new functions:
 
 - Functions supporting deferred calls should allow for multiple calls (i.e.
   they should be idempotent).
-  This leaves state at affected plugins and does avoids duplicating state (e.g.
+  This leaves state at affected plugins and does avoid duplicating state (e.g.
   "was this function called for this plugin before?") in encapsulating
   plugins.
 

doc/news/_preparation_next_release.md

@@ -40,7 +40,7 @@ You can also read the news [on our website](https://www.libelektra.org/news/0.8.
 - Type system preview
 - Chef Cookbook
 - Elektra Web 1.6
-
+- Notifications
 
 ### Type system preview
 
@@ -133,6 +133,37 @@ Try it out now on: http://webdemo.libelektra.org/
 Thanks to Daniel Bugl.
 
 
+### Notifications
+
+Elektra's notification feature which allows applications to keep persistent
+configuration settings in sync with the key database and other applications was
+greatly improved with this release:
+
+- The [notification API](https://doc.libelektra.org/api/current/html/group__kdbnotification.html)
+  now supports more types and has improved support for callbacks.
+- With the addition of the [zeromqsend](https://www.libelektra.org/plugins/zeromqsend)
+  and [zeromqrecv](https://www.libelektra.org/plugins/zeromqrecv) plugins
+  together with the [hub-zeromq](https://www.libelektra.org/tools/hub-zeromq)
+  tool we have an alternative to the D-Bus transport plugins
+  ([dbus](https://www.libelektra.org/plugins/dbus) and
+  [dbusrecv](https://www.libelektra.org/plugins/dbusrecv)).
+- The new asynchronous I/O binding for [ev](https://www.libelektra.org/bindings/io_ev)
+  is the third I/O binding - so notifications can be used in applications using
+  [glib](https://www.libelektra.org/bindings/io_glib), [uv](https://www.libelektra.org/bindings/io_uv)
+  or [ev](https://www.libelektra.org/bindings/io_ev).
+  If your application uses a different library please check out the
+  ["How to create your own I/O binding" section](https://www.libelektra.org/tutorials/notifications#how-to-create-your-own-i-o-binding) in the [notification tutorial](https://www.libelektra.org/tutorials/notifications).
+- Notifications can be used to reload KDB after Elektra's configuration (e.g.
+  mountpoints or globally mounted plugins) has changed.
+  We added a [how-to to the notification tutorial](https://www.libelektra.org/tutorials/notifications#howto-reload-kdb-when-elektras-configuration-has-changed)
+  that explains the required steps and the ["notificationReload"](https://www.libelektra.org/examples/notificationreload) example with the complete code.
+
+More details can be [found](#zeromq-transport-plugins) [in](#misc) [this](#bindings) [news](#notifications).
+Check out the updated [notification tutorial](https://www.libelektra.org/tutorials/notifications)
+and notification examples ([polling](https://www.libelektra.org/examples/notificationpolling),
+[async](https://www.libelektra.org/examples/notificationasync) and
+[reload](https://www.libelektra.org/examples/notificationreload).
+
 ## Plugins
 
 ### CCode
@@ -367,7 +398,8 @@ Thanks to Daniel Bugl.
 - replaced strdup with elektraStrDup (for C99 compatibility) *(Markus Raab)*
 - You can now remove the basename of a key via the C++ API by calling `key.delBaseName()`. *(René Schwaiger)*
 - The function `elektraArrayGetNextKey` now uses `NULL` instead of the empty string as init value for the returned key. *(René Schwaiger)*
-
+- <<TODO>>
+- <<TODO>>
 - <<TODO>>
 
 ### pluginprocess
@@ -393,6 +425,17 @@ Thanks to Daniel Bugl.
   It can be used to integrate the notification feature with applications based
   on [ev](http://libev.schmorp.de) main loops. *(Thomas Wahringer)*
 
+## Notifications
+
+- The
+  [notification API](https://doc.libelektra.org/api/current/html/group__kdbnotification.html)
+  was extended.
+  The API now supports more types: `int`, `unsigned int`,
+  `long`, `unsigned long`, `long long`, `unsinged long long`, `float` and `double`.
+  It also supports all of Elektra's `kdb_*_t` types defined in `kdbtypes.h`.
+  Also contexts for callbacks were added and
+  `elektraNotificationRegisterCallbackSameOrBelow()` allows for notifications
+  for the registered key or below. *(Thomas Wahringer)*
 
 ## Tools
 
@@ -618,7 +661,10 @@ compiled against an older 0.8 version of Elektra will continue to work
 Following changes were made:
 
 - The C++ API was extended with delBaseName()
-- <<TODO>>
+- `kdbtypes.h` now comes with support for C99 types
+- We added the private headerfiles `kdbnotificationinternal.h`, `kdbioplugin.h`. *(Thomas Wahringer)*
+- The I/O binding header files have been moved a new directory called `kdbio`.
+  For example, instead of including `elektra/kdbio_ev.h` users of the binding now include `elektra/kdbio/ev.h`. *(Thomas Wahringer)*
 - <<TODO>>
 
 ## Website