QSE_dgmEventSkip.c File Reference

Utility to help skip events in a datagram. More...

#include <QSE/QSE_dgmEventSkip.h>
#include <LSF/LSF.h>
#include <LSE/LSE_ids.h>
#include <LSF/LSF_scan.h>
#include <PBI/PTR.h>

Classes
struct	Ctx
Functions
static LSF_scanContributionHandler	dgm_skip (Ctx *ctx, const LSF_datagram *dgm)
	Tries to skip over the number of events in this datagram.
static LSF_scanRecordHandler	ctb_skip (Ctx *ctx, const LSF_contribution *ctb)
	Reduces the skip count by the number of events in this contribution.
static LSF_scanRecordHandler	ctb_fast_skip (Ctx *ctx, const LSF_contribution *ctb)
	Reduces the number of events to be skipped by the number of events in this contribution. It is not reduced below 0.
static LSF_scanRecordHandler	ctb_slow_skip (Ctx *ctx, const LSF_contribution *ctb)
	Reduces the skip count by the number of events in this contribution.
static unsigned int	rec_slow_skip (Ctx *ctx, const LSF_record *rec)
	Reduces the skip count by 1. If the skip count reaches 0, the scanning of the records and contributions in the datagram is aborted. In this case the datagram containing the desired event has been found.
int	QSE_dgmEventSkip (const LSF_datagram *dgm, int nskip, int *nctb, int *nrec)
	Counts the skip count down by the number of events in this datagram, but stops if the number of events is greater than nskip.
static __inline unsigned int	check (Ctx *ctx, const unsigned int *rec_end)
	This routine is called when the number of events reaches 0. It checks if this occurs precisely on datagram or contribution boundary and, if so, sets the values context appropriately.

---

Detailed Description

Utility to help skip events in a datagram.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: QSE_dgmEventSkip.c,v 1.2 2011/03/27 01:45:45 russell Exp $

This routine is typically used to help skip the first n events in a datagram packet stream. It stops at the datagram containing the first event to process. This allows the utility to update any datagram contribution or record context that it may need, before beginning the actual processing.

---

Function Documentation

static unsigned int check	(	Ctx *	ctx,
		const unsigned int *	rec_end
	)			[static]

This routine is called when the number of events reaches 0. It checks if this occurs precisely on datagram or contribution boundary and, if so, sets the values context appropriately.

Parameters:

	ctx	The skip context
	rec_end	The ending address of the last record

Referenced by ctb_fast_skip(), and rec_slow_skip().

static __inline LSF_scanRecordHandler ctb_fast_skip	(	Ctx *	ctx,
		const LSF_contribution *	ctb
	)			[static]

Reduces the number of events to be skipped by the number of events in this contribution. It is not reduced below 0.

Parameters:

	ctx	The event skipping context
	ctb	The contribution

References check().

Referenced by ctb_skip().

static LSF_scanRecordHandler ctb_skip	(	Ctx *	ctx,
		const LSF_contribution *	ctb
	)			[static]

Reduces the skip count by the number of events in this contribution.

Parameters:

	ctx	The event skipping context
	ctb	The contribution

References ctb_fast_skip(), and ctb_slow_skip().

Referenced by dgm_skip().

static __inline LSF_scanRecordHandler ctb_slow_skip	(	Ctx *	ctx,
		const LSF_contribution *	ctb
	)			[static]

Reduces the skip count by the number of events in this contribution.

Parameters:

	ctx	The event skipping context
	ctb	The contribution

References rec_slow_skip().

Referenced by ctb_skip().

static LSF_scanContributionHandler dgm_skip	(	Ctx *	ctx,
		const LSF_datagram *	dgm
	)			[static]

Tries to skip over the number of events in this datagram.

Parameters:

	ctx	The event skipping context
	dgm	The datagram

References ctb_skip().

Referenced by QSE_dgmEventSkip().

int QSE_dgmEventSkip	(	const LSF_datagram *	dgm,
		int	nskip,
		int *	nctb,
		int *	nrec
	)

