StdLib/Include/Containers/Fifo.h

   1 /** @file
   2   Class for arbitrary sized FIFO queues.
   3
   4   Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials are licensed and made available
   6   under the terms and conditions of the BSD License which accompanies this
   7   distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php.
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12 **/
  13 #ifndef _FIFO_CLASS_H
  14 #define _FIFO_CLASS_H
  15 #include  <Uefi.h>
  16 #include  <wchar.h>
  17 #include  <Containers/ModuloUtil.h>
  18 #include  <sys/types.h>
  19
  20 __BEGIN_DECLS
  21
  22 typedef struct _FIFO_CLASS  cFIFO;
  23
  24 /// Constants to select what is counted by the FIFO_NumInQueue function.
  25 typedef enum {
  26   AsElements,     ///< Count the number of readable elements in the queue.
  27   AsBytes         ///< Count the number of readable bytes in the queue.
  28 } FIFO_ElemBytes;
  29
  30 /** Construct a new instance of a FIFO Queue.
  31
  32     @param[in]    NumElements   Number of elements to be contained in the new FIFO.
  33     @param[in]    ElementSize   Size, in bytes, of an element
  34
  35     @retval   NULL      Unable to create the instance.
  36     @retval   NonNULL   Pointer to the new FIFO instance.
  37 **/
  38 cFIFO * EFIAPI New_cFIFO(UINT32 NumElements, size_t ElementSize);
  39
  40 /** Add one or more elements to the FIFO.
  41
  42     This function allows one to add one or more elements, as specified by Count,
  43     to the FIFO.  Each element is of the size specified when the FIFO object
  44     was instantiated (FIFO.ElementSize).
  45
  46     pElement points to the first byte of the first element to be added.
  47     If multiple elements are to be added, the elements are expected to be
  48     organized as a packed array.
  49
  50     @param[in]    Self        Pointer to the FIFO instance.
  51     @param[in]    pElement    Pointer to the element(s) to enqueue (add).
  52     @param[in]    Count       Number of elements to add.
  53
  54     @retval   0       The FIFO is full.
  55     @retval   >=0     The number of elements added to the FIFO.
  56 **/
  57 typedef size_t  (EFIAPI *cFIFO_Enqueue) (cFIFO *Self, const void *ElementPointer, size_t Count);
  58
  59 /** Read or copy elements from the FIFO.
  60
  61     This function allows one to read one or more elements, as specified by Count,
  62     from the FIFO.  Each element is of the size specified when the FIFO object
  63     was instantiated (FIFO.ElementSize).
  64
  65     pElement points to the destination of the first byte of the first element
  66     to be read. If multiple elements are to be read, the elements are expected
  67     to be organized as a packed array.
  68
  69     @param[in]    Self        Pointer to the FIFO instance.
  70     @param[out]   pElement    Pointer to where to store the element(s) read from the FIFO.
  71     @param[in]    Count       Number of elements to dequeue.
  72     @param[in]    Consume     If TRUE, consume read elements.  Otherwise, preserve.
  73
  74     @retval   0       The FIFO is empty.
  75     @retval   >=0     The number of elements read from the FIFO.
  76 **/
  77 typedef size_t  (EFIAPI *cFIFO_Dequeue) (cFIFO *Self, void *ElementPointer, size_t Count);
  78
  79 /** Make a copy of the FIFO's data.
  80     The contents of the FIFO is copied out and linearized without affecting the
  81     FIFO contents.
  82
  83     @param[in]    Self              Pointer to the FIFO instance.
  84     @param[out]   ElementPointer    Pointer to where to store the elements copied from the FIFO.
  85     @param[in]    Count             Number of elements to copy.
  86
  87     @retval   0       The FIFO is empty.
  88     @retval   >=0     The number of elements copied from the FIFO.
  89 **/
  90 typedef size_t  (EFIAPI *cFIFO_Copy) (cFIFO *Self, void *ElementPointer, size_t Count);
  91
  92 /** Test whether the FIFO is empty.
  93
  94     @param[in]    Self      Pointer to the FIFO instance.
  95
  96     @retval   TRUE    The FIFO is empty.
  97     @retval   FALSE   The FIFO is NOT empty.
  98 **/
  99 typedef BOOLEAN     (EFIAPI *cFIFO_IsEmpty) (cFIFO *Self);
 100
 101 /** Test whether the FIFO is full.
 102
 103     @param[in]    Self      Pointer to the FIFO instance.
 104
 105     @retval   TRUE    The FIFO is full.
 106     @retval   FALSE   The FIFO is NOT full.
 107 **/
 108 typedef BOOLEAN     (EFIAPI *cFIFO_IsFull)  (cFIFO *Self);
 109
 110 /** Determine number of items available to read from the FIFO.
 111
 112     The number of items are either the number of bytes, or the number of elements
 113     depending upon the value of the As enumerator.
 114
 115     @param[in]    Self      Pointer to the FIFO instance.
 116     @param[in]    As        An enumeration variable whose value determines whether the
 117                             returned value is the number of bytes or the number of elements
 118                             currently contained by the FIFO.
 119
 120     @retval   0       The FIFO is empty.
 121     @retval   >=0     The number of items contained in the FIFO.
 122 **/
 123 typedef size_t      (EFIAPI *cFIFO_NumInQueue) (cFIFO *Self, FIFO_ElemBytes As);
 124
 125 /** Determine amount of free space in the FIFO that can be written into.
 126
 127     The number of items are either the number of bytes, or the number of elements
 128     depending upon the value of the As enumerator.
 129
 130     @param[in]    Self      Pointer to the FIFO instance.
 131     @param[in]    As        An enumeration variable whose value determines whether the
 132                             returned value is the number of bytes or the number of elements
 133                             currently available in the FIFO.
 134
 135     @retval   0       The FIFO is full.
 136     @retval   >=0     The number of items which can be accepted by the FIFO.
 137 **/
 138 typedef size_t      (EFIAPI *cFIFO_FreeSpace) (cFIFO *Self, FIFO_ElemBytes As);
 139
 140 /** Empty the FIFO, discarding up to NumToFlush elements.
 141
 142     @param[in]    Self              Pointer to the FIFO instance.
 143     @param[in]    NumToFlush        Number of elements to flush from the FIFO.
 144                                     If larger than the number of elements in the
 145                                     FIFO, the FIFO is emptied.
 146
 147     @return     Returns the number of elements remaining in the FIFO after the flush.
 148 **/
 149 typedef size_t     (EFIAPI *cFIFO_Flush)   (cFIFO *Self, size_t NumToFlush);
 150
 151 /** Remove the most recent element from the FIFO.
 152
 153     @param[in]    Self              Pointer to the FIFO instance.
 154 **/
 155 typedef void        (EFIAPI *cFIFO_Truncate)  (cFIFO *Self);
 156
 157 /** Cleanly delete a FIFO instance.
 158
 159     @param[in]    Self              Pointer to the FIFO instance.
 160 **/
 161 typedef void        (EFIAPI *cFIFO_Delete)  (cFIFO *Self);
 162
 163 /** Get the FIFO's current Read Index.
 164
 165     @param[in]    Self      Pointer to the FIFO instance.
 166
 167     @return   The current value of the FIFO's ReadIndex member is returned.
 168 **/
 169 typedef UINT32      (EFIAPI *cFIFO_GetRDex) (cFIFO *Self);
 170
 171 /** Get the FIFO's current Write Index.
 172
 173     @param[in]    Self      Pointer to the FIFO instance.
 174
 175     @return   The current value of the FIFO's WriteIndex member is returned.
 176 **/
 177 typedef UINT32      (EFIAPI *cFIFO_GetWDex) (cFIFO *Self);
 178
 179 /// Structure declaration for FIFO objects.
 180 struct _FIFO_CLASS {
 181   /* ######## Public Functions ######## */
 182   cFIFO_Enqueue     Write;            ///< Write an element into the FIFO.
 183   cFIFO_Dequeue     Read;             ///< Read an element from the FIFO.
 184   cFIFO_Copy        Copy;             ///< Non-destructive copy from FIFO.
 185   cFIFO_IsEmpty     IsEmpty;          ///< Test whether the FIFO is empty.
 186   cFIFO_IsFull      IsFull;           ///< Test whether the FIFO is full.
 187   cFIFO_NumInQueue  Count;            ///< Return the number of elements contained in the FIFO.
 188   cFIFO_FreeSpace   FreeSpace;        ///< Return the number of available elements in the FIFO.
 189   cFIFO_Flush       Flush;            ///< Remove the N earliest elements from the FIFO.
 190   cFIFO_Truncate    Truncate;         ///< Remove the most recent element from the FIFO.
 191   cFIFO_Delete      Delete;           ///< Delete the FIFO object.
 192
 193   /* ######## Protected Functions ######## */
 194   cFIFO_GetRDex     GetRDex;          ///< Get a copy of the current Read Index.
 195   cFIFO_GetWDex     GetWDex;          ///< Get a copy of the current Write Index.
 196
 197   /* ######## PRIVATE Data ######## */
 198   void             *Queue;            ///< The FIFO's data storage.
 199   UINT32            ElementSize;      ///< Number of bytes in an element.
 200   UINT32            NumElements;      ///< Number of elements the FIFO can store.
 201   UINT32            ReadIndex;        ///< Index of next element to Read.
 202   UINT32            WriteIndex;       ///< Index of where next element will be Written.
 203 };
 204
 205 __END_DECLS
 206 #endif  /* _FIFO_CLASS_H */