EBF_pkts.h File Reference

EBF pkts, Interface. This provides an iterator like facility for a vector of EBF packets. More...

#include <EDS/io/EBF_pkt.ih>
#include <EDS/EBF_pkt.h>

Classes

struct _EBF_pkts_ps

The iterator control structure. More...

union _EBF_pkts_u

The iterator control structure. More...

Typedefs

typedef struct _EBF_pkts_ps EBF_pkts_ps

Typedef for struct _EBF_pkts_ps.

typedef struct _EBF_pkts_ps EBF_pkts

Opaque type for the packets vector.

typedef union _EBF_pkts_u EBF_pkts_u

Typedef for struct _EBF_pkts.

Functions

static __inline EBF_pkt * EBF__pktsPkt (EBF_pkts pkts)

Retrieves the next packet.

static __inline int EBF__pktsSize (EBF_pkts pkts)

Retrieves the length in bytes of the packets vector.

static __inline EBF_pkts EBF__pktsNext (EBF_pkts pkts)

Pushes the packet iterator to the next packet.

static __inline EBF_pkts EBF__pktsAdvance (EBF_pkts pkts, int size)

Advances the specified packet iterator forward by the specified number of bytes.

int EBF_pktsCount (EBF_pkts pkts)

Counts the number of packets.

EBF_pkts EBF_pktsLimit (EBF_pkts pkts, int limit)

Limits the packets to the specified number of packets.

EBF_pkts EBF_pktsSkip (EBF_pkts pkts, int skip)

Counts the number of packets.

EBF_pkts EBF_pktsSetup (EBF_pkts pkts, int skip, int limit)

Skips the specified number of packets and then limits the packets vector.

Detailed Description

EBF pkts, Interface. This provides an iterator like facility for a vector of EBF packets.

Author:: JJRussell - russell@slac.stanford.edu

    CVS $Id: EBF_pkts.h,v 1.5 2011/08/04 19:46:11 russell Exp $

Overview: This facility provides an iterator like facility for a vector of packets. The vector of packets is described by the EBF_pkts structure. It contains two 32-bit values

A pointer to the first packet in the vector
The size, in bytes, of all the packets in the vector

When all the packets are exhausted, the empty packets vector will be returned. The empty packets vector is defined as the vector with

Its packet pointer pointing just past the last packet (uninteresting, but defined for completeness)
Its remaining size being precisely 0.

Operations: The following operations all return, as an immediate value, a new packet vector, with the first packet pointing at the desired packet. If the desired packet does not exist in the specified packet vector, the empty packets vector is returned.

: The operations are

EBF_pktsEvtsLimit, limits the packet descriptor to no more than the specified number of events. This is useful if the size of the specficed number of events needs to be known apriori to processing the events.
EBF_pktsSkip, skips the requested number of packets

Counting function

In addition, two counting functions

EBF_pktCount
EBF_pktsEvtCount are provided to count to count the number of packets/events

Typedef Documentation

unsigned long long int EBF_pkts

Opaque type for the packets vector.

: The user should never directly access the internals of the EBF_pkts data structure. Rather he should use EBF__pktsPkt and EBF_pktsSize to get a pointer the current packet and the remaining size. Note that the size is the size of the packet vector not the size of the current packet; there is another accessor taking the packet pointer as an argument for that function. The size is mainly used to determine when the vector is exhausted.

: So why did one go through all this, in other words, why not just expose the structure. Well, first, this is more modular, hiding the implementation details, but more importantly, at least in the online world, expressing the packets vector as a 64-bit quantity allows it to be passed into and returned from functions as an immediate value without copying it into temporary memory.

Function Documentation

static __inline EBF_pkts EBF__pktsAdvance	(	EBF_pkts	pkts,
		int	size
	)			`[static]`

Advances the specified packet iterator forward by the specified number of bytes.

Returns:: The new state of the packet iterator

Parameters:

	pkts	The current state of the packet iteractor
	size	The size, in bytes, to advance the packet iterator

Warning:: This routine makes no check that the new iterator actually points to a new packet. If the size goes either negative or the specified size does not point one to an packet, it is let the buyer beware.

: This routine should be used if the packet size in bytes has already been extracted.

References _EBF_pkts_u::p, _EBF_pkts_ps::pkt, _EBF_pkts_u::ps, and _EBF_pkts_ps::size.

Referenced by normal_delivery(), and timed_delivery().

static __inline EBF_pkts EBF__pktsNext ( EBF_pkts pkts ) [static]

Pushes the packet iterator to the next packet.

Returns:: The new state of the packet iterator

Parameters:

pkts

The current state of the packet interactor

