diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ivy-perl-1.html | 116 | ||||
-rw-r--r-- | doc/ivy-perl-2.html | 44 | ||||
-rw-r--r-- | doc/ivy-perl-3.html | 111 | ||||
-rw-r--r-- | doc/ivy-perl-4.html | 28 | ||||
-rw-r--r-- | doc/ivy-perl-5.html | 23 | ||||
-rw-r--r-- | doc/ivy-perl-6.html | 34 | ||||
-rw-r--r-- | doc/ivy-perl.1 | 91 | ||||
-rw-r--r-- | doc/ivy-perl.html | 64 |
8 files changed, 511 insertions, 0 deletions
diff --git a/doc/ivy-perl-1.html b/doc/ivy-perl-1.html new file mode 100644 index 0000000..b6b2c92 --- /dev/null +++ b/doc/ivy-perl-1.html @@ -0,0 +1,116 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy Perl library guide: General information</TITLE> + <LINK HREF="ivy-perl-2.html" REL=next> + + <LINK HREF="ivy-perl.html#toc1" REL=contents> +</HEAD> +<BODY> +<A HREF="ivy-perl-2.html">Next</A> +Previous +<A HREF="ivy-perl.html#toc1">Contents</A> +<HR> +<H2><A NAME="s1">1. General information</A></H2> + +<H2><A NAME="ss1.1">1.1 What is Ivy?</A> +</H2> + +<P> +<P>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. +<P> +<H3>Architecture and principles</H3> + +<P>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. +<P> +<P> +<P>From the programmer's point of view, Ivy is an information broadcasting +channel. The main functions are: +<P> +<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> +<P>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> + +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. +<P>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. +<P> +<P> +<H3>Using Ivy</H3> + +<P>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:</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. +<P> +<P> +<P>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> +<P> +<P>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! +<P> +<H2><A NAME="ss1.2">1.2 The Ivy Perl library</A> +</H2> + +<P>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. +<P>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. +<P>The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It +is maintained by the CENA-Toulouse team. +<P> +<HR> +<A HREF="ivy-perl-2.html">Next</A> +Previous +<A HREF="ivy-perl.html#toc1">Contents</A> +</BODY> +</HTML> 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy C library guide: Getting and installing the Ivy Perl library</TITLE> + <LINK HREF="ivy-perl-3.html" REL=next> + <LINK HREF="ivy-perl-1.html" REL=previous> + <LINK HREF="ivy-perl.html#toc2" REL=contents> +</HEAD> +<BODY> +<A HREF="ivy-perl-3.html">Next</A> +<A HREF="ivy-perl-1.html">Previous</A> +<A HREF="ivy-perl.html#toc2">Contents</A> +<HR> +<H2><A NAME="s2">2. Getting and installing the Ivy Perl library</A></H2> + +<P>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: +<P> +<H2><A NAME="ss2.1">2.1 Installing RedHat or Debian packages</A> +</H2> +<p>If your system is Linux/Redhat, you have to use the command <em><strong> rpm -i package-name</strong></em>. +<p>If your system is Linux/Debian, you have to use the command <em><strong> dpkg -i package-name</strong></em>. + + +<P> +<P> +<H2><A NAME="ss2.2">2.2 Getting and installing the sources</A> +</H2> +<p>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. + + +<P> +<P> +<P> +<P> +<HR> +<A HREF="ivy-perl-3.html">Next</A> +<A HREF="ivy-perl-1.html">Previous</A> +<A HREF="ivy-perl.html#toc2">Contents</A> +</BODY> +</HTML> diff --git a/doc/ivy-perl-3.html b/doc/ivy-perl-3.html new file mode 100644 index 0000000..bee7734 --- /dev/null +++ b/doc/ivy-perl-3.html @@ -0,0 +1,111 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy C library guide: Basic functions</TITLE> + <LINK HREF="ivy-perl-4.html" REL=next> + <LINK HREF="ivy-perl-2.html" REL=previous> + <LINK HREF="ivy-perl.html#toc3" REL=contents> +</HEAD> +<BODY> +<A HREF="ivy-perl-4.html">Next</A> +<A HREF="ivy-perl-2.html">Previous</A> +<A HREF="ivy-perl.html#toc3">Contents</A> +<HR> +<H2><A NAME="s3">3. Basic functions</A></H2> + +<H2><A NAME="ss3.1">3.1 Initialization and main loop</A> +</H2> + +<P>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. +<P>The Ivy Perl library provides two kind of main loop: a "local" loop + for perl code, and a "Tk" loop for perl-tk code. +<P>Here is more details on <CODE>Ivy::start</CODE> function: +<P> +<BLOCKQUOTE><CODE> +<PRE> + Ivy::start(-loopMode => 'TK', + -ivyBus => '2011', + -appName => "TOTO", + -neededApp => "TITI", + -statusFunc => \&statusScan); + +</PRE> +</CODE></BLOCKQUOTE> + +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>.. +<P> + +<BLOCKQUOTE><CODE> +<PRE> +MainLoop; +</PRE> +</CODE></BLOCKQUOTE> + +makes your application enter the main loop in which it will handle asynchronous +communications and signals. +<P> +<BLOCKQUOTE><CODE> +<PRE> +Ivy::stop (); +</PRE> +</CODE></BLOCKQUOTE> + +makes your application exit the main loop. +<P> +<P> +<H2><A NAME="ss3.2">3.2 Emitting messages</A> +</H2> + +<P>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>: +<P> +<BLOCKQUOTE><CODE> +<PRE> +Ivy::sendMsg ("..."); +</PRE> +</CODE></BLOCKQUOTE> + +sends a message on the bus. +<P> +<P> +<H2><A NAME="ss3.3">3.3 Subscribing to messages</A> +</H2> + +<P>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. +<BLOCKQUOTE><CODE> +<PRE> +Ivy::bindRegexp ("^HELLO WORLD", [\&Start]); +</PRE> +</CODE></BLOCKQUOTE> + +binds callback function <CODE>Start</CODE> to the regular expression specified by +<CODE>regex_format</CODE>. +<P> +<BLOCKQUOTE><CODE> +<PRE> +Ivy::bindRegexp ("^HELLO WORLD", NULL); +</PRE> +</CODE></BLOCKQUOTE> + +deletes the binding. +<P> +<P> +<P> +<HR> +<A HREF="ivy-perl-4.html">Next</A> +<A HREF="ivy-perl-2.html">Previous</A> +<A HREF="ivy-perl.html#toc3">Contents</A> +</BODY> +</HTML> diff --git a/doc/ivy-perl-4.html b/doc/ivy-perl-4.html new file mode 100644 index 0000000..88719cc --- /dev/null +++ b/doc/ivy-perl-4.html @@ -0,0 +1,28 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy C library guide: Advanced functions</TITLE> + <LINK HREF="ivy-perl-5.html" REL=next> + <LINK HREF="ivy-perl-3.html" REL=previous> + <LINK HREF="ivy-perl.html#toc4" REL=contents> +</HEAD> +<BODY> +<A HREF="ivy-perl-5.html">Next</A> +<A HREF="ivy-perl-3.html">Previous</A> +<A HREF="ivy-perl.html#toc4">Contents</A> +<HR> +<H2><A NAME="s4">4. Advanced functions</A></H2> + +<H2><A NAME="ss4.1">4.1 Utilities</A> +</H2> + +<H2><A NAME="ss4.2">4.2 Direct messages</A> +</H2> + +<HR> +<A HREF="ivy-perl-5.html">Next</A> +<A HREF="ivy-perl-3.html">Previous</A> +<A HREF="ivy-perl.html#toc4">Contents</A> +</BODY> +</HTML> diff --git a/doc/ivy-perl-5.html b/doc/ivy-perl-5.html new file mode 100644 index 0000000..96276ea --- /dev/null +++ b/doc/ivy-perl-5.html @@ -0,0 +1,23 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy C library guide: Managing timers and other channels</TITLE> + <LINK HREF="ivy-perl-6.html" REL=next> + <LINK HREF="ivy-perl-4.html" REL=previous> + <LINK HREF="ivy-perl.html#toc5" REL=contents> +</HEAD> +<BODY> +<A HREF="ivy-perl-6.html">Next</A> +<A HREF="ivy-perl-4.html">Previous</A> +<A HREF="ivy-perl.html#toc5">Contents</A> +<HR> +<H2><A NAME="s5">5. Managing timers and other channels</A></H2> + +<P> +<HR> +<A HREF="ivy-perl-6.html">Next</A> +<A HREF="ivy-perl-4.html">Previous</A> +<A HREF="ivy-perl.html#toc5">Contents</A> +</BODY> +</HTML> diff --git a/doc/ivy-perl-6.html b/doc/ivy-perl-6.html new file mode 100644 index 0000000..a5ad87b --- /dev/null +++ b/doc/ivy-perl-6.html @@ -0,0 +1,34 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy C library guide: Conventions for writing applications</TITLE> + <LINK HREF="ivy-perl-5.html" REL=previous> + <LINK HREF="ivy-perl.html#toc6" REL=contents> +</HEAD> +<BODY> +Next +<A HREF="ivy-perl-5.html">Previous</A> +<A HREF="ivy-perl.html#toc6">Contents</A> +<HR> +<H2><A NAME="s6">6. Conventions for writing applications</A></H2> +<H3>6.1 Default bus</H3> +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.</p> +<P>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.</P> +<P> +<H3>6.2 Syntax of messages</h3> +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> +Example: +<p><CODE>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</CODE> +<HR> +Next +<A HREF="ivy-perl-5.html">Previous</A> +<A HREF="ivy-perl.html#toc6">Contents</A> +</BODY> +</HTML> 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 <bustico@cenatoulouse.dgac.fr> +.nf +Stephane Chatty <chatty@cenatoulouse.dgac.fr> +.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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> + <TITLE>The Ivy Perl library guide</TITLE> + <LINK HREF="ivy-perl-1.html" REL=next> + + +</HEAD> +<BODY> +<A HREF="ivy-perl-1.html">Next</A> +Previous +Contents +<HR> +<H1>The Ivy Perl library guide</H1> + +<H2>Stéphane Chatty, <CODE>chatty@cena.dgac.fr</CODE></H2>13 April 1999 +<P><HR> +<EM>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.</EM> +<HR> +<P> +<H2><A NAME="toc1">1.</A> <A HREF="ivy-perl-1.html">General information</A></H2> + +<UL> +<LI><A HREF="ivy-perl-1.html#ss1.1">1.1 What is Ivy?</A> +<LI><A HREF="ivy-perl-1.html#ss1.2">1.2 The Ivy Perl library</A> +</UL> +<P> +<H2><A NAME="toc2">2.</A> <A HREF="ivy-perl-2.html">Getting and installing the Ivy Perl library</A></H2> + +<UL> +<LI><A HREF="ivy-perl-2.html#ss2.1">2.1 Installing RedHat or Debian packages</A> +</UL> +<P> +<H2><A NAME="toc3">3.</A> <A HREF="ivy-perl-3.html">Basic functions</A></H2> + +<UL> +<LI><A HREF="ivy-perl-3.html#ss3.1">3.1 Initialization and main loop</A> +<LI><A HREF="ivy-perl-3.html#ss3.2">3.2 Emitting messages</A> +<LI><A HREF="ivy-perl-3.html#ss3.3">3.3 Subscribing to messages</A> +<LI><A HREF="ivy-perl-3.html#ss3.4">3.4 Example</A> +</UL> +<P> +<H2><A NAME="toc4">4.</A> <A HREF="ivy-perl-4.html">Advanced functions</A></H2> + +<UL> +<LI><A HREF="ivy-perl-4.html#ss4.1">4.1 Utilities</A> +<LI><A HREF="ivy-perl-4.html#ss4.2">4.2 Direct messages</A> +</UL> +<P> +<H2><A NAME="toc5">5.</A> <A HREF="ivy-perl-5.html">Managing timers and other channels</A></H2> + + +<P> +<H2><A NAME="toc6">6.</A> <A HREF="ivy-perl-6.html">Conventions for writing applications</A></H2> + +<HR> +<A HREF="ivy-perl-1.html">Next</A> +Previous +Contents +</BODY> +</HTML> |