\hypertarget{FPA_8c}{
\section{FPA.c File Reference}
\label{FPA_8c}\index{FPA.c@{FPA.c}}
}
Utility for configuring and allocating a pool of Fixed Sized Packets. 


{\tt \#include \char`\"{}BBC/FPA.h\char`\"{}}\par
{\tt \#include \char`\"{}BBC/LLI\_\-protos.h\char`\"{}}\par
{\tt \#include \char`\"{}BBC/LLI.ih\char`\"{}}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__FPA__fcb}{\_\-FPA\_\-fcb}
\begin{CompactList}\small\item\em Layouts the control structure for managing the list of free packets. This structure is private to the FPA utility.\item\end{CompactList}\item 
struct \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb}
\begin{CompactList}\small\item\em Layouts the control structure used by each packet on the free list This structure is private to the FPA utility.\item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
\hypertarget{FPA_8c_a0}{
\index{FPA_fcb_sizeof@{FPA\_\-fcb\_\-sizeof}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_fcb_sizeof@{FPA\_\-fcb\_\-sizeof}}
int {\bf FPA\_\-fcb\_\-sizeof} ()}
\label{FPA_8c_a0}

\item 
\hypertarget{FPA_8c_a1}{
\index{FPA_pcb_sizeof@{FPA\_\-pcb\_\-sizeof}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_pcb_sizeof@{FPA\_\-pcb\_\-sizeof}}
int {\bf FPA\_\-pcb\_\-sizeof} ()}
\label{FPA_8c_a1}

\item 
\hypertarget{FPA_8c_a2}{
\index{FPA_init@{FPA\_\-init}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_init@{FPA\_\-init}}
int {\bf FPA\_\-init} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb, char $\ast$buffer, int buf\_\-size, int packet\_\-size, int pcb\_\-offset, \hyperlink{FPA_8h_a2}{FPA\_\-type} type, \hyperlink{FPA_8h_a3}{FPA\_\-cb\_\-init} init\_\-routine, void $\ast$init\_\-parameter)}
\label{FPA_8c_a2}

\item 
\hypertarget{FPA_8c_a3}{
\index{FPA_destroy@{FPA\_\-destroy}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_destroy@{FPA\_\-destroy}}
int {\bf FPA\_\-destroy} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb)}
\label{FPA_8c_a3}

\item 
\hypertarget{FPA_8c_a4}{
\index{FPA_get@{FPA\_\-get}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_get@{FPA\_\-get}}
void $\ast$ {\bf FPA\_\-get} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb)}
\label{FPA_8c_a4}

\item 
\hypertarget{FPA_8c_a5}{
\index{FPA_getW@{FPA\_\-getW}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_getW@{FPA\_\-get\-W}}
void $\ast$ {\bf FPA\_\-get\-W} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb, int timeout)}
\label{FPA_8c_a5}

\item 
\hypertarget{FPA_8c_a6}{
\index{FPA_free@{FPA\_\-free}!FPA.c@{FPA.c}}\index{FPA.c@{FPA.c}!FPA_free@{FPA\_\-free}}
int {\bf FPA\_\-free} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb, void $\ast$packet)}
\label{FPA_8c_a6}

\end{CompactItemize}


\subsection{Detailed Description}
Utility for configuring and allocating a pool of Fixed Sized Packets.



\begin{Desc}
\item[Author: ]\par
JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}
This utility allows one to configure a pool of memory as a collection of fixed sized packets. The allocation and deallocation is interlocked, making it safe to use in a multi-threaded environment.

The behaviour when the pool is exhausted is configurable to be either blocking or non-blocking. If blocking is choose, then the blocking can be in either FIFO or PRIORITY ordering.

A design choice was to hide both the control structure for the pool and the packet management structure. The former is an easy decision, the latter causes some awkward programming at times, but greatly increases modularity. The pain is almost exclusively limited to initialization. This is kind of an experiment to see if this works. If not, it will get changed.

{\bf USAGE/EXAMPLE} \par
 Here is how one would typically use this facility. Suppose one wished to manage a pool of packets which contained data which was to be read from an external source. Further suppose that each packet was to be have a fixed header describing the data type and that this type never changes.



\footnotesize\begin{verbatim}
    FPA_fcb         *fcb;
    int         pcb_size;
    char   *buffer[1000];
    struct MyPacket { int data_type, char buf[46] };

    fcb = malloc (FPA_fcb_sizeofb ());   / * Allocate the control block * /
    FPA_init (fcb,                      / * FPA control block          * /
              buffer,                   / * Memory pool to manage      * /
              sizeof(buffer),           / * Size of the memory pool    * /
              sizeof(struct MyPacket),  / * Size of each packet        * /
              -1,                       / * Place PCB at the bottom    * /
              FPA_K_TYPE_FIFO_BLOCKING, / * Allow FIFO style blocking  * /
              (FPA_cb_init)initializer, / * Initialization routine     * /
              (void *)data_type);       / * Data type of each packet   * /
    .
    .
    .
    while (ptr = isDataReady ())
    {
        packet = FPA_getW (fcb, FPA_K_WTO_WAIT_FOREVER);
        copy (ptr, packet, packet_size);
    }
              
    return;
    }

    / * Callback routine to initialize each packet * /
    void initializer (int data_type,
                      struct MyPacket *packet,
                      int packet_size,
                      int pcb_offset)
    {
        packet.data_type = data_type;
    }

   \end{verbatim}\normalsize