home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / timer_429.lzh / Timer / README < prev    next >
Text File  |  1991-01-10  |  4KB  |  97 lines
  1. WAITING ON THE AMIGA
  2. © Copyright 1990 Timm Martin
  3.  
  4.  
  5. INTRODUCTION
  6.  
  7. This archive contains a few functions to allow you to wait inside your C
  8. programs.  Included are 6 files:
  9.  
  10.    README ...... what you are reading now
  11.    article ..... article discussing the technical details
  12.    timer.c ..... all of the timer device functions
  13.    timer.h ..... header file for programs using these functions
  14.    test.c ...... test program showing you how to use these functions
  15.    test ........ executable form of the test program
  16.  
  17. These functions allow you to wait inside your program for a specified amount
  18. of time either synchronously or asynchronously.  A "synchronous" wait means
  19. your program "sleeps" until the desired amount of time has expired.  An
  20. "asynchronous" wait means your program can continue executing, and the timer
  21. device will notify you when the specified amount of time has expired.
  22.  
  23. Using the timer device instead of a simple for-loop to wait inside a program
  24. has a few important advantages:
  25.  
  26.   1) You can be guaranteed of the exact amount of time you will wait with the
  27.      timer device.  With a for-loop, the amount of time you wait is dependent
  28.      on the speed of the machine and how busy it is.
  29.   
  30.   2) With the timer device, you can wait asycnhronously.  The for-loop wait is
  31.      strictly synchronous.
  32.   
  33.   3) Waiting inside a for-loop is a busy-wait, which is taboo in a
  34.      multitasking system.  It will cause other system operations to drag. 
  35.      A synchronous wait using the timer device will put your program to
  36.      sleep, allowing the rest of the system to function unimpeded.
  37.  
  38.  
  39. LEGAL JUNK
  40.  
  41. The text is copyrighted, but all of the source is public domain.  You may use
  42. it in any program, commercial or non-commercial, without acknowledgement of
  43. or compensation to the author.
  44.  
  45. All of the source was written to conform to ANSI C standards and compiles
  46. cleanly using Manx C v5.0b (and compiler options -pas -wadpru).
  47.  
  48.  
  49. GETTING STARTED...QUICKLY!
  50.  
  51. --  Place the timer.h header file in the current directory and add the
  52.     following line to the beginning of your source file:
  53.  
  54.         #include "timer.h"
  55.  
  56. --  In your program startup function, call the timer_open() function,
  57.     checking its return value.  If FALSE, you should end the program.
  58.  
  59. --  In your program cleanup function, call the timer_close() function.
  60.  
  61. --  To wait synchronously, use the timer_wait() function, sending it the
  62.     number of microseconds you want to wait.
  63.  
  64. --  To wait asynchronously, use the timer_start() function, sending it the
  65.     number of microseconds in which you want to be notified.  Then wait for a
  66.     signal from the timer device:
  67.     
  68.         Wait( 1L<<timer_port->mp_SigBit );
  69.  
  70.     This can be combined with other signals to allow you to wait for more
  71.     than one input.  For example, to wait for the timer device and for window
  72.     input:
  73.     
  74.         struct Window *window;
  75.         Wait( 1L<<window->UserPort->mp_SigBit | 1L<<timer_port->mp_SigBit );
  76.  
  77.     To test whether the specified time has elapsed, use the timer_test()
  78.     function.  If it has not elapsed, be sure to call the timer_abort()
  79.     function before issuing another request.  For example:
  80.     
  81.         if (timer_test())
  82.           /* the specified time has elapsed */
  83.         else
  84.           timer_abort();
  85.  
  86. --  Compile the timer.c source file.  Be sure to link this file with your main
  87.     program, for example (with the test.c program and Manx C):
  88.  
  89.         ln test timer -lc
  90.  
  91.  
  92. For more details, read the accompanying article and the source to the test
  93. program.
  94.  
  95.  
  96. /*--- END OF TEXT ---*/
  97.