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.
+
+
Architecture and principles
+
+
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: Ivy::start (-loopMode =>
+ 'local', -ivyBus => '2011', -appName => "toto" );
+
sending a message. Example: Ivy::sendMsgs ("HELLO WORLD")
+
bind a message pattern to a callback function. Example:
+ Ivy::bindRegexp ("^HELLO (.*)", [\&cb])
+
the main loop. MainLoop
+
+
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
+HELLO (.*) and if another application emits the message HELLO WORLD, a
+callback will be called in the first application with WORLD as an argument.
+
+
+
Using Ivy
+
+
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:
+
+
in C on Unix and Windows platforms, with its own communication library
+
in C++ on Windows platforms
+
in C++ on Unix platforms, integrated with the Uch communication library
+
in C++ on Unix platforms, integrated with OpenInventor
+
in C++ on Macintosh
+
in Perl and in Perl/Tk
+
integrated with Object Caml on Unix platforms
+
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 Perl library (aka Ivy-Perl or ivy-perl) is a Perl library that allows you to connect
+applications to an Ivy bus. You can use it to write applications in Perl or any
+other language that supports Perl extensions (Perl/Tk for instance). This guide documents how you can do
+that.
+
The Ivy Perl library is known to compile and work in WindowsNT and Linux
+environments. It should be easy to use on most Posix environments.
+
The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It
+is maintained by the CENA-Toulouse team.
+
+
+Next
+Previous
+Contents
+
+
diff --git a/doc/ivy-perl-2.html b/doc/ivy-perl-2.html
new file mode 100644
index 0000000..50b58ff
--- /dev/null
+++ b/doc/ivy-perl-2.html
@@ -0,0 +1,44 @@
+
+
+
+
+ The Ivy C library guide: Getting and installing the Ivy Perl library
+
+
+
+
+
+Next
+Previous
+Contents
+
+
You can get the latest versions of the Ivy Perl 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 not a Linux one, you have to get and install the source of ivy-perl.
+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-Perl library is done by calling function Ivy::start. 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 Perl library provides two kind of main loop: a "local" loop
+ for perl code, and a "Tk" loop for perl-tk code.
+
+
+initializes and connects your application to the bus specified in ivyBus. The string provided
+should follow the convention described in section XX. Example: "127:2010"..
+
+
+
+
+MainLoop;
+
+
+
+makes your application enter the main loop in which it will handle asynchronous
+communications and signals.
+
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:
+
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 Ivy::bindRegexp
+to bind a callback to a pattern.
+
+
+Ivy::bindRegexp ("^HELLO WORLD", [\&Start]);
+
+
+
+binds callback function Start to the regular expression specified by
+regex_format.
+
+Next
+Previous
+Contents
+
+
diff --git a/doc/ivy-perl.1 b/doc/ivy-perl.1
new file mode 100644
index 0000000..265354c
--- /dev/null
+++ b/doc/ivy-perl.1
@@ -0,0 +1,91 @@
+'\"
+'\" Ivy, Perl interface \- library managing connexions to a software bus
+'\"
+'\" Copyright (C) 1997-1999
+'\" Centre d'Études de la Navigation Aérienne
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\"
+'\" # Start an argument description
+.de AP
+.ie !"\\$4"" .TP \\$4
+.el \{\
+. ie !"\\$2"" .TP \\n()Cu
+. el .TP 15
+.\}
+.ie !"\\$3"" \{\
+.ta \\n()Au \\n()Bu
+\&\\$1 \\fI\\$2\\fP (\\$3)
+.\".b
+.\}
+.el \{\
+.br
+.ie !"\\$2"" \{\
+\&\\$1 \\fI\\$2\\fP
+.\}
+.el \{\
+\&\\fI\\$1\\fP
+.\}
+.\}
+..
+'\" # define tabbing values for .AP
+.de AS
+.nr )A 10n
+.if !"\\$1"" .nr )A \\w'\\$1'u+3n
+.nr )B \\n()Au+15n
+.\"
+.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
+.nr )C \\n()Bu+\\w'(in/out)'u+2n
+..
+'\" # BS - start boxed text
+'\" # ^y = starting y location
+'\" # ^b = 1
+.TH Ivy-Perl-3.0 1 3.0 "Ivy-Perl-3.0 Interface"
+.SH NAME
+ivy-perl - a software bus library
+.SH SYNOPSIS
+Ivy-perl provides a useful set of Perl library functions for communicating between different
+processes through a software bus
+.SH DESCRIPTION
+Ivy is a software bus, ie a system that allows any software component to freely exchange data.
+The basic principle of a software bus is to ease the rapid implementation of new agents, and to manage a dynamic collection of agents on the bus: agents connect, send and receive messages, and disconnect without perturbing the overall functionment of the bus.
+Each time an application initializes a connection on the bus, a
+"ready" message is sent to all other applications already connected, and the
+list of the messages subscribed by this application is dispatched.
+The format for the messages is free.
+.nf
+The essential functions of Ivy are:
+.nf
+.I Connexion
+.nf
+.I Message sending
+.nf
+.I Message subscription
+.nf
+.I Main loop
+
+.SH FILES
+.I /usr/lib/perl5/site_perl/Ivy.pm
+.SH ENVIRONMENT
+.I IVYBUS
+.nf
+.I IVYDOMAINS
+.SH DIAGNOSTICS
+error messages displayed
+.SH BUGS
+none reported yet!
+.SH AUTHORS
+.nf
+Alexandre Bustico
+.nf
+Stephane Chatty
+.SH SEE ALSO
+ivy-c (1)
+.sp
+For further details, please refer to the Ivy html page at http://www.cenatls.cena.dgac.fr/pii/produits/Ivy.html
+.SH NOTES
+In case of any comment or bug report on this library, please contact
+bustico@cenatoulouse.dgac.fr, chatty@cenatoulouse.dgac.fr, jacomi@cenatoulouse.dgac.fr
+
diff --git a/doc/ivy-perl.html b/doc/ivy-perl.html
new file mode 100644
index 0000000..006ae35
--- /dev/null
+++ b/doc/ivy-perl.html
@@ -0,0 +1,64 @@
+
+
+
+
+ The Ivy Perl library guide
+
+
+
+
+
+Next
+Previous
+Contents
+
+
The Ivy Perl library guide
+
+
Stéphane Chatty, chatty@cena.dgac.fr
13 April 1999
+
+This document is a programmer's guide that describes how to use the Ivy Perl
+library to connect applications to an Ivy bus. This guide describes version 3.0
+of the library.
+
+