notification: add news highlight & improve docs

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
@@ -394,9 +425,12 @@ Thanks to Daniel Bugl.
 - The
   [notification API](https://doc.libelektra.org/api/current/html/group__kdbnotification.html)
   was extended.
-  The API now supports contexts for callbacks, the types `int`, `unsigned int`,
+  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`. *(Thomas Wahringer)*
+  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
 
@@ -486,20 +520,6 @@ Thanks to Daniel Bugl.
 [Markdown Shell Recorder]: https://master.libelektra.org/tests/shell/shell_recorder/tutorial_wrapper
 [Shell Recorder]: (https://master.libelektra.org/tests/shell/shell_recorder)
 
-## Compatibility
-
-As always, the ABI and API of kdb.h is fully compatible, i.e. programs
-compiled against an older 0.8 version of Elektra will continue to work
-(ABI) and you will be able to recompile programs without errors (API).
-
-- <<TODO>>
-- <<TODO>>
-- <<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)*
-
 ## Build
 
 ### CMake
@@ -629,7 +649,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

doc/tutorials/notifications.md

@@ -137,8 +137,8 @@ Values of registered variables are automatically updated when the value of the
 assigned key has changed.
 In the following example we will register an integer variable.
 
-The following examples are shortened for tangibility. The complete example is available in
-[src/libs/notification/example/example_notification_async.c](https://github.com/ElektraInitiative/libelektra/blob/master/src/libs/notification/example/example_notification_async.c).
+The following examples are shortened for tangibility. The complete code is available in
+["notificationAsync" example](https://www.libelektra.org/examples/notificationasync).
 
 ```C
 #include <elektra/kdb.h>
@@ -297,7 +297,7 @@ void initKdb (ElektraIoTimerOperation * timerOp ELEKTRA_UNUSED)
 	elektraNotificationOpen (kdb);
 
 	// Code for registration from snippet before
-	Key * elektraKey = keyNew ("system/elektra", KEY_END);
+	Key * elektraKey = keyNew ("/elektra", KEY_END);
 	elektraNotificationRegisterCallbackSameOrBelow (kdb, elektraKey, elektraChangedCallback, NULL);
 	keyDel (elektraKey);
 
@@ -326,7 +326,8 @@ First, we create the timer in the main loop setup of the application.
 ElektraIoTimerOperation * reload;
 
 // main loop setup (e.g. main())
-// the timer operation will reload KDB after 100 milliseconds
+// the timer operation is disabled for now and
+// will reload KDB after 100 milliseconds
 reload = elektraIoNewTimerOperation (100, 0, initKdb, NULL);
 elektraIoBindingAddTimer (binding, reload);
 ```
@@ -367,6 +368,8 @@ to Elektra's configuration.
 The snippets above omit error handling for brevity. The complete code including
 error handling is available in the
 ["notification reload" example](https://www.libelektra.org/examples/notificationreload).
+This example also omits globals by passing them as user data using the
+`elektraIo*GetData()` functions.
 
 ## Emergent Behavior Guidelines
 

examples/notificationAsync.c

@@ -9,8 +9,8 @@
  *   - Transport plugins (e.g. kdb global-mount dbus announce=once dbusrecv)
  *
  * Relevant keys for this example:
- *   - /sw/elektra/example_notification/#0/current/value: Set to any integer value
- *   - /sw/elektra/example_notification/#0/current/color: Set the text color. Possible
+ *   - /sw/example/notification/#0/current/value: Set to any integer value
+ *   - /sw/example/notification/#0/current/color: Set the text color. Possible
  *     values are "red", "green" and "blue".
  *
  * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
@@ -95,7 +95,7 @@ int main (void)
 
 	KeySet * config = ksNew (20, KS_END);
 
-	Key * key = keyNew ("/sw/elektra/example_notification/#0/current", KEY_END);
+	Key * key = keyNew ("/sw/example/notification/#0/current", KEY_END);
 	KDB * kdb = kdbOpen (key);
 	if (kdb == NULL)
 	{
@@ -115,15 +115,15 @@ int main (void)
 	}
 
 	int value = 0;
-	Key * intKeyToWatch = keyNew ("/sw/elektra/example_notification/#0/current/value", KEY_END);
+	Key * intKeyToWatch = keyNew ("/sw/example/notification/#0/current/value", KEY_END);
 	result = elektraNotificationRegisterInt (kdb, intKeyToWatch, &value);
 	if (!result)
 	{
 		printf ("could not register variable, aborting\n");
 		return -1;
 	}
 
-	Key * callbackKeyToWatch = keyNew ("/sw/elektra/example_notification/#0/current/color", KEY_END);
+	Key * callbackKeyToWatch = keyNew ("/sw/example/notification/#0/current/color", KEY_END);
 	result = elektraNotificationRegisterCallback (kdb, callbackKeyToWatch, &setTerminalColor, NULL);
 	if (!result)
 	{
@@ -137,7 +137,7 @@ int main (void)
 
 	printf ("Asynchronous Notification Example Application\n");
 	printf ("Please note that notification transport plugins are required see\n"
-		"  https://www.libelektra.org/tutorials/notifications#notification-configuration!\n");
+		" https://www.libelektra.org/tutorials/notifications#notification-configuration!\n");
 	printf ("- Set \"%s\" to red, blue or green to change the text color\n", keyName (callbackKeyToWatch));
 	printf ("- Set \"%s\" to any integer value\n", keyName (intKeyToWatch));
 	printf ("Send SIGINT (Ctl+C) to exit.\n\n");

examples/notificationPolling.c

@@ -2,11 +2,11 @@
  * @file
  *
  * @brief Example for notification library which repeatedly reads some keys and
- * reacts to them; see "example_notification_async" for an example without polling
+ * reacts to them; see "notificationAsync.c" for an example without polling
  *
  * Relevant keys for this example:
- *   - /sw/elektra/example_notification/#0/current/value: Set to any integer value
- *   - /sw/elektra/example_notification/#0/current/color: Set the text color. Possible
+ *   - /sw/example/notification/#0/current/value: Set to any integer value
+ *   - /sw/example/notification/#0/current/color: Set the text color. Possible
  *     values are "red", "green" and "blue".
  *
  * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
@@ -89,7 +89,7 @@ int main (void)
 
 	KeySet * config = ksNew (20, KS_END);
 
-	Key * key = keyNew ("/sw/elektra/example_notification/#0/current", KEY_END);
+	Key * key = keyNew ("/sw/example/notification/#0/current", KEY_END);
 	KDB * kdb = kdbOpen (key);
 	if (kdb == NULL)
 	{
@@ -105,15 +105,15 @@ int main (void)
 	}
 
 	int value = 0;
-	Key * intKeyToWatch = keyNew ("/sw/elektra/example_notification/#0/current/value", KEY_END);
+	Key * intKeyToWatch = keyNew ("/sw/example/notification/#0/current/value", KEY_END);
 	result = elektraNotificationRegisterInt (kdb, intKeyToWatch, &value);
 	if (!result)
 	{
 		printf ("could not register variable, aborting\n");
 		return -1;
 	}
 
-	Key * callbackKeyToWatch = keyNew ("/sw/elektra/example_notification/#0/current/color", KEY_END);
+	Key * callbackKeyToWatch = keyNew ("/sw/example/notification/#0/current/color", KEY_END);
 	result = elektraNotificationRegisterCallback (kdb, callbackKeyToWatch, &setTerminalColor, NULL);
 	if (!result)
 	{
@@ -127,7 +127,7 @@ int main (void)
 	while (!keepRunning)
 	{
 		// After this kdbGet the integer variable is updated and the callback was called.
-		// see "example_notification_async" for an example without polling
+		// see "notificationAsync" for an example without polling
 		kdbGet (kdb, config, key);
 
 		// Print values

examples/notificationReload.c

@@ -10,7 +10,7 @@
  *   - Transport plugins (e.g. kdb global-mount zeromqsend zeromqrecv && kdb run-hub-zeromq)
  *
  * Relevant keys for this example:
- *   - /sw/elektra/example_notification/#0/current/value: Set to any integer value
+ *   - /sw/example/notification/#0/current/value: Set to any integer value
  *   Add additional transport plugins and remove the original pair afterwards or
  *   mount a file which sets the key above to a different value and unmount it again
  *
@@ -178,8 +178,8 @@ int main (void)
 	g_unix_signal_add (SIGINT, onSIGNAL, data);
 
 	data->config = ksNew (20, KS_END);
-	data->parentKey = keyNew ("/sw/elektra/example_notification/#0/current", KEY_END);
-	data->intKeyToWatch = keyNew ("/sw/elektra/example_notification/#0/current/value", KEY_END);
+	data->parentKey = keyNew ("/sw/example/notification/#0/current", KEY_END);
+	data->intKeyToWatch = keyNew ("/sw/example/notification/#0/current/value", KEY_END);
 
 	// Setup timer that repeatedly prints the variable
 	data->timer = elektraIoNewTimerOperation (TWO_SECONDS, 1, printVariable, data);
@@ -191,7 +191,7 @@ int main (void)
 
 	printf ("Reloading Notification Example Application\n");
 	printf ("Please note that notification transport plugins are required see\n"
-		"  https://www.libelektra.org/tutorials/notifications#notification-configuration!\n");
+		" https://www.libelektra.org/tutorials/notifications#notification-configuration!\n");
 	printf ("- Set \"%s\" to any integer value\n", keyName (data->intKeyToWatch));
 	printf ("- Try to add additional transport plugins and remove the original pair afterwards\n");
 	printf ("- Mount a file which sets the key above to a different value and unmount it\n");
@@ -208,5 +208,6 @@ int main (void)
 	ksDel (data->config);
 	keyDel (data->intKeyToWatch);
 	keyDel (data->parentKey);
+	elektraFree (data);
 	printf ("cleanup done!\n");
 }

src/bindings/io/glib/README.md

@@ -36,7 +36,6 @@ Populated I/O interface
 ## Example
 
 ```C
-
 #include <elektra/kdb.h>
 #include <elektra/kdbio.h>
 #include <elektra/kdbio/glib.h>
@@ -65,5 +64,7 @@ void main (void)
 	elektraIoBindingCleanup (binding);
 	g_main_loop_unref (loop);
 }
