\hypertarget{RNG_8h}{ \section{RNG.h File Reference} \label{RNG_8h}\index{RNG.h@{RNG.h}} } Utility for configuring a pool of memory as a ring buffer. {\tt \#include \char`\"{}BBC/LLI\_\-type.h\char`\"{}}\par \subsection*{Defines} \begin{CompactItemize} \item \hypertarget{RNG_8h_a0}{ \index{RNG_K_WTO_NO_WAIT@{RNG\_\-K\_\-WTO\_\-NO\_\-WAIT}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_K_WTO_NO_WAIT@{RNG\_\-K\_\-WTO\_\-NO\_\-WAIT}} \#define \hyperlink{RNG_8h_a0}{RNG\_\-K\_\-WTO\_\-NO\_\-WAIT}\ (0)} \label{RNG_8h_a0} \begin{CompactList}\small\item\em Timeout = 0, ie do not wait.\item\end{CompactList}\item \hypertarget{RNG_8h_a1}{ \index{RNG_K_WTO_FOREVER@{RNG\_\-K\_\-WTO\_\-FOREVER}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_K_WTO_FOREVER@{RNG\_\-K\_\-WTO\_\-FOREVER}} \#define \hyperlink{RNG_8h_a1}{RNG\_\-K\_\-WTO\_\-FOREVER}\ (-1)} \label{RNG_8h_a1} \begin{CompactList}\small\item\em Wait forever.\item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{RNG_8h_a2}{ \index{RNG_rcb@{RNG\_\-rcb}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_rcb@{RNG\_\-rcb}} typedef \_\-RNG\_\-rcb \hyperlink{RNG_8h_a2}{RNG\_\-rcb}} \label{RNG_8h_a2} \begin{CompactList}\small\item\em Typedef for RNG buffer control block.\item\end{CompactList}\item \hypertarget{RNG_8h_a3}{ \index{RNG_type@{RNG\_\-type}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_type@{RNG\_\-type}} typedef enum \hyperlink{RNG_8h_a27}{\_\-RNG\_\-type} \hyperlink{RNG_8h_a3}{RNG\_\-type}} \label{RNG_8h_a3} \begin{CompactList}\small\item\em Typedef of the enumeration \_\-RNG\_\-type.\item\end{CompactList}\end{CompactItemize} \subsection*{Enumerations} \begin{CompactItemize} \item enum \hyperlink{RNG_8h_a27}{\_\-RNG\_\-type} \{ \hyperlink{RNG_8h_a27a4}{RNG\_\-K\_\-TYPE\_\-NON\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-NON\_\-BLOCKING, \hyperlink{RNG_8h_a27a5}{RNG\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING, \hyperlink{RNG_8h_a27a6}{RNG\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING \} \begin{CompactList}\small\item\em The type of blocking to use when an allocation is attempted on an empty pool.\item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item void $\ast$ \hyperlink{RNG_8h_a7}{RNG\_\-beg} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to the beginning of the underflow area.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a8}{RNG\_\-rbeg} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to the beginning of the ring buffer area.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a9}{RNG\_\-rend} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to the end of the ring buffer area.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a10}{RNG\_\-end} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to the end of the overflow area.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a11}{RNG\_\-rd} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to current read pointer the ring buffer area.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a12}{RNG\_\-wr} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to the current write pointer.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a13}{RNG\_\-shard} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to current list of shards.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a14}{RNG\_\-buf} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return a pointer to the original buffer.\item\end{CompactList}\item int \hyperlink{RNG_8h_a15}{RNG\_\-bsize} (const struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Query routine to return the size of the original buffer.\item\end{CompactList}\item int \hyperlink{RNG_8h_a16}{RNG\_\-destroy} (struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em Returns any resources associated with this ring buffer.\item\end{CompactList}\item int \hyperlink{RNG_8h_a17}{RNG\_\-sizeof\_\-rcb} (void) \begin{CompactList}\small\item\em Returns the size of the Ring Contol Block.\item\end{CompactList}\item int \hyperlink{RNG_8h_a18}{RNG\_\-init} (struct \_\-RNG\_\-rcb $\ast$rcb, unsigned char $\ast$buf, int size, int underflow, int overflow, int alignment, \hyperlink{RNG_8h_a3}{RNG\_\-type} blocking) \begin{CompactList}\small\item\em Initializes the control structure for a Ring buffer.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a19}{RNG\_\-get} (struct \_\-RNG\_\-rcb $\ast$rcb, int request, const void $\ast$chk\-Wrt) \begin{CompactList}\small\item\em Non-blocking allocation request for a specified amount of memory.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a20}{RNG\_\-grab} (struct \_\-RNG\_\-rcb $\ast$rcb, int minimum, const void $\ast$chk\-Wrt, int $\ast$allocated) \begin{CompactList}\small\item\em Non-blocking allocation request for all the remaining contigious memory.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a21}{RNG\_\-get\-W} (struct \_\-RNG\_\-rcb $\ast$rcb, int request, const void $\ast$chk\-Wrt, int timeout) \begin{CompactList}\small\item\em Blocking allocation request for a specified amount of memory.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a22}{RNG\_\-grab\-W} (struct \_\-RNG\_\-rcb $\ast$rcb, int minimum, const void $\ast$chk\-Wrt, int $\ast$allocated, int timeout) \begin{CompactList}\small\item\em Non-blocking allocation request for all the remaining contigious memory.\item\end{CompactList}\item int \hyperlink{RNG_8h_a23}{RNG\_\-free} (struct \_\-RNG\_\-rcb $\ast$rcb, const void $\ast$packet, int amount) \begin{CompactList}\small\item\em Frees the requested amount of memory from the specified address.\item\end{CompactList}\item void $\ast$ \hyperlink{RNG_8h_a24}{RNG\_\-shrink} (struct \_\-RNG\_\-rcb $\ast$rcb, const void $\ast$new\-Wrt, int left) \begin{CompactList}\small\item\em Shrinks the previously allocated packet back to the specified address.\item\end{CompactList}\item int \hyperlink{RNG_8h_a25}{RNG\_\-reset} (struct \_\-RNG\_\-rcb $\ast$rcb) \begin{CompactList}\small\item\em If the pool is empty, resets the WR/RD pointers to their initial values.\item\end{CompactList}\item \hypertarget{RNG_8h_a26}{ \index{RNG_usec_to_rto@{RNG\_\-usec\_\-to\_\-rto}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_usec_to_rto@{RNG\_\-usec\_\-to\_\-rto}} unsigned int \hyperlink{RNG_8h_a26}{RNG\_\-usec\_\-to\_\-rto} (unsigned int usecs)} \label{RNG_8h_a26} \begin{CompactList}\small\item\em Converts a time, specified in usecs, to a timeout value.\item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Utility for configuring a pool of memory as a ring buffer. \begin{Desc} \item[Author: ]\par JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} {\bf ABSTRACT} \par {\bf --------} \par Implements a set of routines for managing a $\backslash$bsingle {\bf writer} / {\bf single} {\bf reader} ring buffer. The routines are thread and interrupt level safe, although one should {\em not} use the blocking forms \hyperlink{RNG_8h_a21}{RNG\_\-get\-W}() and \hyperlink{RNG_8h_a22}{RNG\_\-grab\-W}() in interrupt routines. The most common usage would be to have the WRITER allocate the memory and fill it. This would then be passed along to another thread which would 'read' or consume the contents, then free the memory. While ring buffers managers are quick and simply allocators, ring buffers have their limitations. This version supports only in order allocation and deallocation. That is one must deallocate the memory in the same order that it was allocated. This version of ring buffer management does provide some help when the end of the ring buffer is reached. In order to keep the allocation request contigious in this case, the ring buffer may be configured with an overflow area. The ring buffer management utilities are allowed to use the overflow to satisfy an allocation request, but they never begin an allocation in the overflow area. It is the user's responsibility to specify the overflow area to be as large as the maximum size request that will be made. The user may also configure an underflow area, which is symmetric to the overflow area, except at the top of the buffer. It's usage is a bit more esoteric. Imagine the situation of wishing to DMA 1000 bytes into a piece of memory allocated by the RNG utility. Circumstances dictate that the memory be contigious within the ring buffer pool. The DMA operation naturally demands continuity. Suppose the current state of the ring buffer is such that one is close the end of the ring buffer pool. The overflow area could be used to satisfy this request. At the end of the DMA operation, the user simply allocates the amount of memory which spilled into the overflow area at the top of the ring buffer and copies into it. The user is now pretty content. The DMA operation proceeded nicely into a chunk of contigious memory and, after the copy operation, the results are contigious in the ring buffer. So what's the problem? It's the copy operation. Suppose the ring buffer only had 4 bytes left at the bottom, leaving the user to copy 996 bytes back to the top. If the allocation could have been made 4 bytes above the top of the ring buffer, then only 4 bytes would have to be copied to the bottom. The underflow provides the memory to implement this scheme. \begin{Desc} \item[Warning: ]\par After having said all that, the underflow is not yet implemented.\end{Desc} {\bf USAGE} EXAMPLE \par {\bf -------------} \par \footnotesize\begin{verbatim} unsigned char pool[POOL_SIZE]; size = RNG_sizeof_rcb (); rcb = (struct _RNG_rcb *)malloc (size); RNG_init (rcb, pool, sizeof(pool), BYTE_ALIGN, RNG_K_TYPE_FIFO_BLOCKING); . . max = 1000; / * Ask for 1000 bytes of memory * / msg = (unsigned char *)RNG_getW (rcb, max, NULL, RNG_K_WTO_FOREVER); . . / * Fill this memory, then return the used portion * / next = fillMemory (msg, max, &left); RNG_shrink (rcb, next, left); used = max - left; . . / * Return the rest of the allocated memory * / RNG_free (rcb, msg, used); \end{verbatim}\normalsize \subsection{Enumeration Type Documentation} \hypertarget{RNG_8h_a27}{ \index{RNG.h@{RNG.h}!_RNG_type@{\_\-RNG\_\-type}} \index{_RNG_type@{\_\-RNG\_\-type}!RNG.h@{RNG.h}} \subsubsection[\_\-RNG\_\-type]{\setlength{\rightskip}{0pt plus 5cm}enum \_\-RNG\_\-type}} \label{RNG_8h_a27} The type of blocking to use when an allocation is attempted on an empty pool. This determines how the ring allocators, \hyperlink{RNG_8h_a21}{RNG\_\-get\-W}() and \hyperlink{RNG_8h_a22}{RNG\_\-grab\-W}(), calls will behave when an allocation is attempted on an empty pool. One can specify non-blocking or two types of blocking, either blocking in FIFO order or PRIORITY order. If a non-blocking type is requested, common practice would be to use the simpler \hyperlink{RNG_8h_a19}{RNG\_\-get}() routine, since it never waits. \begin{Desc} \item[Enumeration values:]\par \begin{description} \index{RNG_K_TYPE_NON_BLOCKING@{RNG\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_K_TYPE_NON_BLOCKING@{RNG\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}}\item[{\em \hypertarget{RNG_8h_a27a4}{ {\em RNG\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}} \label{RNG_8h_a27a4} }]No Blocking when the pool is exhausted \index{RNG_K_TYPE_FIFO_BLOCKING@{RNG\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_K_TYPE_FIFO_BLOCKING@{RNG\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}}\item[{\em \hypertarget{RNG_8h_a27a5}{ {\em RNG\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}} \label{RNG_8h_a27a5} }]FIFO Blocking when the pool is exhausted \index{RNG_K_TYPE_PRIORITY_BLOCKING@{RNG\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}!RNG.h@{RNG.h}}\index{RNG.h@{RNG.h}!RNG_K_TYPE_PRIORITY_BLOCKING@{RNG\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}}\item[{\em \hypertarget{RNG_8h_a27a6}{ {\em RNG\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}} \label{RNG_8h_a27a6} }]PRIORITY blocking when the pool is exhausted \end{description} \end{Desc} \subsection{Function Documentation} \hypertarget{RNG_8h_a7}{ \index{RNG.h@{RNG.h}!RNG_beg@{RNG\_\-beg}} \index{RNG_beg@{RNG\_\-beg}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-beg]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-beg (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a7} Query routine to return a pointer to the beginning of the underflow area. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the beginning of the underflow area.\end{Desc} This routine is primarily used for debugging purposes, but is also useful when determining whether a region of memory occupies any of the underflow area. The underflow area ends at the beginning of the ring buffer area, set \hyperlink{RNG_8h_a8}{RNG\_\-rbeg}(). \begin{Desc} \item[Warning: ]\par Note that due to rounding to alignment boundaries this pointer may or may not be the same as the beginning of the original buffer. \end{Desc} \hypertarget{RNG_8h_a15}{ \index{RNG.h@{RNG.h}!RNG_bsize@{RNG\_\-bsize}} \index{RNG_bsize@{RNG\_\-bsize}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-bsize]{\setlength{\rightskip}{0pt plus 5cm}int RNG\_\-bsize (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a15} Query routine to return the size of the original buffer. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The size of the original pool of memory the RNG utilities where requested to manage.\end{Desc} This routine, along with \hyperlink{RNG_8h_a14}{RNG\_\-buf}(), returns the original buffer address and size that the RNG utilities where requested to manage. These two values may be useful when the RNG buffer is being destroyed, allowing the user to return the buffer to whereever it belongs \hypertarget{RNG_8h_a14}{ \index{RNG.h@{RNG.h}!RNG_buf@{RNG\_\-buf}} \index{RNG_buf@{RNG\_\-buf}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-buf]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-buf (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a14} Query routine to return a pointer to the original buffer. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the original pool of memory the RNG utilities where requested to manage.\end{Desc} This routine, along with \hyperlink{RNG_8h_a15}{RNG\_\-bsize}(), returns the original buffer address and size that the RNG utilities where requested to manage. These two values may be useful when the RNG buffer is being destroyed, allowing the user to return the buffer to whereever it belongs. \hypertarget{RNG_8h_a16}{ \index{RNG.h@{RNG.h}!RNG_destroy@{RNG\_\-destroy}} \index{RNG_destroy@{RNG\_\-destroy}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int RNG\_\-destroy (struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a16} Returns any resources associated with this ring buffer. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} Frees any internally gathered resources associated with the specified ring buffer. The {\em rcb} is no longer usable as ring buffer after this call. \begin{Desc} \item[Warning: ]\par It is the user's responsibility to dispose of the memory associated with the buffer that was being managed and the memory containing the Ring Control Block. \end{Desc} \hypertarget{RNG_8h_a10}{ \index{RNG.h@{RNG.h}!RNG_end@{RNG\_\-end}} \index{RNG_end@{RNG\_\-end}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-end]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-end (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a10} Query routine to return a pointer to the end of the overflow area. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the end of the overflow area\end{Desc} This routine is primarily used for debugging purposes, but may be useful when determining whether a region of memory occupies the overflow area. \begin{Desc} \item[Warning: ]\par Due to rounding to alignment boundaries, this pointer may or may not coincide with the ending of the original pool of memory the RNG utilities where asked to manage. \end{Desc} \hypertarget{RNG_8h_a23}{ \index{RNG.h@{RNG.h}!RNG_free@{RNG\_\-free}} \index{RNG_free@{RNG\_\-free}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-free]{\setlength{\rightskip}{0pt plus 5cm}int RNG\_\-free (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, const void $\ast$ {\em ptr}, int {\em amount})}} \label{RNG_8h_a23} Frees the requested amount of memory from the specified address. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em ptr}]The pointer where the free begins \item[{\em amount}]The amount of memory to free \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} Frees the requested {\em amount} of memory beginning at {\em ptr}. Note that, unlike many other allocators, RNG\_\-free allows partial freeing. One is not obligated to match allocations and deallocations. The only restriction is that the free $\backslash$ptr must be consistent with the next location to be freed by the Ring Buffer utilities, and that one frees only that which is allocated. \hypertarget{RNG_8h_a19}{ \index{RNG.h@{RNG.h}!RNG_get@{RNG\_\-get}} \index{RNG_get@{RNG\_\-get}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-get]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-get (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, int {\em request}, const void $\ast$ {\em chk\-Wrt})}} \label{RNG_8h_a19} Non-blocking allocation request for a specified amount of memory. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em request}]The size, in bytes, of the request \item[{\em chk\-Wrt}]The anticipated allocation value, to within alignment factors. This maybe specified as NULL. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, a pointer to the allocated memory, else NULL.\end{Desc} Attempts to allocate the requested amount of memory. If insufficient memory is available or the {\em chk\-Wrt} pointer is inconsistent with the internal write pointer, NULL is returned. The user can distinguish these two cases by calling \hyperlink{RNG_8h_a12}{RNG\_\-wr}(), to fetch the current value of the write pointer. The user may also live dangerously and specify NULL for the {\em chk\-Wrt} argument, in which case the consistency check is bypassed. \hypertarget{RNG_8h_a21}{ \index{RNG.h@{RNG.h}!RNG_getW@{RNG\_\-getW}} \index{RNG_getW@{RNG\_\-getW}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-getW]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-get\-W (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, int {\em request}, const void $\ast$ {\em chk\-Wrt}, int {\em timeout})}} \label{RNG_8h_a21} Blocking allocation request for a specified amount of memory. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em request}]The size, in bytes, of the request \item[{\em chk\-Wrt}]The anticipated allocation value, to within alignment factors. This maybe specified as NULL. \item[{\em timeout}]The timeout period. Currently only RNG\_\-K\_\-WTO\_\-NO\_\-WAIT (0) and RNG\_\-K\_\-WTO\_\-FOREVER (-1) are supported. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, a pointer to the allocated memory, else NULL.\end{Desc} Attempts to allocate the requested amount of memory. If the {\em chk\-Wrt} pointer is inconsistent with the internal write pointer, or insufficeint memory is available and the timeout period expires, NULL is returned. The user can distinguish these two cases by calling \hyperlink{RNG_8h_a12}{RNG\_\-wr}(), to fetch the current value of the write pointer. The user may also live dangerously and specify NULL for the {\em chk\-Wrt} argument, in which case the consistency check is bypassed. \begin{Desc} \item[Warning: ]\par Blocking on a RNG buffer that is does not have blocking enable will be treated as a NO WAIT call. \end{Desc} \hypertarget{RNG_8h_a20}{ \index{RNG.h@{RNG.h}!RNG_grab@{RNG\_\-grab}} \index{RNG_grab@{RNG\_\-grab}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-grab]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-grab (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, int {\em minimum}, const void $\ast$ {\em chk\-Wrt}, int $\ast$ {\em allocated})}} \label{RNG_8h_a20} Non-blocking allocation request for all the remaining contigious memory. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em request}]The size, in bytes, of the request \item[{\em chk\-Wrt}]The anticipated allocation value, to within alignment factors. This maybe specified as NULL. \item[{\em allocated}]Pointer to receive the actual amount, in bytes, that was allocated. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, a pointer to the allocated memory, else NULL.\end{Desc} This is a greedy form of allocation. All the contigious memory from the current write pointer on is allocated to the caller provided this amount is larger than the minimum requested. This allows the user to continually fill memory even if does not know at allocation time how much is needed. This routine is often used with \hyperlink{RNG_8h_a24}{RNG\_\-shrink}(). Here one allocates as much as one can with RNG\_\-grab, uses what he wants, then returns the unused portion by calling \hyperlink{RNG_8h_a24}{RNG\_\-shrink}(). If there is less than the minimum amount of memory in the pool, NULL is returned. \hypertarget{RNG_8h_a22}{ \index{RNG.h@{RNG.h}!RNG_grabW@{RNG\_\-grabW}} \index{RNG_grabW@{RNG\_\-grabW}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-grabW]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-grab\-W (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, int {\em minimum}, const void $\ast$ {\em chk\-Wrt}, int $\ast$ {\em allocated}, int {\em timeout})}} \label{RNG_8h_a22} Non-blocking allocation request for all the remaining contigious memory. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em request}]The size, in bytes, of the request \item[{\em chk\-Wrt}]The anticipated allocation value, to within alignment factors. This maybe specified as NULL. \item[{\em allocated}]Pointer to receive the actual amount, in bytes, that was allocated. \item[{\em timeout}]The timeout period. Currently only RNG\_\-K\_\-WTO\_\-NO\_\-WAIT (0) and RNG\_\-K\_\-WTO\_\-FOREVER (-1) are supported. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, a pointer to the allocated memory, else NULL.\end{Desc} This is a greedy form of allocation. All the contigious memory from the current write pointer on is allocated to the caller provided this amount is larger than the minimum requested. This allows the user to continually fill memory even if does not know at allocation time how much is needed. This routine is often used with \hyperlink{RNG_8h_a24}{RNG\_\-shrink}(). Here one allocates as much as one can with RNG\_\-grab, uses what he wants, then returns the unused portion by calling \hyperlink{RNG_8h_a24}{RNG\_\-shrink}(). If less the timeout period expires or the internal write pointer is inconsistent with the {\em chk\-Wrt} argument, NULL is returned. The user may distinguish these cases by calling \hyperlink{RNG_8h_a12}{RNG\_\-wr}(). \begin{Desc} \item[Warning: ]\par Blocking on a RNG buffer that is does not have blocking enable will be treated as a NO WAIT call. \end{Desc} \hypertarget{RNG_8h_a18}{ \index{RNG.h@{RNG.h}!RNG_init@{RNG\_\-init}} \index{RNG_init@{RNG\_\-init}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-init]{\setlength{\rightskip}{0pt plus 5cm}int RNG\_\-init (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, unsigned char $\ast$ {\em buf}, int {\em size}, int {\em underflow}, int {\em overflow}, int {\em alignment}, \hyperlink{RNG_8h_a3}{RNG\_\-type} {\em blocking})}} \label{RNG_8h_a18} Initializes the control structure for a Ring buffer. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em buf}]The buffer to be managed \item[{\em size}]The size, in bytes, of the buffer to be managed \item[{\em underflow}]The size, in bytes, of the underflow area \item[{\em overflow}]The size, in bytes, of the overflow area \item[{\em alignment}]The desired alignment of all requests, expressed as a power of 2, eg 0 =$>$ 1 byte alignment, 1 =$>$ 2 byte alignment, 2 =$>$ 4 byte alignment, etc. \item[{\em blocking}]The type of blocking the user wishes. See RNG\_\-type for the types available and their description. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} Initializes a Ring Control Block to manage a pool of memory. The memory is carved into three pieces, an underflow area, a ring buffer area, and an overflow area. The detailed use and meaning of these areas is described elsewhere. \hypertarget{RNG_8h_a8}{ \index{RNG.h@{RNG.h}!RNG_rbeg@{RNG\_\-rbeg}} \index{RNG_rbeg@{RNG\_\-rbeg}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-rbeg]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-rbeg (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a8} Query routine to return a pointer to the beginning of the ring buffer area. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the beginning of the ring buffer area. By definition, this is also the end of the underflow area.\end{Desc} This routine is primarily used for debugging purposes, but is also useful when determining whether a region of memory occupies any of the underflow area or is in the ring buffer pool proper. The underflow area extends from the pointer returned by \hyperlink{RNG_8h_a7}{RNG\_\-beg}() to the pointer returned by this routine. The end of the ring buffer pool is returned from \hyperlink{RNG_8h_a9}{RNG\_\-rend}(). \hypertarget{RNG_8h_a11}{ \index{RNG.h@{RNG.h}!RNG_rd@{RNG\_\-rd}} \index{RNG_rd@{RNG\_\-rd}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-rd]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-rd (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a11} Query routine to return a pointer to current read pointer the ring buffer area. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The value of the current read pointer\end{Desc} This routine is primarily used for debugging purposes. \begin{Desc} \item[Warning: ]\par Whereas many of the other query routines return pointers or values that are static and valid once the ring buffer has been initialized, this pointer is dynamic. Let the user beware. \end{Desc} \hypertarget{RNG_8h_a9}{ \index{RNG.h@{RNG.h}!RNG_rend@{RNG\_\-rend}} \index{RNG_rend@{RNG\_\-rend}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-rend]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-rend (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a9} Query routine to return a pointer to the end of the ring buffer area. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the end of the ring buffer area. By definition this is also the start of the overflow area.\end{Desc} This routine is primarily used for debugging purposes, but is also useful when determining whether a region of memory occupies either the ring buffer pool proper or the overflow area. This pointer is the boundary between those two regions. \hypertarget{RNG_8h_a25}{ \index{RNG.h@{RNG.h}!RNG_reset@{RNG\_\-reset}} \index{RNG_reset@{RNG\_\-reset}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-reset]{\setlength{\rightskip}{0pt plus 5cm}int RNG\_\-reset (struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a25} If the pool is empty, resets the WR/RD pointers to their initial values. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em The}]ring control block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} Normally the read and write pointers are not diddle with except on allocation and deallocation. In an empty pool, the read and write pointers will can be anywhere. This means that the maximum contigious memory may not be available for use. This routine allows the user to reset these pointers to their initial positions, thus maximizing the amount of contigious memory. The downside of this move is that the Ring Buffer loses some of its 'history' feature, which may be valuable as a debugging aid. \hypertarget{RNG_8h_a13}{ \index{RNG.h@{RNG.h}!RNG_shard@{RNG\_\-shard}} \index{RNG_shard@{RNG\_\-shard}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-shard]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-shard (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a13} Query routine to return a pointer to current list of shards. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to any abandoned memory \end{Desc} \begin{Desc} \item[Warning: ]\par This is provided for debugging purposes only. \end{Desc} \hypertarget{RNG_8h_a24}{ \index{RNG.h@{RNG.h}!RNG_shrink@{RNG\_\-shrink}} \index{RNG_shrink@{RNG\_\-shrink}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-shrink]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-shrink (struct \_\-RNG\_\-rcb $\ast$ {\em rcb}, const void $\ast$ {\em new\-Wrt}, int {\em left})}} \label{RNG_8h_a24} Shrinks the previously allocated packet back to the specified address. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \item[{\em new\-Wrt}]The address to shrink to. The current write pointer, up to alignment factors, is moved to this address. \item[{\em left}]The number of unused bytes from the previous allocation. This is used as a consistency check. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, the next write pointer. Due to alignment reasons, this may or may not be the same as $\backslash$new\-Wrt.\end{Desc} Routine shrinks the previously allocated packet back to the specified address. A check is performed to see if this {\em new\-Wrt} pointer plus the number of bytes $\backslash$left in the old allocation is consistent with the Ring Buffer Manager's internal write pointer. If not, NULL is returned. \hypertarget{RNG_8h_a17}{ \index{RNG.h@{RNG.h}!RNG_sizeof_rcb@{RNG\_\-sizeof\_\-rcb}} \index{RNG_sizeof_rcb@{RNG\_\-sizeof\_\-rcb}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-sizeof\_\-rcb]{\setlength{\rightskip}{0pt plus 5cm}int RNG\_\-sizeof\_\-rcb (void)}} \label{RNG_8h_a17} Returns the size of the Ring Contol Block. \begin{Desc} \item[Returns: ]\par The size of a Ring Control Block\end{Desc} This routine allows the user to allocate or set aside a block of memory to be used as Ring Control Block. It is the first step when initializing a Ring Control buffer. This routine allows the implementation to hide the internal structure of a Ring Control Block, but still allow the user to control its allocation. \hypertarget{RNG_8h_a12}{ \index{RNG.h@{RNG.h}!RNG_wr@{RNG\_\-wr}} \index{RNG_wr@{RNG\_\-wr}!RNG.h@{RNG.h}} \subsubsection[RNG\_\-wr]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RNG\_\-wr (const struct \_\-RNG\_\-rcb $\ast$ {\em rcb})}} \label{RNG_8h_a12} Query routine to return a pointer to the current write pointer. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rcb}]The Ring Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The value of the current write pointer\end{Desc} This routine is primarily used for debugging purposes. \begin{Desc} \item[Warning: ]\par Whereas many of the other query routines return pointers or values that are static and valid once the ring buffer has been initialized, this pointer is dynamic. Let the user beware. \end{Desc}