References EBF__pktSize(), _EBF_pkts_u::p, _EBF_pkts_ps::pkt, _EBF_pkts_u::ps, and _EBF_pkts_ps::size.

Referenced by EBF_pktsCount(), EBF_pktsLimit(), and EBF_pktsSkip().

static __inline EBF_pkt * EBF__pktsPkt ( EBF_pkts pkts ) [static]

Retrieves the next packet.

Returns:: Pointer to the current packet

Parameters:

pkts

The current state of the packet interator

References _EBF_pkts_u::p, _EBF_pkts_ps::pkt, and _EBF_pkts_u::ps.

Referenced by normal_delivery(), and timed_delivery().

static __inline int EBF__pktsSize ( EBF_pkts pkts ) [static]

Retrieves the length in bytes of the packets vector.

Returns:: Length, in bytes of the packets vector

Parameters:

pkts

The current state of the packet interactor

: This function is mainly used to tell when the packets vector is exhausted, i.e. length = 0.

References _EBF_pkts_u::p, _EBF_pkts_u::ps, and _EBF_pkts_ps::size.

Referenced by normal_delivery(), and timed_delivery().

int EBF_pktsCount ( EBF_pkts pkts )

Counts the number of packets.

Returns:: The number of packets in pkts

Parameters:

pkts

Pointer to the vector of packets to count

References EBF__pktsNext(), _EBF_pkts_u::p, _EBF_pkts_u::ps, and _EBF_pkts_ps::size.

int EBF_pktsLimit	(	EBF_pkts	pkts,
		int	limit
	)

Limits the packets to the specified number of packets.

Returns:: The limited packets vector

Parameters:

	pkts	Pointer to the vector of packets to limit
	limit	The number of packets to limit the vector of packets to

: This limits the packets vector to the specified number of packets. If npkts is specified as -1, this is taken as a flag to not limit the packets vector and the packets vector is returned as is. Note that there may be fewer actual packets than limit. All this function guarantees is that there will be no more than @ limit

References EBF__pktsNext(), _EBF_pkts_u::p, _EBF_pkts_u::ps, and _EBF_pkts_ps::size.

Referenced by EBF_pktsSetup().

EBF_pkts EBF_pktsSetup	(	EBF_pkts	pkts,
		int	skip,
		int	limit
	)

Skips the specified number of packets and then limits the packets vector.

Returns:: New packets vector

Parameters:

	pkts	Pointer to the target vector of packets
	skip	The number of packets to skip
	limit	The maximum number of packets, if -1, no limiting is done

: If there are insufficient packets to satisfy the request, the empty packets vector is returned. This is merely a convenience function, combining EBF_pktsSkip and EBF_pktsLimit.

References EBF_pktsLimit(), and EBF_pktsSkip().

Referenced by EBF_streamProcess().

EBF_pkts EBF_pktsSkip	(	EBF_pkts	pkts,
		int	skip
	)

Counts the number of packets.

Returns:: New packets vector

Parameters:

	pkts	Pointer to the target vector of packets
	skip	The number of packets to skip

References EBF__pktsNext(), _EBF_pkts_u::p, _EBF_pkts_u::ps, and _EBF_pkts_ps::size.

Referenced by EBF_pktsSetup().


Classes
struct	_EBF_pkts_ps
	The iterator control structure. More...
union	_EBF_pkts_u
	The iterator control structure. More...
Typedefs
typedef struct _EBF_pkts_ps	EBF_pkts_ps
	Typedef for struct _EBF_pkts_ps.
typedef struct _EBF_pkts_ps	EBF_pkts
	Opaque type for the packets vector.
typedef union _EBF_pkts_u	EBF_pkts_u
	Typedef for struct _EBF_pkts.
Functions
static __inline EBF_pkt *	EBF__pktsPkt (EBF_pkts pkts)
	Retrieves the next packet.
static __inline int	EBF__pktsSize (EBF_pkts pkts)
	Retrieves the length in bytes of the packets vector.
static __inline EBF_pkts	EBF__pktsNext (EBF_pkts pkts)
	Pushes the packet iterator to the next packet.
static __inline EBF_pkts	EBF__pktsAdvance (EBF_pkts pkts, int size)
	Advances the specified packet iterator forward by the specified number of bytes.
int	EBF_pktsCount (EBF_pkts pkts)
	Counts the number of packets.
EBF_pkts	EBF_pktsLimit (EBF_pkts pkts, int limit)
	Limits the packets to the specified number of packets.
EBF_pkts	EBF_pktsSkip (EBF_pkts pkts, int skip)
	Counts the number of packets.
EBF_pkts	EBF_pktsSetup (EBF_pkts pkts, int skip, int limit)
	Skips the specified number of packets and then limits the packets vector.