-
 ```
+
+Please check out the ["notificationReload" example](https://www.libelektra.org/examples/notificationreload)
+which uses this I/O binding.

src/bindings/io/uv/README.md

@@ -35,7 +35,6 @@ Populated I/O interface
 ## Example
 
 ```C
-
 #include <elektra/kdb.h>
 #include <elektra/kdbio.h>
 #include <elektra/kdbio/uv.h>
@@ -63,5 +62,7 @@ void main (void)
 	elektraIoBindingCleanup (binding);
 	uv_loop_close (loop);
 }
-
 ```
+
+Please check out the ["notificationAsync" example](https://www.libelektra.org/examples/notificationasync)
+which uses this I/O binding.

src/tools/hub-zeromq/hub-zeromq.c

@@ -35,7 +35,7 @@ static void onSignal (int signal)
 
 int main (void)
 {
-	printf ("lightweight zeromq message hub\n");
+	printf ("\nlightweight zeromq message hub\n");
 
 	// exit on SIGINT
 	signal (SIGINT, onSignal);
@@ -97,7 +97,8 @@ int main (void)
 	}
 
 	printf ("listening on %s (XSUB for zeromqsend)\n", xSubEndpoint);
-	printf ("listening on %s (XPUB for zeromqrecv)\n\n", xPubEndpoint);
+	printf ("listening on %s (XPUB for zeromqrecv)\n", xPubEndpoint);
+	printf ("hub is running\n");
 	ksDel (config);
 
 	// forward messages between sockets