home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 534.lha / FifoLib_v3.1 / fifolib.doc.pp / fifolib.doc
Text File  |  1991-08-08  |  13KB  |  373 lines
  1.  
  2.                   FIFO.LIBRARY
  3.  
  4.                MANUAL, REVISION 3
  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_NBIO
  97.         Specify that ReadFifo() and WriteFifo() calls are not to block.
  98.  
  99.  
  100. fifo.library/CloseFifo                      fifo.library/CloseFifo
  101.  
  102.     NAME
  103.     CloseFifo - close a previously openned FIFO
  104.  
  105.     SYNOPSIS
  106.     void CloseFifo(fifo, flags)
  107.             D0     D1
  108.  
  109.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  110.     long flags;    /*  see below    */
  111.  
  112.     FUNCTION
  113.     CloseFifo() is the reverse of OpenFifo(), dereferencing a Fifo.
  114.  
  115.     The last close of a shared fifo will result in the deletion of that
  116.     fifo ONLY if all data has been read, allowing unsynchronized
  117.     programs to use the Fifo.
  118.  
  119.     A future flag will cause the last close of a FIFO to delete the
  120.     fifo and throw away any data.
  121.  
  122.     FLAGS
  123.  
  124.     FIFOF_EOF
  125.         If specified, the FIFO will generate an EOF to readers
  126.         after the last writer has closed.  This particular handle
  127.         need not be the last writer.
  128.  
  129.         If not specified, any active readers are left hanging
  130.         (allowing another program to 'take up' where this one left
  131.         off without the readers knowing)
  132.  
  133.         NOTE that any new writer that OpenFifo()s the fifo will
  134.         clear this flag.
  135.  
  136.         NOTE that the EOF condition will be returned only once
  137.         to a given reader, then cleared (causing the reader to
  138.         block again).  This is because shells generally ignore
  139.         EOF and we would otherwise get into an infinite loop.
  140.  
  141.         THIS FLAG HAS NO EFFECT IF THE HANDLE WAS NOT ORIGINALLY
  142.         OPENNED FIFOF_WRITE.
  143.  
  144. fifo.library/ReadFifo                      fifo.library/ReadFifo
  145.  
  146.     NAME
  147.     ReadFifo -  read data from a FIFO
  148.  
  149.     SYNOPSIS
  150.     long ready = ReadFifo(fifo, pptr, skip)
  151.            D0           D0    D1   A0
  152.  
  153.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  154.     char **pptr;    /*  address of pointer to store buffer pointer      */
  155.     long skip;    /*  # of bytes to skip (delete)     */
  156.     long ready;    /*  # of bytes available to read, -1 = EOF    */
  157.  
  158.     WARNING
  159.     ReadFifo() uses UNCONVENTIONAL ARGUMENTS
  160.  
  161.     FUNCTION
  162.     ReadFifo() first deletes (skip) bytes from the FIFO, then sets a
  163.     pointer into the fifo's buffer and returns the number of bytes
  164.     immediately available for reading.
  165.  
  166.     THE DATA POINTER TO MAY NOT BE MODIFIED UNDER ANY CIRCUMSTANCES
  167.  
  168.     The call is efficient because, in many cases, a buffer copy can be
  169.     completely avoided by the program.  The loop code in the example
  170.     below shows generally how operation works.  For further
  171.     information, refer to the test program (TEST.C).
  172.  
  173.     The number of bytes available (ready), is independant of the
  174.     number of bytes you threw away (skip).  You get a certain amount
  175.     of lookahead for free, but it should be stressed that the (ready)
  176.     value is not necessarily all the available data.  Data in the
  177.     fifo is not always contiguous and so there may be more data
  178.     available than you can immediately determine.  For example, the
  179.     call might return 1 when in fact 500 bytes are available.  But
  180.     only 1 byte is available contiguously (based at the pointer).
  181.     After processing the 1 byte your next read would return 499.
  182.  
  183.     NON-BLOCKING IO
  184.     If FIFOF_NBIO was specified on open, this call will return
  185.     immediately and 0 is a valid return.  If 0 is returned there
  186.     is no data ready and the program must poll the fifo.  But
  187.     wait, there is a better way to do it ... instead of polling
  188.     the fifo you can opt to have a message sent to you when data
  189.     becomes available.  see the RequestFifo() function call and
  190.     look at TEST.C
  191.  
  192.     If FIFOF_NBIO is *not* specified, then 0 will never be returned
  193.     by this call.  Instead, either >0 or -1 (EOF) will be returned.
  194.  
  195.     MULTIPLE-READERS
  196.  
  197.     Multiple readers may exist for a given FIFO.  This is completely
  198.     supported.  If you have one writer and two readers, and the
  199.     writer writes "ABC", then both readers will each read "ABC".
  200.     Because the FIFO buffer is shared, readers may NOT modify any
  201.     data returned in (pptr) because this could effect other readers
  202.     (depending on whether they have already read the data or not).
  203.  
  204.     INTERRUPTS / EXCEPTIONS
  205.  
  206.     ReadFifo() may not be called from an interrupt or a hardware
  207.     exception.  ReadFifo() may ONLY be called from task or process.
  208.  
  209.     EXAMPLE
  210.  
  211.     /*
  212.      *  dump fifo ff.  FIFO was openned without FIFOF_NBIO.
  213.      */
  214.  
  215.     {
  216.         long i = 0;         /*    delete nothing on first loop  */
  217.         long n;
  218.         char *ptr;
  219.  
  220.         while ((n = ReadFifo(ff, &ptr, i)) > 0) {
  221.         if (n > 64)         /*  can easily limit read-size if you */
  222.             n = 64;        /*    want to (optional, obviously)     */
  223.         i = n;            /*    drain this many on next loop    */
  224.         write(1, ptr, n);
  225.         }
  226.         /*
  227.          *    note, if you break out of the loop you may need a final
  228.          *    ReadFifo(ff, &ptr, i); to clear out what you have already
  229.          *    processed.
  230.          */
  231.     }
  232.  
  233.  
  234. fifo.library/WriteFifo                      fifo.library/WriteFifo
  235.  
  236.     NAME
  237.     WriteFifo - write data to a FIFO
  238.  
  239.     SYNOPSIS
  240.     long actual = WriteFifo(fifo, buf, len)
  241.            D0        D0    D1   A0
  242.  
  243.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  244.     void *buf;    /*  buffer to read data into    */
  245.     long max;    /*  maximum # of bytes to read    */
  246.  
  247.     FUNCTION
  248.     WriteFifo() writes data to a FIFO.  WriteFifo() will either return
  249.     actual = len if the write succeeded, 0 if the FIFO is full, or -1
  250.     if an error occurs.  No intermediate values are currently returned
  251.     (i.e. writes are atomic)
  252.  
  253.     If two writers attempt to write to the same FIFO at the same time
  254.     and the FIFOF_NORMAL flag was not specified on open (i.e. writer
  255.     writes from an interrupt or exception), then it is possible for
  256.     a collision to occur in which case one of the calls will return
  257.     an error (-1).
  258.  
  259.     WARNING WARNING
  260.     You may not write blocks larger than 1/2 the fifo buffer size,
  261.     this will generate an immediate error (-2) regardless of how
  262.     much space is actually available.  The reason for this is simply
  263.     that writes are guarenteed to be atomic, and cannot be guarenteed
  264.     if larger blocks are written.  Also, flow control breaks down
  265.     with larger blocks so I figure it is best to nip it in the bud and
  266.     return a formal error.
  267.  
  268.     NON-BLOCKING-IO (FIFOF_NORMAL fifos only)
  269.     Writes are atomic.  If a write fails and FIFOF_NBIO was specified
  270.     on open, the write will return with a failure code of -1.  You
  271.     may optionally poll or use the RequestFifo() call.
  272.  
  273.     Note that even if RequestFifo() returns the message, a write may
  274.     fail due to other processes writing to the fifo before you have
  275.     a chance to, in which case you have to RequestFifo() again and
  276.     loop.
  277.  
  278.     If FIFOF_NBIO was not specified on open, then the write will not
  279.     return until the data has been successfully written, or -2 will
  280.     be returned if you specified too large a buffer.
  281.  
  282.     INTERRUPTS/EXCEPTIONS
  283.     To write to a fifo from an interrupt or exception you must open the
  284.     fifo WITHOUT the FIFOF_NORMAL flag, and be prepared to handle
  285.     possible collisions with other writers.
  286.  
  287.     In this case a failure code of -1 could mean either that the FIFO
  288.     is full or that a collision has occured and you were the side that
  289.     lost out.
  290.  
  291.     WARNING:  any writes via a fifo not openned with the FIFOF_NORMAL
  292.     flag will *NOT* wakeup anybody blocked waiting to read from the
  293.     fifo, whether by RequestFifo() (the message is not returned),
  294.     or via normal opens (without the FIFOF_NBIO flag).  Readers must
  295.     POLL in this case.
  296.  
  297. fifo.library/RequestFifo                fifo.library/RequestFifo
  298.  
  299.     NAME
  300.     RequestFifo - request this message be returned when read data is
  301.               available or write buffer space is available.
  302.  
  303.  
  304.     SYNOPSIS
  305.     RequestFifo(fifo, msg, req)
  306.              D0   D1    A0
  307.  
  308.     void *fifo;
  309.     struct Message *msg;    /*  messasge in question    */
  310.     long req;        /*  request            */
  311.  
  312.     FUNCTION
  313.     Normally this call is used to queue a message to the fifo.library
  314.     that will be ReplyMsg()d to your task when the specified condition
  315.     occurs.  There are four possible requests.
  316.  
  317.     FREQ_RPEND
  318.         Request that the specified message be returned when read data
  319.         is pending on the fifo.
  320.  
  321.         note: if data is immediately available, the message will be
  322.         immediately replied.  If an EOF condition exists or occurs the
  323.         message will also be replied.
  324.  
  325.     FREQ_WAVAIL
  326.         Request that the specified message be returned when the fifo is
  327.         more than half empty.  It is possible that an attempt to write
  328.         after getting your message back will fail due to other writers
  329.         getting their writes in ahead of you.
  330.  
  331.     FREQ_ABORT
  332.         Request that this message, which was previously queued via
  333.         FREQ_RPEND or FREQ_WAVAIL, be returned immediately.
  334.  
  335.         May be called even if message has already been returned but
  336.         not processed.
  337.  
  338.     You may queue multiple messages, even several messages all for the
  339.     same thing.  When you queue a message, it's node becomes owned by
  340.     the library until replied.  You CANNOT queue the same message
  341.     multiple times at once.  Generally programmers will queue one
  342.     message for write-avail-space and another message for
  343.     read-data-ready, then poll the fifo when these messages are
  344.     returned and re-queue the message(s).
  345.  
  346.     ReadFifo() and WriteFifo() call RequestFifo() internally when the
  347.     FIFOF_NBIO flag is NOT used.  This is how they wait for events when
  348.     a call blocks due to lack of data or lack of buffer space.
  349.  
  350.  
  351. fifo.library/BufSizeFifo                fifo.library/BufSizeFifo
  352.  
  353.     NAME
  354.     BufSizeFifo - return size of fifo's buffer
  355.  
  356.     SYNOPSIS
  357.     long bytes = BufSizeFifo(fifo)
  358.            D0         D0
  359.  
  360.     void *fifo;
  361.  
  362.     FUNCTION
  363.     This function returns the size of the specified fifo's buffer.
  364.  
  365.     Note that you may not make WriteFifo() calls with lengths
  366.     larger than 1/2 the size of the fifo's buffer.  This function
  367.     allows you to determine the fifo's buffer size to properly
  368.     observe this limit.  You cannot depend on the buffer size you
  369.     specified in OpenFifo() because only the first OpenFifo() for
  370.     a given fifo actually sets the buffer size.
  371.  
  372.  
  373.