-
Ivy is a software bus designed at CENA (France). A software bus is a system -that allows software applications to exchange information with the illusion of -broadcasting that information, selection being performed by the receiving -applications. Using a software bus is very similar to dealing with events in a -graphical toolkit: on one side, messages are emitted without caring about who -will handle them, and on the other side, one decide to handle the messages that -have a certain type or follow a certain pattern. Software buses are mainly aimed -at facilitating the rapid development of new agents, and at managing a dynamic -collection of agents on the bus: agents show up, emit messages and receive some, -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: -
-
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 messages are exchanged in text format, and bindings are based on regular
-expressions with captures. If an application subscribes to
-HELLO (.*) and if another application emits the message HELLO WORLD, a
-callback will be called in the first application with WORLD as an argument.
-
-
-
You can use Ivy through applications that have been provided to you. This is the
-case for ivyprobe, an Ivy agent that allows you to examine the messages
-exchanged on a given bus and to send messages on that bus. You can refer to the
-web site http: for a list of available agents. However, what you will
-usually want to do is to develop your own applications. In order to do that you
-can use an Ivy connection kit, that is a library that implements Ivy.
-
-
-
Libraries that implement Ivy are available in the following environments: -
-
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 (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. 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. -
-
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: -
-
If your system is Linux/Redhat, you have to use the command rpm -i package-name. -
If your system is Linux/Debian, you have to use the command dpkg -i package-name. - - -
-
-
If your system is not a Linux one, you have to get and compile the source of the ivy-c library. -In this case, you have to get the source from CENA at http://XXX or from one of the Fairway sites. - - -
-
-
-
-
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 IvyInit. Once
-the library is initialized you can create timers and add subscriptions, but your
-agent is still not connected to any bus. In order to connect, you should call
-function IvyStart. In theory, initialization is then over. However in
-practice, as for any asynchronous communication or interaction library, nothing
-happens until your application has reached the main loop.
-
The Ivy C library provides its own main loop: IvyMainLoop. You should use
-it unless you already use a toolkit that provides its own main loop and you want
-to use that one. If it is the case, please refer to section XX. Otherwise, just
-call IvyMainLoop. From within the main loop, you can call IvyStop to
-exit the loop.
-
Here are more details on those functions: -
-
-
-void IvyInit (const char* agentname,
- const char* hello_msg,
- IvyApplicationCallback app_cb,
- void *app_data,
- IvyDieCallback die_cb,
- void *die_data);
-
--
-
-void IvyStart (const char* bus);
-
-bus. The string provided
-should follow the convention described in section XX. Example: "127:2010".
--
-
-void IvyMainLoop (void (*hook) (void));
-
--
-
-void IvyStop ();
-
--
-
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 IvySendMsg, which works like printf:
-
-
-
-void IvySendMsg (const char* format, ...);
-
-printf, sprintf or fprintf.
--
-
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 main. Use function IvyBindMsg
-to bind a callback to a pattern, and function IvyUnbindMsg to delete the
-binding.
-
-
-MsgRcvPtr IvyBindMsg (MsgCallback cb,
- void* data,
- const char* regex_format, ...);
-
-cb to the regular expression specified by
-regex_format and the optional following arguments. regex_format and
-the following arguments are handled as in printf.
--
-
-void IvyUnbindMsg (MsgRcvPtr id);
-
-id
--
In what precedes, MsgRcvPtr is an opaque type used to identify bindings,
-data is a user pointer passed to the callback whenever it is called, and
-Msgcallback is defined as follows:
-
-
-typedef void (*MsgCallback)(IvyClientPtr app, void *data, int argc, char **argv);
-
--
-
The following application connects to an Ivy bus, translates messages "Hi
-[name]" to "Bonjour [name]", and quits on message "Bye".
-
-
-#include <stdlib.h>
-#include <stdio.h>
-#include <getopt.h>
-#include <ivy.h>
-#include <ivyloop.h>
-
-/* 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);
-}
-
--
-
-
-
-
In your applications, you may need to manage other input/output channels than an -Ivy bus: a serial driver, the channels defined by a graphical toolkit, or simply -stdin and stdout. The same applies for timers. You can either manage those -channels or timers from the Ivy main loop, or instead use the main loop provided by -another library. -
-
You can get a channel to be managed from the Ivy main loop by using functions
-IvyChannelSetUp and IvyChannelClose.
-
-
-Channel IvyChannelSetUp (HANDLE fd,
- void* data,
- ChannelHandleDelete handle_delete,
- ChannelHandleRead handle_read);
-
-handle_read is called whenever data is read on file
-descriptor fd, and function handle_delete whenever fd is
-closed, and
--
-
-void IvyChannelClose (Channel ch);
-
-ch.
--
In what precedes, Channel is an opaque type defined by the Ivy C library, data is a pointer that will be passed to functions handle_read
-and handle_delete. It can be defined at will by users.
-The types HANDLE, ChannelHandleDelete and
-ChannelHandleRead are as follows:
-
-Unix:
-
-typedef int HANDLE;
-
-
-Windows:
-
-typedef SOCKET HANDLE;
-
-
-
-typedef void (*ChannelHandleDelete)(void *data);
-typedef void (*ChannelHandleRead)(Channel ch, HANDLE fd, void* data);
-
--
-
You can get a function to be repeatedly called by using function
-TimerRepeatAfter:
-
-
-
-TimerId TimerRepeatAfter (int nbticks, long delay, TimerCb handle_timer, void* data);
-
-handle_timer is called nbticks times at
-intervals of delay seconds, thus creating a timer.
--
-
-void TimerModify (TimerId id, long delay);
-
-id.
--
-
-void TimerRemove (TimerId id);
-
-id, thus stopping it.
-In what precedes, data is passed to handle_timer every time it is
-called. delay is expressed in milliseconds.
-If nbticks is set to TIMER_LOOP, then handle_timer will
-be called forever. TimerCb is as follows:
-
-
-typedef void (*TimerCb)(TimerId id, void *data, unsigned long delta);
-
--
-
You can decide to use the main loop from another toolkit such as the X Toolkit -or the Tk toolkit. If you do that, you'll have to define three functions that -Ivy will use to get its own channels managed by the other toolkit. The three -following global variables should be defined: -
-
-ChannelInit channel_init;
-ChannelSetUp channel_setup;
-ChannelClose channel_close;
-
-They should point to functions that respectively: -
-
The types ChannelInit, ChannelSetUp and ChannelClose are defined
-as follows:
-
-
-
-typedef void (*ChannelInit)(void);
-typedef Channel (*ChannelSetUp)(
- HANDLE fd,
- void *data,
- ChannelHandleDelete handle_delete,
- ChannelHandleRead handle_read);
-typedef void (*ChannelClose)( Channel channel );
-
--
-
In order to implement the three previous functions, you will need to define the
-hidden type struct _channel (the type Channel is defined as struct _channel*). Use it to store the data provided by the other toolkit.
-
-
In order to override the default definition of the three previous variables, you -will need: -
ivyloop.o with the file
-that contains your definitions-
-
-
-
-
-
You can set the bus to be used by setting the environment variable IVYBUS or by implementing the option -b in the application.
-
By convention, the message application-name READY is to be used when initializing the connexion to ivy. -
Example: -
IvyInit ("TOTO", "TOTO READY",...)
-
AIRCRAFT:LIB720 Moved lat=46.1697 lon=2.0844 vx=-36 vy=-463 afl=330 rate=0 heading=184 ground_speed=465
-mach_speed=0 tendance=0 time=24600 cfl=330
-
chatty@cena.dgac.fr-
-
-
-
-
-
-For further details, please refer to the Ivy html page at http://www.cenatls.cena.dgac.fr/pii/produits/Ivy.html -