CCompoundEventSegment

Name

CCompoundEventSegment -- Container for other event segments

Synopsis


#include <CCompoundEventSegment.h>
         
 class CCompoundEventSegement : public CEventSegment {

  virtual void initialize();
  virtual void clear();
  virtual void disable();
  virtual size_t read(void* pBuffer, size_t maxwords);
  virtual void onBegin();
  virtual void onEnd();
  virtual void onPause();
  virtual void onResume();
  void AddEventSegment(CEventSegment* pSegment);
  void DeleteEventSegment(CEventSegment* pSegment);
  virtual const bool isComposite();
  EventSegmentIterator begin();
  EventSegmentIterator end();
  const size_t size();
  size_t leafCount();
  size_t fullCount();
  void visit(CVisitor& visitor);
}

Description

CCompoundEventSegemnt provides an ordered container for event segment objects (or rather pointers to event segment objects). Since a CCompoundEventSegment itself is an event segment you can build an arbitrarily deep hierarchy of event segments using this class.

A rich set of facilities for navigating the event segment hierarchy is provided though normally this hierarchy gets built at program initialization time and is fixed throughout the lifetime of the program. Navigation models include iteration and visitation. See Types and Public Data for information about the class scoped data types that support these models.

Event segments also provide a mechanism to determine if they are containers via the isComposite member function.

Public member functions

virtual void initialize();

Part of the event segment interface. Does a deep initialization of all events segments in the compound event segment. This is done by calling the initialize member on each element in the container. This implies that if an element of the container is itself a compound event segment, it's children will be recursively initialized.

virtual void clear();

Part of the event segment interface. Does a deep clear of all event segments. This is done by calling the clear member on each element in the container. This implies that if an element of the container is itself a compound event segment, it's children will be recursively cleared.

virtual void disable();

Part of the event segment interface. Does a deep disable of all event segments. This is done by calling the disable member on each element in the container. This implies that if an element of the container is itself a compound event segment, it's children will be recursively disabled.

virtual size_t read(void* pBuffer, size_t maxwords);

Part of the event segment interface. Does a deep read of all event segments. This is done by calling the read member on each element in the container. This implies that if an element of the container is itself a compound event segment, it's children will be recursively read.

pBuffer points to the buffer into which data should be read. maxwords is the maximum number of words that can still fit in that buffer. The method returns the number of words that were read by this segment.

virtual void onBegin();

Invokes onBegin for all event segments in the compound. If there are nested segments, traversal is depth first.

virtual void onEnd();

Invokes onEnd for all event segments in the compound. If there are nested segments, traversal is depth first.

virtual void onPause();

Invokes onPause for all event segments in the compound. If there are nested segments, traversal is depth first.

virtual void onResume();

Invokes onResume for all event segments in the compound. If there are nested segments, traversal is depth first.

void AddEventSegment(CEventSegment* pSegment);

Adds an event segment pSegment to the end of the ordered container of event segments in the compound. Very bad things will happen if pSegment's lifetime is not at least that of the event segment.

void DeleteEventSegment(CEventSegment* pSegment);

If pSegment is one of the immediate children of the object, it is removed from the container. If not, this is a no-op. Please note that this is not a deep delete. If pSegment is actually a child of some compound event segment in the container, it will not be found and therefore not removed.

pSegment is removed from the container. It is up to the calling software, if appropriate, to destroy the actual object.

virtual const bool isComposite();

This returns true. The member function isComposite is provided in all event segments. It is true if the object implements the interface of the compound event segment.

EventSegmentIterator begin();

Returns a begin of iteration iterator. See "Types and Public Data" below for more about iterators. See as well end below for typical usage. This iterator is a shallow iterator.

EventSegmentIterator end();

Returns an iterator that points off the end of the container. This can be used to determine when the iterator has visited all members of the container. The function below shows a typical usage.


CCompoundEventSegment es;
...
CCompoundEventSegment::EventSegmentIterator p = es.begin();
while (p != es.end()) {
    CEventSegment *pSegment = *p;
    //
    // Do something with pSegment:
    ...
    p++;
}
                    

const size_t size();

Returns the number of elements in the event segment container. This is a shallow count.

size_t leafCount();

Returns the number of 'terminal' nodes in the hierarchy. A terminal node is one for which isComposite returns false. This is a deep count.

size_t fullCount();

Returns the total number of nodes in the hiearchy. This is a deep count.

void visit(CVisitor& visitor);

Visits each node in the hieararchy and invokes the visitor at each node at this level of the hierarchy. If deep visitation is required, then whenever the visitor is handed a node for which isComposite is true, it should invoke this method on that node with itself as a parameter.

For more on the visitor class, see "Types and public data". For a recipe for doing recursive visitation, see "EXAMPLES"

Types and public data

This class provides an iterator for its container; CCompoundEventSegment::EventSegmentIterator. This is a pointer like object. When dereferenced the iterator returns a CEventSegment* for a segment that is in the container. Increment moves the 'pointer' to the next item in the container (shallow iteration).

The class provides an abstract base class on which Visitors can be built: CCompoundEventSegment::CVisitor. The definition of this class is shown below:


  class CVisitor {
  public:
    virtual void operator()(CEventSegment* pSegment) = 0;
  };
                

The idea is that you would derive a class from that and invoke the visit method with an object of that class to do something to all nodes in the container.

EXAMPLES

This section shows how to do deep iteration both with visitors and with iterators. The key is that whenever a compound is found iteration or visitation is done recursively on that compond.

Example 1. Deep iteration of CCompondEventSegment elements


/*
   Do something to all leaf nodes of the event segment
   hierarchy
*/
void doSomething(CCompoundEventSegment* pSegment)
{
    CCompoundEventSegment::EventSegmentIterator p = pSegment->begin();
    while (p != pSegment>end()) {
        CEventSegment* pSeg = *p;
        if (pSeg>isComposite()) {
            doSomething(pSeg);     // Recurse to go deep.
        }
        else {
           // Do whatever needs doing here....
        }
        p++;
    }
}
                

Example 2. Deep visitation of CCompoundEventSegment elements


class MyVisitor : public CCompoundEventSegment::CVisitor
{
    virtual void operator()(CEventSegment* pSeg)
    {
        if (pSeg>isCompound()) {
            pSeg>visit(*this);
        }
        else {
            // Do what needs doing to terminal nodes....
        }
    }
};
...
CCompoundEventSegment segment;
MyVisitor visitor;
segment.visit(visitor);  // Visitor ensures deep visitation.

                

SEE ALSO

CEventSegment(3sbsReadout)