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
deleted file mode 100644
index 50b58ff..0000000
--- a/doc/ivy-perl-2.html
+++ /dev/null
@@ -1,44 +0,0 @@
-
-
-
-
- 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.
-
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.
-
-
-
-Next
-Previous
-Contents
-
-
diff --git a/doc/ivy-perl.sgml b/doc/ivy-perl.sgml
new file mode 100644
index 0000000..31b39f5
--- /dev/null
+++ b/doc/ivy-perl.sgml
@@ -0,0 +1,377 @@
+
+
+
+
+
+
+
+
+
+
+The Ivy Perl library guide
+
+
+
+StéphaneChatty
+chatty@cena.fr
+
+
+April 13, 1999
+
+
+1999
+Centre d'Études de la Navigation Aérienne
+
+
+
+
+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. The Ivy Perl library was mainly written by Alexandre Bustico
+from CENA, but this documentation is maintained by users of the library.
+
+
+
+
+
+Foreword
+
+
+This document was written in SGML according to the DocBook DTD, so as to be able to
+generate PDF and html output. However, the authors have not yet mastered the
+intricacies of SGML, the DocBook DTD, the DocBook Stylesheets and the related
+tools, which have achieved the glorious feat of being far more complex than
+LaTeX and Microsoft Word combined together. This explains why this document, in addition
+to being incomplete, is so ugly. We'll try and improve it.
+
+
+
+
+
+What is Ivy?
+
+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://www.tls.cena.fr/products/ivy/ 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
+
+
+What is it?
+
+
+The Ivy Perl library (aka Perl-Net-Ivy 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.
+
+
+
+
+
+Getting and installing the Ivy Perl library
+
+
+You can get the latest versions of the Ivy C library from CENA
+(http://www.tls.cena.fr/products/ivy/). Depending
+on whether you use a supported binary distribution, you can retrieve RPM
+or Debian packages for Linux (do not forget to get the development package as
+well as the run-time package), or retrieve the source files and install them by hand.
+If your packages are Linux/RPM, 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.
+
+
+
+
+
+Basic functions
+
+
+Initialization and main loop
+
+
+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.
+
+
+
+Here is more details on Ivy::start function:
+
+
+ Ivy::start(-loopMode => 'TK',
+ -ivyBus => '2011',
+ -appName => "TOTO",
+ -neededApp => "TITI",
+ -statusFunc => \&statusScan);
+
+
+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.
+
+
+
+
+Ivy::stop ();
+
+
+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 IvySendMsg, which works like
+printf:
+
+
+
+
+Ivy::sendMsg ("...");
+
+
+sends a message on the bus.
+
+
+
+
+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 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.
+
+
+
+
+Ivy::bindRegexp ("^HELLO WORLD", NULL);
+
+
+deletes the binding.
+
+
+
+
+
+Advanced functions
+
+
+Utilities
+
+
+
+Direct messages
+
+
+
+
+
+Managing timers and other channels
+
+
+
+Conventions for writing applications
+
+
+Default bus
+
+By default, the bus used is 127.255.255.255:2010 ie
+the application will be connected on the port 2010 of the local machine it runs
+on.
+
+
+
+You can set the bus to be used by setting the environment variable
+IVYBUS or by implementing the option -b in the
+application.
+
+
+
+Syntax of messages
+
+The syntax of the messages exchanged is totally free. However, the following
+convention is recommended:
+
+
+
+
+Example:
+
+
+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
+
+
+
+
+
+
+Known bugs
+
+Version 3 is only compatible with perl-tk 402-004.
+It does not work with perl-tk 400.202 (fileId event problem)
+It does not work with perl-tk_800.011 (remove file descriptor problem)
+
+
+
+
--
cgit v1.1