[mirror_edk2.git] / StdLib / Include / Containers / Fifo.h

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