home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / util / libs / fifolib / fifolib.doc < prev    next >
Text File  |  1993-10-03  |  13KB  |  378 lines
  1.  
  2.                   FIFO.LIBRARY
  3.  
  4.                MANUAL, VERSION 3.2
  5.  
  6.      (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  7.  
  8.  
  9. fifo.library/FifoNotes
  10. -
  11. fifo.library/OpenFifo
  12. fifo.library/CloseFifo
  13. fifo.library/ReadFifo
  14. fifo.library/WriteFifo
  15. fifo.library/RequestFifo
  16. fifo.library/BufSizeFifo
  17.  
  18. fifo.library/FifoNotes                      fifo.library/FifoNotes
  19.  
  20.     FIFO.LIBRARY is a general fifo library implementation with the following
  21.     features:
  22.  
  23.     * named fifos
  24.     * support for writing to a fifo from a hardware exception
  25.     * multiple readers on a fifo supported, each get the same data
  26.       stream
  27.     * efficient reading (no buffer copies on read)
  28.     * automatic or manual (via message passing) flow control
  29.  
  30.     The uses for this library are limitless.  To use the library, open
  31.     it via OpenLibrary("fifo.library", 0);, the base variable is named:
  32.  
  33.     FifoBase
  34.  
  35.     Please refer to the test program for an example of usage.
  36.  
  37.     LINK LIBRARIES:    fifo.lib    standard amiga (join type) library,
  38.                     large-data model
  39.  
  40.             fifos.lib   standard amiga (joing type) library,
  41.                     small-data model
  42.  
  43.  
  44. fifo.library/OpenFifo                      fifo.library/OpenFifo
  45.  
  46.     NAME
  47.     OpenFifo - open a rendezvous FIFO by name
  48.  
  49.     SYNOPSIS
  50.     fifo = OpenFifo(name, bufsize, flags)
  51.     D0         D0    D1     A0
  52.  
  53.     void *fifo;    /*  returned fifo handle        */
  54.     char *name;    /*  rendezvous name - case sensitive    */
  55.     long bufsize;    /*  must be a power of 2        */
  56.     long flags;    /*  open flags                */
  57.  
  58.     FUNCTION
  59.     OpenFifo() creates a FIFO if <name> does not exist, else
  60.     references an already existing FIFO named <name>.  OpenFifo()
  61.     returns a fifo handle to be used for further operations.
  62.  
  63.     bufsize must be a power of 2.  For example, 1024.
  64.  
  65.     NOTE: two OpenFifo()s openning the same fifo are NOT guarenteed
  66.     to return the same handle, even though they reference the same
  67.     FIFO.
  68.  
  69.     FLAGS
  70.     FIFOF_READ
  71.         file handle intended to be used for reading, do not specify
  72.         unless you read from the handle.
  73.  
  74.     FIFOF_WRITE
  75.         file handle intended to be used for writing, do not specify
  76.         unless you write to the handle.
  77.  
  78.         If a previous CloseFifo() activated FIFOF_EOF, then the flag is
  79.         cleared.
  80.  
  81.     FIFOF_NORMAL
  82.         normal (task based) calls to library, else is assumed calls
  83.         will be made from an interrupt or hardware exception.
  84.  
  85.         NOTE: non-normal fifo writes are unable to wake up blocked
  86.         library calls.  Thus, anybody reading a fifo written to by
  87.         an interrupt or exception (read: enforcer), must poll the
  88.         fifo.  Eventually automatic polling will be an option to make
  89.         operation with non-normal writers transparent to the reader.
  90.  
  91.     FIFOF_KEEPIFD
  92.         When this FIFO is eventually closed, do not destroy it if
  93.         unread data is pending.  Allows a 'writer' to completely finish
  94.         and exit before a read even has the chance to open the fifo.
  95.  
  96.     FIFOF_RREQUIRED
  97.         Cause any write operations to fail when there are no readers
  98.         (i.e. broken pipe), prevents a lockup from occuring if the
  99.         reader is ^C'd.
  100.  
  101.     FIFOF_NBIO
  102.         Specify that ReadFifo() and WriteFifo() calls are not to block.
  103.  
  104.  
  105. fifo.library/CloseFifo                      fifo.library/CloseFifo
  106.  
  107.     NAME
  108.     CloseFifo - close a previously openned FIFO
  109.  
  110.     SYNOPSIS
  111.     void CloseFifo(fifo, flags)
  112.             D0     D1
  113.  
  114.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  115.     long flags;    /*  see below    */
  116.  
  117.     FUNCTION
  118.     CloseFifo() is the reverse of OpenFifo(), dereferencing a Fifo.
  119.  
  120.     The last close of a shared fifo will result in the deletion of that
  121.     fifo ONLY if all data has been read, allowing unsynchronized
  122.     programs to use the Fifo.
  123.  
  124.     A future flag will cause the last close of a FIFO to delete the
  125.     fifo and throw away any data.
  126.  
  127.     FLAGS
  128.  
  129.     FIFOF_EOF
  130.         If specified, the FIFO will generate an EOF to readers
  131.         after the last writer has closed.  This particular handle
  132.         need not be the last writer.
  133.  
  134.         If not specified, any active readers are left hanging
  135.         (allowing another program to 'take up' where this one left
  136.         off without the readers knowing)
  137.  
  138.         NOTE that any new writer that OpenFifo()s the fifo will
  139.         clear this flag.
  140.  
  141.         NOTE that the EOF condition will be returned only once
  142.         to a given reader, then cleared (causing the reader to
  143.         block again).  This is because shells generally ignore
  144.         EOF and we would otherwise get into an infinite loop.
  145.  
  146.         THIS FLAG HAS NO EFFECT IF THE HANDLE WAS NOT ORIGINALLY
  147.         OPENNED FIFOF_WRITE.
  148.  
  149. fifo.library/ReadFifo                      fifo.library/ReadFifo
  150.  
  151.     NAME
  152.     ReadFifo -  read data from a FIFO
  153.  
  154.     SYNOPSIS
  155.     long ready = ReadFifo(fifo, pptr, skip)
  156.            D0           D0    D1   A0
  157.  
  158.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  159.     char **pptr;    /*  address of pointer to store buffer pointer      */
  160.     long skip;    /*  # of bytes to skip (delete)     */
  161.     long ready;    /*  # of bytes available to read, -1 = EOF    */
  162.  
  163.     WARNING
  164.     ReadFifo() uses UNCONVENTIONAL ARGUMENTS
  165.  
  166.     FUNCTION
  167.     ReadFifo() first deletes (skip) bytes from the FIFO, then sets a
  168.     pointer into the fifo's buffer and returns the number of bytes
  169.     immediately available for reading.
  170.  
  171.     THE DATA POINTER TO MAY NOT BE MODIFIED UNDER ANY CIRCUMSTANCES
  172.  
  173.     The call is efficient because, in many cases, a buffer copy can be
  174.     completely avoided by the program.  The loop code in the example
  175.     below shows generally how operation works.  For further
  176.     information, refer to the test program (TEST.C).
  177.  
  178.     The number of bytes available (ready), is independant of the
  179.     number of bytes you threw away (skip).  You get a certain amount
  180.     of lookahead for free, but it should be stressed that the (ready)
  181.     value is not necessarily all the available data.  Data in the
  182.     fifo is not always contiguous and so there may be more data
  183.     available than you can immediately determine.  For example, the
  184.     call might return 1 when in fact 500 bytes are available.  But
  185.     only 1 byte is available contiguously (based at the pointer).
  186.     After processing the 1 byte your next read would return 499.
  187.  
  188.     NON-BLOCKING IO
  189.     If FIFOF_NBIO was specified on open, this call will return
  190.     immediately and 0 is a valid return.  If 0 is returned there
  191.     is no data ready and the program must poll the fifo.  But
  192.     wait, there is a better way to do it ... instead of polling
  193.     the fifo you can opt to have a message sent to you when data
  194.     becomes available.  see the RequestFifo() function call and
  195.     look at TEST.C
  196.  
  197.     If FIFOF_NBIO is *not* specified, then 0 will never be returned
  198.     by this call.  Instead, either >0 or -1 (EOF) will be returned.
  199.  
  200.     MULTIPLE-READERS
  201.  
  202.     Multiple readers may exist for a given FIFO.  This is completely
  203.     supported.  If you have one writer and two readers, and the
  204.     writer writes "ABC", then both readers will each read "ABC".
  205.     Because the FIFO buffer is shared, readers may NOT modify any
  206.     data returned in (pptr) because this could effect other readers
  207.     (depending on whether they have already read the data or not).
  208.  
  209.     INTERRUPTS / EXCEPTIONS
  210.  
  211.     ReadFifo() may not be called from an interrupt or a hardware
  212.     exception.  ReadFifo() may ONLY be called from task or process.
  213.  
  214.     EXAMPLE
  215.  
  216.     /*
  217.      *  dump fifo ff.  FIFO was openned without FIFOF_NBIO.
  218.      */
  219.  
  220.     {
  221.         long i = 0;         /*    delete nothing on first loop  */
  222.         long n;
  223.         char *ptr;
  224.  
  225.         while ((n = ReadFifo(ff, &ptr, i)) > 0) {
  226.         if (n > 64)         /*  can easily limit read-size if you */
  227.             n = 64;        /*    want to (optional, obviously)     */
  228.         i = n;            /*    drain this many on next loop    */
  229.         write(1, ptr, n);
  230.         }
  231.         /*
  232.          *    note, if you break out of the loop you may need a final
  233.          *    ReadFifo(ff, &ptr, i); to clear out what you have already
  234.          *    processed.
  235.          */
  236.     }
  237.  
  238.  
  239. fifo.library/WriteFifo                      fifo.library/WriteFifo
  240.  
  241.     NAME
  242.     WriteFifo - write data to a FIFO
  243.  
  244.     SYNOPSIS
  245.     long actual = WriteFifo(fifo, buf, len)
  246.            D0        D0    D1   A0
  247.  
  248.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  249.     void *buf;    /*  buffer to read data into    */
  250.     long max;    /*  maximum # of bytes to read    */
  251.  
  252.     FUNCTION
  253.     WriteFifo() writes data to a FIFO.  WriteFifo() will either return
  254.     actual = len if the write succeeded, 0 if the FIFO is full, or -1
  255.     if an error occurs.  No intermediate values are currently returned
  256.     (i.e. writes are atomic)
  257.  
  258.     If two writers attempt to write to the same FIFO at the same time
  259.     and the FIFOF_NORMAL flag was not specified on open (i.e. writer
  260.     writes from an interrupt or exception), then it is possible for
  261.     a collision to occur in which case one of the calls will return
  262.     an error (-1).
  263.  
  264.     WARNING WARNING
  265.     You may not write blocks larger than 1/2 the fifo buffer size,
  266.     this will generate an immediate error (-2) regardless of how
  267.     much space is actually available.  The reason for this is simply
  268.     that writes are guarenteed to be atomic, and cannot be guarenteed
  269.     if larger blocks are written.  Also, flow control breaks down
  270.     with larger blocks so I figure it is best to nip it in the bud and
  271.     return a formal error.
  272.  
  273.     NON-BLOCKING-IO (FIFOF_NORMAL fifos only)
  274.     Writes are atomic.  If a write fails and FIFOF_NBIO was specified
  275.     on open, the write will return with a failure code of -1.  You
  276.     may optionally poll or use the RequestFifo() call.
  277.  
  278.     Note that even if RequestFifo() returns the message, a write may
  279.     fail due to other processes writing to the fifo before you have
  280.     a chance to, in which case you have to RequestFifo() again and
  281.     loop.
  282.  
  283.     If FIFOF_NBIO was not specified on open, then the write will not
  284.     return until the data has been successfully written, or -2 will
  285.     be returned if you specified too large a buffer.
  286.  
  287.     INTERRUPTS/EXCEPTIONS
  288.     To write to a fifo from an interrupt or exception you must open the
  289.     fifo WITHOUT the FIFOF_NORMAL flag, and be prepared to handle
  290.     possible collisions with other writers.
  291.  
  292.     In this case a failure code of -1 could mean either that the FIFO
  293.     is full or that a collision has occured and you were the side that
  294.     lost out.
  295.  
  296.     WARNING:  any writes via a fifo not openned with the FIFOF_NORMAL
  297.     flag will *NOT* wakeup anybody blocked waiting to read from the
  298.     fifo, whether by RequestFifo() (the message is not returned),
  299.     or via normal opens (without the FIFOF_NBIO flag).  Readers must
  300.     POLL in this case.
  301.  
  302. fifo.library/RequestFifo                fifo.library/RequestFifo
  303.  
  304.     NAME
  305.     RequestFifo - request this message be returned when read data is
  306.               available or write buffer space is available.
  307.  
  308.  
  309.     SYNOPSIS
  310.     RequestFifo(fifo, msg, req)
  311.              D0   D1    A0
  312.  
  313.     void *fifo;
  314.     struct Message *msg;    /*  messasge in question    */
  315.     long req;        /*  request            */
  316.  
  317.     FUNCTION
  318.     Normally this call is used to queue a message to the fifo.library
  319.     that will be ReplyMsg()d to your task when the specified condition
  320.     occurs.  There are four possible requests.
  321.  
  322.     FREQ_RPEND
  323.         Request that the specified message be returned when read data
  324.         is pending on the fifo.
  325.  
  326.         note: if data is immediately available, the message will be
  327.         immediately replied.  If an EOF condition exists or occurs the
  328.         message will also be replied.
  329.  
  330.     FREQ_WAVAIL
  331.         Request that the specified message be returned when the fifo is
  332.         more than half empty.  It is possible that an attempt to write
  333.         after getting your message back will fail due to other writers
  334.         getting their writes in ahead of you.
  335.  
  336.     FREQ_ABORT
  337.         Request that this message, which was previously queued via
  338.         FREQ_RPEND or FREQ_WAVAIL, be returned immediately.
  339.  
  340.         May be called even if message has already been returned but
  341.         not processed.
  342.  
  343.     You may queue multiple messages, even several messages all for the
  344.     same thing.  When you queue a message, it's node becomes owned by
  345.     the library until replied.  You CANNOT queue the same message
  346.     multiple times at once.  Generally programmers will queue one
  347.     message for write-avail-space and another message for
  348.     read-data-ready, then poll the fifo when these messages are
  349.     returned and re-queue the message(s).
  350.  
  351.     ReadFifo() and WriteFifo() call RequestFifo() internally when the
  352.     FIFOF_NBIO flag is NOT used.  This is how they wait for events when
  353.     a call blocks due to lack of data or lack of buffer space.
  354.  
  355.  
  356. fifo.library/BufSizeFifo                fifo.library/BufSizeFifo
  357.  
  358.     NAME
  359.     BufSizeFifo - return size of fifo's buffer
  360.  
  361.     SYNOPSIS
  362.     long bytes = BufSizeFifo(fifo)
  363.            D0         D0
  364.  
  365.     void *fifo;
  366.  
  367.     FUNCTION
  368.     This function returns the size of the specified fifo's buffer.
  369.  
  370.     Note that you may not make WriteFifo() calls with lengths
  371.     larger than 1/2 the size of the fifo's buffer.  This function
  372.     allows you to determine the fifo's buffer size to properly
  373.     observe this limit.  You cannot depend on the buffer size you
  374.     specified in OpenFifo() because only the first OpenFifo() for
  375.     a given fifo actually sets the buffer size.
  376.  
  377.  
  378.