1 files changed, 178 insertions, 0 deletions
diff --git a/doc/ivy-c-5.html b/doc/ivy-c-5.html
new file mode 100644
index 0000000..53eaf19
--- /dev/null
+++ b/doc/ivy-c-5.html
@@ -0,0 +1,178 @@
+<!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-c-6.html" REL=next>
+ <LINK HREF="ivy-c-4.html" REL=previous>
+ <LINK HREF="ivy-c.html#toc5" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="ivy-c-6.html">Next</A>
+<A HREF="ivy-c-4.html">Previous</A>
+<A HREF="ivy-c.html#toc5">Contents</A>
+<HR>
+<H2><A NAME="s5">5. Managing timers and other channels</A></H2>
+
+<P>
+<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.
+<P>
+<H2><A NAME="ss5.1">5.1 Adding channels and timers to the Ivy main loop</A>
+</H2>
+
+<H3>Channels</H3>
+
+<P>You can get a channel to be managed from the Ivy main loop by using functions
+<CODE>IvyChannelSetUp</CODE> and <CODE>IvyChannelClose</CODE>.
+<BLOCKQUOTE><CODE>
+<PRE>
+Channel IvyChannelSetUp (HANDLE fd,
+                        void* data,
+                        ChannelHandleDelete handle_delete,
+                        ChannelHandleRead handle_read);
+</PRE>
+</CODE></BLOCKQUOTE>
+
+ensures that function <CODE>handle_read</CODE> is called whenever data is read on file
+descriptor <CODE>fd</CODE>, and function <CODE>handle_delete</CODE> whenever <CODE>fd</CODE> is
+closed, and
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+void IvyChannelClose (Channel ch);
+</PRE>
+</CODE></BLOCKQUOTE>
+
+terminates the management of channel <CODE>ch</CODE>.
+<P>
+<P>In what precedes, <CODE>Channel</CODE> is an opaque type defined by the Ivy C library, <CODE>data</CODE> is a pointer that will be passed to functions <CODE>handle_read</CODE> 
+and <CODE>handle_delete</CODE>. It can be defined at will by users. 
+The types HANDLE, ChannelHandleDelete and
+ChannelHandleRead are as follows:
+<BLOCKQUOTE><CODE>
+Unix: 
+<PRE>
+typedef int HANDLE;
+</PRE>
+
+Windows: 
+<PRE>
+typedef SOCKET HANDLE;
+</PRE>
+
+<PRE>
+typedef void (*ChannelHandleDelete)(void *data);
+typedef void (*ChannelHandleRead)(Channel ch, HANDLE fd, void* data);
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>
+<P>
+<H3>Timers</H3>
+
+<P>You can get a function to be repeatedly called by using function
+<CODE>TimerRepeatAfter</CODE>:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+TimerId TimerRepeatAfter (int nbticks, long delay, TimerCb handle_timer, void* data);
+</PRE>
+</CODE></BLOCKQUOTE>
+
+ensures that function <CODE>handle_timer</CODE> is called <CODE>nbticks</CODE> times at
+intervals of <CODE>delay</CODE> seconds, thus creating a timer.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+void TimerModify (TimerId id, long delay);
+</PRE>
+</CODE></BLOCKQUOTE>
+
+changes the delay used for timer <CODE>id</CODE>.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+void TimerRemove (TimerId id);
+</PRE>
+</CODE></BLOCKQUOTE>
+
+deletes timer <CODE>id</CODE>, thus stopping it.
+<P>In what precedes, <CODE>data</CODE> is passed to <CODE>handle_timer</CODE> every time it is
+called. <CODE>delay</CODE> is expressed in milliseconds.
+If <CODE>nbticks</CODE> is set to <CODE>TIMER_LOOP</CODE>, then <CODE>handle_timer</CODE> will
+be called forever. <CODE>TimerCb</CODE> is as follows:
+<BLOCKQUOTE><CODE>
+<PRE>
+typedef void (*TimerCb)(TimerId id, void *data, unsigned long delta);
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>
+<P>
+<H2><A NAME="ss5.2">5.2 Adding Ivy to another main loop</A>
+</H2>
+
+<H3>Functions to be provided</H3>
+
+<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:
+<BLOCKQUOTE><CODE>
+<PRE>
+ChannelInit channel_init;
+ChannelSetUp channel_setup;
+ChannelClose channel_close;
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>They should point to functions that respectively:
+<UL>
+<LI> make the necessary global initializations before entering the main loop</LI>
+<LI> initialize a channel and ensure that it is managed by the main loop</LI>
+<LI> close a channel</LI>
+</UL>
+<P>
+<P>The types <CODE>ChannelInit</CODE>, <CODE>ChannelSetUp</CODE> and <CODE>ChannelClose</CODE> are defined
+as follows:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+typedef void (*ChannelInit)(void);
+typedef Channel (*ChannelSetUp)(
+        HANDLE fd,
+        void *data,
+        ChannelHandleDelete handle_delete,
+        ChannelHandleRead handle_read);
+typedef void (*ChannelClose)( Channel channel );
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>
+<P>
+<H3>Type to be defined</H3>
+
+<P>In order to implement the three previous functions, you will need to define the
+hidden type <CODE>struct _channel</CODE> (the type <CODE>Channel</CODE> is defined as <CODE>struct _channel*</CODE>). Use it to store the data provided by the other toolkit.
+<P>
+<H3>Overriding the Ivy main loop</H3>
+
+<P>In order to override the default definition of the three previous variables, you 
+will need:
+<UL>
+<LI> either to create a new library by replacing file <CODE>ivyloop.o</CODE> with the file
+that contains your definitions</LI>
+<LI> or ...</LI>
+</UL>
+<P>
+<P>
+<P>
+<P>
+<P>
+<P>
+<HR>
+<A HREF="ivy-c-6.html">Next</A>
+<A HREF="ivy-c-4.html">Previous</A>
+<A HREF="ivy-c.html#toc5">Contents</A>
+</BODY>
+</HTML>