This document is a programmer's guide that describes how to use the Ivy C
library to connect applications to an Ivy bus. This guide describes version 3.0
@@ -50,18 +50,33 @@ then leave the bus without blocking the others.
As opposed to other software buses, Ivy does not depend on a centralised
server. Actually, Ivy is mostly a communication convention between processes,
implemented through a collection of libraries in several languages.
+
From the programmer's point of view, Ivy is an information broadcasting
channel. The main functions are:
-- connecting to a bus. Example: IvyInit (b, 2011)
+
- connecting to a bus. Example: IvyInit (b, "192.126:2011")
- sending a message. Example: IvySend (b, "HELLO %s", world)
- bind a message pattern to a callback function. Example: IvyBind (b, "HELLO (.*)", cb)
- the main loop. Example : IvyLoop ()
+Ivy's
+decentralised connection scheme probably incurs limitations in terms of how many
+applications can be connected to an Ivy bus, but this simplifies management a
+lot. Basically, an Ivy bus is just a set of applications that decide to
+communicate together. The only conventions between these applications are:
+
+- the use of the Ivy protocol (for obvious reasons)
+
- a bus address, made of a broadcast port number (a bit like a citizen band
+channel) and a set of networks addresses
+
+When an application wants to connect to a bus, it sends a broadcast message on the
+networks specified in the bus address, so that all applications present on those
+networks and listening on the specified port number connect to it. It then
+becomes part of the bus, and listens like the other ones.
The messages are exchanged in text format, and bindings are based on regular
expressions with captures. If an application subscribes to
@@ -71,6 +86,15 @@ callback will be called in the first application with Using Ivy
+You can use Ivy through applications that have been provided to you. This is the
+case for
Libraries that implement Ivy are available in the following environments:
- in C on Unix and Windows platforms, with it own communication library
@@ -83,21 +107,197 @@ Libraries that implement Ivy are available in the following environments:
- in Scheme on Unix platforms
- in Java
+
+Connecting your application to an Ivy bus just consists in choosing the
+appropriate library, add the appropriate message emission and reception calls to
+your code, use the main loop provided in the library or make the necessary
+integrations, and get your code running!
The Ivy C library
The Ivy C library (aka Ivy-C or ivy-c) is a C library that allows you to connect
applications to an Ivy bus. You can use it to write applications in C or any
-other language that supports C extensions.
-
+other language that supports C extensions. This guide documents how you can do
+that.
+
+The Ivy C library is known to compile and work in WindowsNT and Linux
+environments. It should be easy to use on most Posix environments.
+
+The Ivy C library was originally developed by François-Régis Colin at CENA. It
+is maintained by the CENA-Toulouse team.
Getting and installing the Ivy C library
+
+You can get the latest versions of the Ivy C library from CENA (http://XXX) or
+from one of the Fairway sites (for instance http://XXX). Depending whether you
+use a supported distribution of Linux or not, you have the following options:
+
+Installing RedHat or Debian packages
+
+
+Getting and compiling the sources
+
+
+
Basic functions
-Initialization
+
+Initialization and main loop
+
+Initializing an Ivy agent with the Ivy C library is a two step process. First of
+all, you should initialize the library by calling function
+The Ivy C library provides its own main loop:
+void IvyInit (const char* agentname,
+ const char* hello_msg,
+ IvyApplicationCallback app_cb,
+ void *app_data,
+ IvyDieCallback die_cb,
+ void *die_data);
+
+initializes the library. blahblah
+
+
+void IvyStart (const char* bus);
+
+connects your application to the bus specified in
+void IvyMainLoop (void (*hook) (void));
+
+makes your application enter the main loop in which it will handle asynchronous
+communications and signals.
+
+
+void IvyStop ();
+
+makes your application exit the main loop.
+
+
Emitting messages
+
+Emitting a message on an Ivy bus is much like printing a message on the standard
+output. However, do not forget that your message will not be emitted if Ivy has
+not been properly initialized and if you do not have a main loop of some sort
+running. To emit a message, use
+void IvySendMsg (const char* format, ...);
+
+sends a message on the bus. This function has exactly the same behaviour as
+Subscribing to messages
+
+Subscribing to messages consists in binding a callback function to a message
+pattern. Patterns are described by regular expressions with captures. When a
+message matching the regular expression is detected on the bus, the callback
+function is called. The captures (ie the bits of the message that match the
+parts of regular expression delimited by brackets) are passed to the callback
+function much like options are passed to
+MsgRcvPtr IvyBindMsg (MsgCallback cb,
+ void* data,
+ const char* regex_format, ...);
+
+binds callback function
+void IvyUnbindMsg (MsgRcvPtr id);
+
+deletes the binding specified by
+In what precedes,
+typedef void (*MsgCallback)(IvyClientPtr app, void *data, int argc, char **argv);
+
+
+
+Example
+
+The following application connects to an Ivy bus, translates messages
+#include
+#include
+#include
+#include
+#include
+
+/* callback associated to "Hi" messages */
+void HiCallback (IvyClientPtr app, void *data, int argc, char **argv)
+{
+ if (argc != 1)
+ fprintf (stderr, "wrong format!\n");
+ else
+ IvySendMsg ("Bonjour %s", argv[0]);
+}
+
+void ByeCallback (IvyClientPtr app, void *data, int argc, char **argv)
+{
+ IvyStop ();
+}
+
+main (int argc, char**argv)
+{
+ /* handling of -b option */
+ const char* bus = 0;
+ char c;
+ while (c = getopt (argc, argv, "b:") != EOF) {
+ switch (c) {
+ case 'b':
+ bus = optarg;
+ break;
+ }
+ }
+
+ /* handling of environment variable */
+ if (!bus)
+ bus = getenv ("IVYBUS");
+
+ /* initializations */
+ IvyInit ("MagicTranslater", "Hello le monde", 0, 0, 0, 0);
+ IvyStart (bus);
+
+ /* bindings */
+ IvyBindMsg (HiCallback, 0, "^Hi (.*)");
+ IvyBindMsg (ByeCallback, 0, "^Bye$");
+
+ /* main loop */
+ IvyMainLoop (0);
+}
+
+
+
+
+
+
+Advanced functions
+Utilities
+Direct messages
Managing timers and other channels
@@ -129,7 +329,7 @@ void IvyChannelClose (Channel ch);
terminates the management of channel
-In what precedes,