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     @return     Returns the number of elements remaining in the FIFO.
 156 **/
 157 typedef size_t        (EFIAPI *cFIFO_Truncate)  (cFIFO *Self);
 158
 159 /** Cleanly delete a FIFO instance.
 160
 161     @param[in]    Self              Pointer to the FIFO instance.
 162 **/
 163 typedef void        (EFIAPI *cFIFO_Delete)  (cFIFO *Self);
 164
 165 /** Get the FIFO's current Read Index.
 166
 167     @param[in]    Self      Pointer to the FIFO instance.
 168
 169     @return   The current value of the FIFO's ReadIndex member is returned.
 170 **/
 171 typedef UINT32      (EFIAPI *cFIFO_GetRDex) (cFIFO *Self);
 172
 173 /** Get the FIFO's current Write Index.
 174
 175     @param[in]    Self      Pointer to the FIFO instance.
 176
 177     @return   The current value of the FIFO's WriteIndex member is returned.
 178 **/
 179 typedef UINT32      (EFIAPI *cFIFO_GetWDex) (cFIFO *Self);
 180
 181 /// Structure declaration for FIFO objects.
 182 struct _FIFO_CLASS {
 183   /* ######## Public Functions ######## */
 184   cFIFO_Enqueue     Write;            ///< Write an element into the FIFO.
 185   cFIFO_Dequeue     Read;             ///< Read an element from the FIFO.
 186   cFIFO_Copy        Copy;             ///< Non-destructive copy from FIFO.
 187   cFIFO_IsEmpty     IsEmpty;          ///< Test whether the FIFO is empty.
 188   cFIFO_IsFull      IsFull;           ///< Test whether the FIFO is full.
 189   cFIFO_NumInQueue  Count;            ///< Return the number of elements contained in the FIFO.
 190   cFIFO_FreeSpace   FreeSpace;        ///< Return the number of available elements in the FIFO.
 191   cFIFO_Flush       Flush;            ///< Remove the N earliest elements from the FIFO.
 192   cFIFO_Truncate    Truncate;         ///< Remove the most recent element from the FIFO.
 193   cFIFO_Delete      Delete;           ///< Delete the FIFO object.
 194
 195   /* ######## Protected Functions ######## */
 196   cFIFO_GetRDex     GetRDex;          ///< Get a copy of the current Read Index.
 197   cFIFO_GetWDex     GetWDex;          ///< Get a copy of the current Write Index.
 198
 199   /* ######## PRIVATE Data ######## */
 200   void             *Queue;            ///< The FIFO's data storage.
 201   UINT32            ElementSize;      ///< Number of bytes in an element.
 202   UINT32            NumElements;      ///< Number of elements the FIFO can store.
 203   UINT32            ReadIndex;        ///< Index of next element to Read.
 204   UINT32            WriteIndex;       ///< Index of where next element will be Written.
 205 };
 206
 207 __END_DECLS
 208 #endif  /* _FIFO_CLASS_H */