Counts the skip count down by the number of events in this datagram, but stops if the number of events is greater than nskip.

Returns:

> 0 The number of events remaining to be skipped. This value should be passed to QSE_dgmEventSkip as nskip when processing the next datagram. nctb is returned as the count of event contributors and nrec the count of event records in this datagram < 0 The target event is the first event in the next datagram. While the user may call QSE_dgmEventSkip with this as a parameter, its only action will be to set nctb and nrec to 0. = 0 The target event is within this datagram. The user may chose to calculate the number of events to skip (simply by noting the value of nskip when it was passe in) or use the return value in nctb and nrec. These values give the number of contributions to skip and the number of events within that contribution to reach the target event.

Parameters:

	dgm	The datagram to examine
	nskip	The number of events to skip.
	nctb	A returned value (may be NULL) If the skip count has expired, this is returned as the event contribution (0 based) it expired in. If the skip count has not expired this is returned as the count of contributions.
	nrec	A returned value (may be NULL) If the skip count has expired, this is returned as then record number (0 based) within the above contribution it expired at. If the skip count has not expired this is returned as the count of event records.

This routine is used by many utilities when they wish to skip some number of events before starting their processing. The routine pages forward through the datagrams until reaching the desired event. When the datagram with the desired event is reached, 0 is returned. Typically this routine would be called for each datagram until 0 is reached.

Example

This piece of code might appear in LSF_scanDatagrams callback routine.

        int nskip = ctl->nskip;

        / * Check if there are events to skip * /
        if (nskip > 0)
        {
            / * 
              |  If there are no events left to skip, nskip will be
              |  returned as 0 and ctl->nctb and ctl->nevent will be
              |  set to the the number of event contributors and the
              |  number of events to skip within that contributor
              |  before the target event is reached.
 /
             
            nskip = QSE_eventsSkip (dgm, nskip, &ctl->nctb, &ctl->nevent);


            / * If have not reached the skip count yet...* /
            if (nskip)
            {
                / * Skip count not reached yet, update the skip count * /
                ctl->nskip   = nskip;

                / *
                  | No need to process the contributors in this datagram
                  | continue processing the next datagram
 /
                ctb.rtn      = NULL;
                ctb.ctx      = (unsigned int)0;

                return ctb;
            }
        }

        / / Start processing datagrams, one may have page to the
        / / correct event using the nctb and nrec return values

Since this procedure only takes one to the datagram containing the first event to be processed, the event record handling routine would do the mandatory updating of the datagram, contribution and record context for the remaining events to be skipped. Then, when the requisite number of events have been skipped, it would begin normal processing.

For example, this might be the first few lines of code in an event record processing routine might look like this...

    / * Always update the context * /
    status =  QSEP_updateAtRecord (qsep, rec);


    / * Do we need to skip * /
    nskip       = ctl->nleft;
    if (nskip) 
    {
        / * Yes, reduce the skip count and continue to the next event * /
        ctl->nleft = nskip - 1; 
        return 0; 
    }
    
    / * The right numbers of events have been skipped, start processing * /
    ...

Note:

The reason that this does not return a pointer to the given event or provide some other random access method to the event is that typically one must page through the datagram to update the event context. Giving a pointer to the event would not help in this case.

Warning:

It cannot be used to get a count of the number of events in a datagram since it stop when the contribution containing the desired event is reached. I toyed with the idea of placing the event count in the header, but this seemed to elevate the importance of event records over any other kind of records. Maybe that was poor reasoning. It sure would have made this routine easier to implement.

References dgm_skip().

Referenced by QSE_dgmDvrDatagram().

static unsigned int rec_slow_skip	(	Ctx *	ctx,
		const LSF_record *	rec
	)			[static]

Reduces the skip count by 1. If the skip count reaches 0, the scanning of the records and contributions in the datagram is aborted. In this case the datagram containing the desired event has been found.

Parameters:

	ctx	The event skipping context
	rec	The LSF record containing the event

References check().

Referenced by ctb_slow_skip().