path: root/doc/ivy-perl.sgml

<!--
	The Ivy Perl library guide

	Copyright (c) 1999-2000
	Centre d'Etudes de la Navigation Aerienne

	SGML source file

	Authors: Stéphane Chatty <chatty@cena.dgac.fr>

	$Id$

	Please refer to file Ivy.pm for the
	copyright notice regarding this software
-->

<!-- -------------------------------------------------------------------------------
      This file was rebuilt from html files after the disappearance of the
      original sgml file. It is not yet syntactically valid, and documents an
      old version of Ivy Perl.
  ------------------------------------------------------------------------------- -->

<?xml version='1.0' ?>
<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<article>
<artheader>

<title>The Ivy Perl library guide</title>

<authorgroup>
<author>
<firstname>Stéphane</firstname><surname>Chatty</surname>
<affiliation><address><email>chatty@cena.fr</email></address></affiliation>
</author>
</authorgroup>
<date>April 13, 1999</date>

<copyright>
<year>1999</year>
<holder>Centre d'Études de la Navigation Aérienne</holder>
</copyright>

<abstract>
<para>
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.
</para>
</abstract>
</artheader>

<sect1>
<title>Foreword</title>

<para>
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.
</para>
</sect1>


<sect1>
<title>What is Ivy?</title>
<para>
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.
</para>


<sect2>
<title>Architecture and principles</title>

<para>
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.
</para>

<para>
From the programmer's point of view, Ivy is an information broadcasting
channel. The main functions are:

<UL>
<LI> connecting to a bus.<EM> Example: Ivy::start (-loopMode =>
	  'local', -ivyBus => '2011', -appName => "toto" );</EM></LI>
<LI> sending a message.<EM> Example: Ivy::sendMsgs ("HELLO WORLD")</EM></LI>
<LI> bind a message pattern to a callback function.<EM> Example:
	  Ivy::bindRegexp ("^HELLO (.*)", [\&cb])</EM></LI>
<LI> the main loop.<EM> MainLoop</EM></LI>
</UL>
</para>

<para>
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:
<OL>
<LI> the use of the Ivy protocol (for obvious reasons)</LI>
<LI> a bus address, made of a broadcast port number (a bit like a citizen band
channel) and a set of networks addresses</LI>
</OL>
</para>

<para>
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.
</para>

<para>
The messages are exchanged in text format, and bindings are based on regular
expressions with captures. If an application subscribes to 
<CODE>HELLO (.*)</CODE> and if another application emits the message <CODE>HELLO WORLD</CODE>, a
callback will be called in the first application with <CODE>WORLD</CODE> as an argument.
</para>

</sect2>

<sect2>
<title>Using Ivy</title>
<para>
You can use Ivy through applications that have been provided to you. This is the
case for <CODE>ivyprobe</CODE>, 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 <CODE>http://www.tls.cena.fr/products/ivy/</CODE> 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.
</para>

<para>
Libraries that implement Ivy are available in the following environments:
<UL>
<LI> in C on Unix and Windows platforms, with its own communication library</LI>
<LI> in C++ on Windows platforms</LI>
<LI> in C++ on Unix platforms, integrated with the Uch communication library</LI>
<LI> in C++ on Unix platforms, integrated with  OpenInventor</LI>
<LI> in C++ on Macintosh</LI>
<LI> in Perl and in Perl/Tk</LI>
<LI> integrated with Object Caml on Unix platforms</LI>
<LI> in Scheme on Unix platforms</LI>
<LI> in Java</LI>
</UL>
</para>

<para>
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! 
</para>
</sect1>

<sect1>
<title>The Ivy Perl library</title>

<sect2>
<title>What is it?</title>

<para>
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.
</para>

<para>
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. 
</para>

<para>
The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It
is maintained by the CENA-Toulouse team.
</para>



<sect2>
<title>Getting and installing the Ivy Perl library</title>

<para>
You can get the latest versions of the Ivy C library from CENA
(<ulink URL="http://www.tls.cena.fr/products/ivy/">http://www.tls.cena.fr/products/ivy/</ulink>). 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 <em><strong> rpm -i package-name</strong></em>.
If your system is Linux/Debian, you have to use the command <em><strong> dpkg -i package-name</strong></em>.
</para>
</sect2>
</sect1>

<sect1>
<title>Basic functions</title>

<sect2>
<title>Initialization and main loop</title>

<para>
Initializing an Ivy agent with the Ivy-Perl library is done by calling function
<CODE>Ivy::start</CODE>. 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.
</para>

<para>
The Ivy Perl library provides two kind of main loop: a "LOCAL" loop 
      for perl code, and a "TK" loop for perl-Tk code.
</para>

<para>
Here is more details on <CODE>Ivy::start</CODE> function:

<programlisting>
  Ivy::start(-loopMode =&gt; 'TK', 
             -ivyBus =&gt; '2011', 
             -appName =&gt; "TOTO",
             -neededApp =&gt; "TITI",
             -statusFunc    =&gt; \&amp;statusScan);
</programlisting>

initializes and connects your application to the bus specified in
<CODE>ivyBus</CODE>. The string provided should follow the convention described
in section XX. Example: <CODE>"127:2010"</CODE>..
</para>

<para>
<programlisting>
MainLoop;
</programlisting>

makes your application enter the main loop in which it will handle asynchronous
communications and signals.
</para>

<para>
<programlisting>
Ivy::stop ();
</programlisting>

makes your application exit the main loop.
</para>

<sect2>
<title>Emitting messages</title>

<para>
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 <CODE>IvySendMsg</CODE>, which works like
<CODE>printf</CODE>:
</para>

<para>
<programlisting>
Ivy::sendMsg ("...");
</programlisting>

sends a message on the bus.
</para>


<sect2>
<title>Subscribing to messages</title>

<para>
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 <CODE>main</CODE>. Use function
<CODE>Ivy::bindRegexp</CODE> to bind a callback to a pattern.

<programlisting>
Ivy::bindRegexp ("^HELLO WORLD", [\&amp;Start]);
</programlisting>

binds callback function <CODE>Start</CODE> to the regular expression specified by
<CODE>regex_format</CODE>.
</para>

<para>
<programlisting>
Ivy::bindRegexp ("^HELLO WORLD", NULL);
<programlisting>

deletes the binding.
</para>

</sect1>

<sect1>
<title>Advanced functions</title>

<sect2>
<title>Utilities</title>
</sect2>

<sect2>
<title>Direct messages</title>
</sect2>

</sect1>

<sect1>
<title>Managing timers and other channels</title>
</sect1>

<sect1>
<title>Conventions for writing applications</title>

<sect2>
<title>Default bus</title>
<para>
By default, the bus used is <em><strong>127.255.255.255:2010 </em></strong> ie
the application will be connected on the port 2010 of the local machine it runs
on.
</para>

<para>
You can set the bus to be used by setting the environment variable
<CODE>IVYBUS</CODE> or by implementing the option <CODE>-b</CODE> in the
application.
</para>

<sect2>
<title>Syntax of messages</title>
<para>
The syntax of the messages exchanged is totally free. However, the following
convention is recommended:
<menu>
<li>The message syntax is <CODE>Subject Attributes</CODE></li>
<li>A Subject is an object, named in a hierarchical form: <CODE>ObjectClass1:object1.ObjectClass2:object2...</CODE></li>
<li>Attributes are pairs <CODE>(attribute-name, value)</CODE></li>
</menu>
</para>

<para>
Example:

<programlisting>
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
</programlisting>
</para>

</sect1>

<sect1>
<title>Known bugs</title>
<para>
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)
</para>
</sect1>
</article>