Content-type: text/html Man page of Buffer analysis framework library

Buffer analysis framework library

Section: NSCL Data Analysis packages (3)
Updated: 0.1
Index Return to Main Contents

NAME

CBufferProcessor - A callback based buffer processor for ad-hoc data analysis.

SYNOPSIS


        /* Include.. */

#include <config.h>
#include <CBufferProcessor.h>

        /* To get: */

class CBufferProcessor
{

public:
  CBufferProcessor();
  virtual ~CBufferProcessor();
 

  bool          scalersSeen() const;
  unsigned int  scalerCount() const;
  unsigned long lastIncrement(unsigned int channel) const;
  float         Total(unsigned int channel) const;
  unsigned long lastIntervalStart() const;
  unsigned long lastIntervalEnd() const;
  STD(string)   Title() const;
  int           runNumber() const;
  STD(string)   runStartTime() const;
  STD(string)   runEndTime() const;

  void addCallback(unsigned int nBufferType, CBufferCallback& callback);
  void removeCallback(unsigned int nBufferType, CBufferCallback& callback);

  virtual void operator()(const void* pBuffer);

  static BufferTranslator*
                 getTranslatingPointer(const void* pBuffer);

};

        /* Somewhere in your code you need: */

void* gpTCLApplication;

        /* Link something like: */

  c++ -o yourprogram yourprogram.c -I$SpecTclHome/include  -L$SpecTclHome/lib \
        -lAnalysis -ltclPlus -lException -lBufferAnalysis

DESCRIPTION

This class provides a callback based framework for analyzing files containing NSCL formatted event data. The idea is that the user will create and register zero or more callback objects (See CBufferCallback(3)). The data buffers in the event file will then be pushed throug the buffer processor's function call operator. For each buffer, the processor will decode the buffer type and dispatch to the function call operators of the set of buffer callbacks that were registered for that type.

The processor registers a set of standard callbacks. These standard callbacks, invoked prior to any user defined callbacks, process state transition buffers and scaler buffers to support the other member functions in the buffer processing class.

If you are more comfortable programming in C than C++, see the BufferAnalysis(3) man page for a C interface to the framework.

PUBLIC INTERFACE

bool scalersSeen() const: This member function will return true if the run has already processed at least one scaler buffer.
unsigned int scalerCount() const: This member function will return the number of scalers that are being read out in the current run. If scalersSeen() would not return true, a string exception will be thrown: ``No scaler buffers seen so I don't know how many scalers there are''.
unsigned long lastIncrement(unsigned int channel) const: Returns the most recent scaler increments read from channel number channel. If scalersSeen() is false, this will throw the same string exception as scalerCount(). If the channel number does not select a valid scaler channel, the string exception will be: ``Channel number out of range''.
float Total(unsigned int channel) const: Returns the current totals for the selected channel. If no scalers have been seen, the same string exception as is thrown by scalerCount() will be thrown. If the channel selected is not valid, a string exception ``Invalid channel to fetch totals'' will be thrown.
unsigned long lastIntervalStart() const: Returns the number of seconds of elapsed active running until the start of the most recent scaler readout interval. If scalers have not yet been processed for this run, the string exception ``Scalers have not yet been seen, scaler start interval invalid'' is thrown.
unsigned long lastIntervalEnd() const: Same as lastIntervalStat(), however the elapsed times returned are those until the end of the most recent scaler read interval.
STD(string) Title() const: Retrurns a string that contains the title of the current run. If no buffers with titles have been seen (note the start of run has a title), this will be an empty string. STD() is a macro which, if necessary prefixes its parameter with std::.
int runNumber() const: returns the number of the run currently being processed. This will be -1 if no run has ever been processed.
STD(string) runStartTime() const: Returns the time at which this run started. This will be a string of the form: ``Month day,year, hh:mm:ss'', for example ``February 18, 2005, 13:11:15''.
STD(string) runEndTime() const: Once the run has been completely processed, this will return the time the run ended as a timestamp string. The form of the timestamp will be identical to that returned by runStartTime(). Prior to the end of run, this will return an empty string.
void addCallback(unsigned int nBufferType, CBufferCallback& callback): Adds a callback to the processor. nBufferType is the type of buffer for which the callback's function call operator should be invoked. callback is a reference to an object that is derived from the class CBufferCallback (see CBufferCallback(3)). Callbacks form an ordered list for each buffer type. A callback object can be registered on more than one buffer type, however a callback object should be registered at most once for a specific buffer type.
void removeCallback(unsigned int nBufferType, CBufferCallback& callback): Removes a previously registerd callback from the buffer processor. nBufferType is the type of buffer on which this callback was registered. callback is a reference to the callback object that was registered. This member can throw string exceptions: If the buffer type does not yet have any callback list created, the string exception will read: ``Buffer type has no callback lists''. If the buffer type has a callback list, but the specified object is not registered in it, the exception will contain: ``No such callback in list''.
virtual void operator()(const void* pBuffer): Call this member to process a data buffer. The buffer processor will decode the buffer type and dispatch to any registered callbacks for that buffer type. Callbacks will be called in the order in which they were registered.
static BufferTranslator* getTranslatingPointer(const void* pBuffer): This static member function can be called to create a buffer translator object appropriate to this buffer. Buffer translators are used to instantiate TranslatorBufferPointer objects, which provide a pointer like interface to storage that does transparent byte swapping as required. NOTE the pointer returned is dynamically allocated wth new and must be freed by the caller via delete.

EXAMPLE

Much of the error handling require for production software is omitted for this example for the sake of brevity.

The example registers a callback object on all buffer types from 0 through MAXBUFTYPE. It counts the number of buffers of each type and, and the end of the data file, prints out the histogram of buffer types with zeroes supressed.


#include <config.h>
#include <CBufferCallback.h>
#include <CBufferProcessor.h>
#include <buftypes.h>

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <string.h>

#include <Iostream.h>

#ifdef HAVE_STD_NAMESPACE
using namespace std;
#endif

class HistogramCallback : public CBufferCallback
{
private:
  int histogram[MAXBUFTYPE];
public:
  void clear() {
    memset(histogram, 0, sizeof(histogram));
  }
  void dump(ostream& output) {
    for(int i=0; i < MAXBUFTYPE; i++) {
      if(histogram[i] != 0) {
        output << histogram[i] << " instances of buffer type: " << i << endl;
      }
    }
  }
  virtual void operator()(unsigned int ntype, const void* pBuffer) {
    histogram[ntype]++;
  }
};

int main(int argc, char** argv)
{
  unsigned short buffer[4096];
  int fd = open(argv[1], O_RDONLY);
  int nread;
  CBufferProcessor processor;
  HistogramCallback callback;

  for(int i=0; i < MAXBUFTYPE; i++) {
    processor.addCallback(i, callback);
  }

  callback.clear();
  
  while((nread = read(fd, buffer, sizeof(buffer))) > 0) {
    processor(buffer);
  }
  
  cout << "File : " << argv[1] << " run " << processor.runNumber()
       << " " << processor.Title() << endl;
  cout << "Run started: " << processor.runStartTime();
  cout << " Run ended: " << processor.runEndTime() << endl;
  cout << "Buffer type distribution: ;

  callback.dump(cout);
}

void* gpTCLApplication;

This document was created by man2html, using the manual pages.
Time: 18:37:14 GMT, February 18, 2005