From f7893eb6c5aaf8f16bf58a2daf9d89bec19b9caf Mon Sep 17 00:00:00 2001 From: sc Date: Fri, 22 Dec 2000 08:52:40 +0000 Subject: Attempt to come back to a normal situation for doc: - source SGML file recreated - generated HTML files removed from archive --- doc/ivy-perl.sgml | 377 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 377 insertions(+) create mode 100644 doc/ivy-perl.sgml (limited to 'doc/ivy-perl.sgml') 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: +
    +
  1. the use of the Ivy protocol (for obvious reasons)
    2. +
  2. a bus address, made of a broadcast port number (a bit like a citizen band +channel) and a set of networks addresses
    3. +
+ + + +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: + +
  • The message syntax is Subject Attributes
    • +
  • A Subject is an object, named in a hierarchical form: ObjectClass1:object1.ObjectClass2:object2...
    • +
  • Attributes are pairs (attribute-name, value)
    • +     +     + + +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