From 3636dcae21d8c851ee16ed91c95747896566220f Mon Sep 17 00:00:00 2001 From: sc Date: Fri, 2 Apr 1999 07:10:03 +0000 Subject: Created the Ivy C library guide. --- doc/ivy-c.sgml | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 doc/ivy-c.sgml (limited to 'doc/ivy-c.sgml') diff --git a/doc/ivy-c.sgml b/doc/ivy-c.sgml new file mode 100644 index 0000000..e51bfec --- /dev/null +++ b/doc/ivy-c.sgml @@ -0,0 +1,235 @@ + + + + + +
+ +The Ivy C library guide +<author>Stéphane Chatty, <tt/chatty@cena.dgac.fr/ +<date>1 April 1999 +<abstract> +This document is a programmer's guide that describes how to use the Ivy C +library to connect applications to an Ivy bus. This guide describes version 3.0 +of the library. +</abstract> + +<toc> + +<sect>General information +<sect1>What is Ivy? +<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. + +<sect2>Architecture and principles +<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> + +From the programmer's point of view, Ivy is an information broadcasting +channel. The main functions are: + +<itemize> +<item> connecting to a bus.<em> Example: IvyInit (b, 2011)</em> +<item> sending a message.<em> Example: IvySend (b, "HELLO %s", world)</em> +<item> bind a message pattern to a callback function.<em> Example: IvyBind (b, "HELLO (.*)", cb)</em> +<item> the main loop.<em> Example : IvyLoop ()</em> +</itemize> + +<p> +The messages are exchanged in text format, and bindings are based on regular +expressions with captures. If an application subscribes to + <tt/HELLO (.*)/ an if another application emits the message <tt/HELLO WORLD/, a +callback will be called in the first application with <tt/WORLD/ as an argument. + + +<sect2>Using Ivy +<p> +Libraries that implement Ivy are available in the following environments: +<itemize> +<item> in C on Unix and Windows platforms, with it own communication library +<item> in C++ on Windows platforms +<item> in C++ on Unix platforms, integrated with the Uch communication library +<item> in C++ on Unix platforms, integrated with OpenInventor +<item> in C++ on Macintosh +<item> in Perl and in Perl/Tk +<item> integrated with Object Caml on Unix platforms +<item> in Scheme on Unix platforms +<item> in Java +</itemize> + + +<sect1>The Ivy C library +<p> +The Ivy C library (aka Ivy-C or ivy-c) is a C library that allows you to connect +applications to an Ivy bus. You can use it to write applications in C or any +other language that supports C extensions. + + +<sect>Getting and installing the Ivy C library + +<sect>Basic functions +<sect1>Initialization +<sect1>Emitting messages +<sect1>Subscribing to messages + +<sect>Managing timers and other channels +<p> + +In your applications, you may need to manage other input/output channels than an +Ivy bus: a serial driver, the channels defined by a graphical toolkit, or simply +stdin and stdout. The same applies for timers. You can either manage those +channels or timers from the Ivy main loop, or instead use the main loop provided by +another library. + +<sect1>Adding channels and timers to the Ivy main loop +<sect2>Channels +<p> +You can get a channel to be managed from the Ivy main loop by using functions +<tt/IvyChannelSetUp/ and <tt/IvyChannelClose/. +<tscreen><verb> +Channel IvyChannelSetUp (HANDLE fd, + void* data, + ChannelHandleDelete handle_delete, + ChannelHandleRead handle_read); +</verb></tscreen> +ensures that function <tt/handle_read/ is called whenever data is read on file +descriptor <tt/fd/, and function <tt/handle_delete/ whenever <tt/fd/ is +closed, and + +<tscreen><verb> +void IvyChannelClose (Channel ch); +</verb></tscreen> +terminates the management of channel <tt/ch/. + +<p> +In what precedes, <tt/data/ is a pointer that will be passed to functions <tt/handle_read/ +and <tt/handle_delete/. It can be defined at will by users. +The types HANDLE, ChannelHandleDelete and +ChannelHandleRead are as follows: +<tscreen>Unix: <verb>typedef int HANDLE;</verb> +Windows: <verb>typedef SOCKET HANDLE;</verb> +<verb> +typedef void (*ChannelHandleDelete)(void *data); +typedef void (*ChannelHandleRead)(Channel ch, HANDLE fd, void* data); +</verb></tscreen> +<p> + +<sect2>Timers +<p> +You can get a function to be repeatedly called by using function +<tt/TimerRepeatAfter/: + +<tscreen><verb> +TimerId TimerRepeatAfter (int nbticks, long delay, TimerCb handle_timer, void* data); +</verb></tscreen> +ensures that function <tt/handle_timer/ is called <tt/nbticks/ times at +intervals of <tt/delay/ seconds, thus creating a timer. + +<tscreen><verb> +void TimerModify (TimerId id, long delay); +</verb></tscreen> +changes the delay used for timer <tt/id/. + +<tscreen><verb> +void TimerRemove (TimerId id); +</verb></tscreen> +deletes timer <tt/id/, thus stopping it. + +In what precedes, <tt/data/ is passed to <tt/handle_timer/ every time it is +called. <tt/delay/ is expressed in milliseconds. +If <tt/nbticks/ is set to <tt/TIMER_LOOP/, then <tt/handle_timer/ will +be called forever. <tt/TimerCb/ is as follows: +<tscreen><verb> +typedef void (*TimerCb)(TimerId id, void *data, unsigned long delta); +</verb></tscreen> + +<p> +<sect1>Adding Ivy to another main loop + +<sect2>Functions to be provided +<p> +You can decide to use the main loop from another toolkit such as the X Toolkit +or the Tk toolkit. If you do that, you'll have to define three functions that +Ivy will use to get its own channels managed by the other toolkit. The three +following global variables should be defined: +<tscreen><verb> +ChannelInit channel_init; +ChannelSetUp channel_setup; +ChannelClose channel_close; +</verb></tscreen> + +They should point to functions that respectively: +<itemize> +<item> make the necessary global initializations before entering the main loop +<item> initialize a channel and ensure that it is managed by the main loop +<item> close a channel +</itemize> +<p> + +The types <tt/ChannelInit/, <tt/ChannelSetUp/ and <tt/ChannelClose/ are defined +as follows: + +<tscreen><verb> +typedef void (*ChannelInit)(void); +typedef Channel (*ChannelSetUp)( + HANDLE fd, + void *data, + ChannelHandleDelete handle_delete, + ChannelHandleRead handle_read); +typedef void (*ChannelClose)( Channel channel ); +</verb></tscreen> + + +<sect2>Type to be defined +<p> +In order to implement the three previous functions, you will need to define the +hidden type <tt/struct _channel/ (the type <tt/Channel/ is defined as <tt/struct +_channel*/). Use it to store the data provided by the other toolkit. + +<sect2>Overriding the Ivy main loop +<p> +In order to override the default definition of the three previous variables, you +will need: +<itemize> +<item> either to create a new library by replacing file <tt/ivyloop.o/ with the file +that contains your definitions +<item> or ... +</itemize> + +<p> + + + + +<sect>Conventions for writing applications +<p> +... the environment variable <tt/IVYBUS/ ..., ... the option <tt/-b/ ... + +</article> -- cgit v1.1