GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-8
Constituent: pbs     Tag: linux-gcc
#include "PBS/L_pubdefs.h"
#include "PBS/LI_type.h"
#include "PBS/LI_comdefs.h"
#include "PBS/TOC_comdefs.h"
Include dependency graph for FPA.h:
This graph shows which files directly or indirectly include this file:
Data Structures | |
struct | _FPA_pcb |
Layouts the control structure used by each packet while it is on the free list. More... | |
Defines | |
#define | FPA_K_PCB_AT_EOP (-1) |
Convenience symbol indicating that the packet control block, the FORK_pcb, should be placed at the end of the packet (EOP). | |
Typedefs | |
typedef enum _FPA_type | FPA_type |
Typedef for enum _FPA_type. | |
typedef _FPA_pcb | FPA_pcb |
Typedef for struct _FPA_pcb. | |
typedef void(* | FPA_init_cb )(void *parameter, void *packet, int packet_size, int pcb_offset) |
Function signature for the packet initialization callback routine. | |
typedef _FPA_fcb | FPA_fcb |
Typedef for struct _FPA_fcb. | |
Enumerations | |
enum | _FPA_type { FPA_K_TYPE_LOCKING_ONLY = RW_K_TYPE_LOCKING_ONLY, FPA_K_TYPE_PENDING = RW_K_TYPE_PENDING, FPA_K_TYPE_PENDING_WTO = RW_K_TYPE_PENDING_WTO, FPA_K_TYPE_PENDING_FIFO = RW_K_TYPE_PENDING_FIFO, FPA_K_TYPE_PENDING_FIFO_WTO = RW_K_TYPE_PENDING_FIFO_WTO, FPA_K_TYPE_PENDING_PRIORITY = RW_K_TYPE_PENDING_PRIORITY, FPA_K_TYPE_PENDING_PRIORITY_WTO = RW_K_TYPE_PENDING_PRIORITY_WTO } |
Enumerates the FPA types available. More... | |
Functions | |
int | FPA_fcb_sizeof (void) |
Returns the size of the Fixed Packet Allocator control block. | |
int | FPA_init (FPA_fcb *fcb, FPA_type blocking, void *buffer, int buf_size, int packet_size, int pcb_offset, FPA_init_cb init_routine, void *init_parameter) |
Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated. | |
void * | FPA_get (FPA_fcb *fcb) |
Get or allocate a packet from the free list. | |
void * | FPA_getW (FPA_fcb *fcb) |
Get or allocate a packet from the free list with a indefinite blocking. | |
void * | FPA_getW_toc (FPA_fcb *fcb, const TOC *toc) |
Get or allocate a packet from the free list using the timeout specified by TOC. | |
int | FPA_free (FPA_fcb *fcb, void *packet) |
Returns a previously allocated packet to the free list. | |
int | FPA_destroy (FPA_fcb *fcb) |
Releases any resources gathered at initialization time. |
CVS $Id: FPA.h,v 1.4 2005/02/14 16:34:50 russell Exp $
SYNOPSIS
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 chosen, then the blocking can be in either FIFO or PRIORITY ordering. This is relevant only when multiple allocators use the pool.
An initial 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 caused awkward programming at times, but would increase modularity. The pain is almost exclusively limited to initialization. It was an experiment to see if this worked, but given the rather limited exposure (the packet management structure is currently only LI_node structure, a single 4-byte word), it was decided to keep the FPA control structure hidden, but expose the FPA packet control structure.
USAGE/EXAMPLE
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 constrained to be the first word of the data packet describing the data type and that this type never changes. This makes the data_type field a candidate for one-time initialization. Since the initializer routine writes the data_type field, the packet control block used to manage the packet when it is on the FPA freelist must not be allowed to occupy the first word. Since, presumably, the body of the structure is filled with fresh data each time, the packet control block can be located anywhere within that section. The choice in the example is to locate it as the first word of the data field.
struct _MyPacket { / * Packet consists of a header ... * / int data_type; / * Header gives the data type * / union _MyData / * and a body * / { FPA_pcb pcb; / * Management when packet is not allocated * / char buf[60]; // * Holds the data when allocated * / } body; }; FPA_fcb *fcb; char *buffer[1000]; fcb = MBA_alloc (FPA_fcb_sizeof ());/ * 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 * / OFFSET_OF(_struct _MyPacket, body.pcb), / * Byte offset of PCB * / FPA_K_TYPE_BLOCKING, , / * Blocking, single allocator * / (FPA_init_cb)initializer, / * Initialization routine * / (void *)data_type); / * Data type of each packet * / . . . while (ptr = isDataReady ()) { struct _MyPacket *packet = FPA_getW (fcb); copy (packet->body.buf, ptr, sizeof (packet->body.buf)); } 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; }
|
Function signature for the packet initialization callback routine.
|
|
Typedef for struct _FPA_pcb. The FPA routines require some storage to manage each packet on the free list. This memory is only used while on the free list and, therefore is available to the user after it a packet has been allocated. Every attempt was made to keep this overhead as small as possible. Currently, this requires only a single 4-byte word.
|
|
Typedef for enum _FPA_type. This determines how the FPA_getW() and FPA_getW_toc() calls will behave when an allocation is attempted on an empty pool. One can specify non-blocking or two types of blocking,
If a non-blocking type is requested only FPA_get() routine can be called.
|
|
|
Releases any resources gathered at initialization time.
|
|
Returns the size of the Fixed Packet Allocator control block.
This call is for modularity reasons. The user can learn the size of memory needed by the FPA utility to manage a pool of packets without needing to know the details of how it is laid out. This could have also been achieved by having the FPA initialization routine allocate the control block, but this takes away the freedom of the user to control his own allocation and deallocation |
|
Returns a previously allocated packet to the free list.
|
|
Get or allocate a packet from the free list.
|
|
Get or allocate a packet from the free list with a indefinite blocking.
|
|
Get or allocate a packet from the free list using the timeout specified by TOC.
|
|
Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated.
Various options allow the user to place where the control structure lives within the packet and determine the blocking style. The most usual choice for the placement of the packet control structure is at the beginning pcb_offset = 0, or at the end pcb_offset = -1, although the user is allowed to specify any offset, provided it is within the packet. The usual blocking style is FPA_K_TYPE_FIFO_BLOCKING.
|