Represents a data source from a file descriptor. This is not an abstract base class, as it's used to accept data from file data sources. It is also the base class for CPipeFile which gets data from a program helper along a pipe.

Understands how items are packaged by the data acquisition system. Once the CFile object has been asked to read a block of data from its encapsulated file descriptor, that block of data is passed to the CBufferDecoder. That object unpackes items from the data block and calls appropriate methods in the CAnalyzer object.

Dispatches items from the buffer decoder to the appropriate methods of the event processors in the event processing pipeline.

A templated class that has the semantics of a pointer but transparently performs byte reordering if needed. This operates by encapsulating a BufferTranslator object which may or my not swap items as needed.

The BufferFactory knows how to instantiate the right type of BufferTranslator by being given an appropriate set of signature bytes which define the byte order of the originating system. These are compared against signature bytes generated by the running system to determine the required byte ordering.

This is the normal constructor. The state of the file is kfsClosed, indicating the object is not yet connected to a file. The Open method is normally then used to open a file.

Constructs the object in an kfsOpen state. The nFd parameter is an already file descriptor openon whatever data source the object will read from or write to.

fixedLength means that the client will perform reads of fixed sized blocks of data. This means, specifically, that the read operations will block on a read until all requested bytes have been accepted or until an error or endfile condition is signaled.

If fixedLength is false, read will be done in non-blocking mode. This allows for partial transfers which can be useful in some applications.

Gets the file descriptor that's bound to the object. This only has meaning if the object's state iss kfsOpen.

Returns the object state. This can be on of kfsOpen in which case the file can be considered open. It can also be kfsClosed un which case the file should be considered closed.

Attempts to read nSize bytes from the file descriptor associated with the object into pBuffer. This throws an error if the object is in the kfsClosed state.

The number of bytes actually read is returned. Note that the behavior of this method depends on whether or not the object has been told to run in fixed block size mode. In Linux reads may terminate transferring some, all or none of the data.

IF fixed size block mode is enabled and the underlying read returns fewer than the requested number of bytes, additional reads are performed until the requested number of bytes have been received. If fixed sized mode is off, only one read will ever be performed.

All errors are signalled by throwing a CErrnoException. If an end file is reached, the method returns 0.

Writes nBytes of data to the file descriptor that is associated with this object. The data comes from the storage pointed to by pBuffer. An exception is thrown if the object is not in the kfsOpen state. An exception is also thrown if the write fails.

It is possible that the write will transfer fewer bytes of data than requested. The actual number of bytes transfered is the method's return value. Unlike Read, only one write is ever performed and the caller will need to perform additional transfers, if necessary, until the entire block of data is written.

Opens a file, binding its file descriptor into the object. If the state of the object is kfsOpen, the existing file is closed prior to opening the new file.

The file opened is rsFilename. The nAccess parameter is a bit mask of kacRead (file is readable), kacWrite (file is writable) and kacCreate (file can be created if needed).

If fullBlocks is true, reads will be done in blocking mode and however many reads needed to fill the user buffer will be performed. If, on the other hand, fullBlocks is false, reads are done with blocking turned off and only one read is done to attempt to satisfy a Read requests.

On success, the state of the object will be kfsOpen. On failure, an exception will be thrown.

Sets the state of the object into kfsOpen and binds the nFd parameter as the object's file descriptor. If there's already an open file descriptor it is first closed.

The intent of this method is to allow a file descriptor opened outside of CFile to be used with CFile objects.

Closes the file descriptor bound to the object and sets the state to kfsClosed. If there is no open file descriptor bound to the object, an exception is thrown..

Returns kfTRUE if the file descriptor bound to the object becomes readable within nMs milliseconds. If the object state is kfsClosed, kfFALSE is returned.

Note that the base class implementation, simply returns true if the file is open and false if not. This is suitable for disk files that are always readable. Derived classes may want to override this, implementing it in terms of select(2).

These constructors create the base class. Two parameters control when the event sink is run and how events are allocated.

nParametersInEvent is the number of parameters that are initially in the event array like object that is passed to the event processig pipeline. This gets expanded as needed. Furthermore, these objects are now recycled, so the impact of getting this wrong is not nearly what it used to be.

nThreshold is the maximum number of events that will be accumulated from successive runs of the evet analysis pipeline before the event sink pipeline is called.

Returns the number of events that need to be accumulated before they are passed through the event sink pipeline.

Returns the initial size for event objects. Events are dynamically expanded. Furthermore, once used and analyzed, they are invalidated, rather than destroyed and re-used later.

The effect of this is that eventually events grow to the fit the largest numbered parameter used by the analysis case.

The analyzer collects all events into an event list (a wrapped vector of events). This event list is then iterated over to send events to the analysis pipeline. This method returns a reference to the event list.

The event list should not be confused with the event pool, also maintained by the analyzer but not available externally. The event pool is a CEventList that contains invalidated events that may be handed to runs of the event analysis pipeline. The Analyzer passes events from the event pool to the analysis pipeline, whereupon they are put in the event list. The event list is passed, event by event, to the event sink pipeline whereupon each event is invalidated and putback in the event pool.

Returns a pointer to the current buffer decoder. The buffer decoder is selected by the -format option of the attach command.

Returns a pointer to the analyzer's event sink. In practice this is actually a pointer to an CEventSinkPipeline which, itself, contains an ordered list of CEventSink objects including a CHistogrammer and zero or more CEventFilter objects.

This method is invoked by SpecTcl when a block of data has been read from the data source. pData points to that block and nBytes is the number of bytes actually read.

This base class simply invokes the buffer decoder's operator() method which is expected to break apart the buffer into bits the analyzer cares about and make callbacks to the analyzer. Many of the remaining methods are normally called by the buffer decoder from within its operator()

Called by the buffer decoder to process state change items. State change items are supposed to indicate a change in run state such as begin run. Note that not all data acquisition systems emit state change items. Not all analysis cases need them.

The nType parameter identifies the type of state change. For NSCLDAQ, these are defined in buftypes.h. The ones that could be passed in to this method in NSCLDAQ are BEGRUNBF (begin run), ENDRUNBF (end run), PAUSBF (pause run), and RESUMEBF (resume run).

Note to the astute reader that the ring buffer decoder maps the ring item types for state changes into these values in order to retain compatibility with older analysis cases.

rDecoder references the decoder. The decoder can be used to fetch key bits of information about the item the decoder has plucked from the item.

Typically the decoder can now respond to calls back to getRun, getTitle with the run number and title of this run respectively (if available).

This method is invoked by the buffer decoder when a run of physics events has been detected. The buffer decoder must be prepared to reply to method calls to getBody, getBodySize and getEntityCount to allow OnPhysics to know the location, extent of the data and how many events to expect.

If the event processing pipeline attempts to run the analyzer off the end of the extent of the data (indicated by getBodySize, the analyzer will throw an exception and abort processing of that chunk. If the event processing pipeline does not consume all of the data after analyzing the number of events indicated by getEntityCount an error message is emitted as well.

Called by the buffer decoder when a scaler item has been encountered in the input data. Scaler items are expected to have a set of counters. The buffer decoder must be ready to respond to invocations of the buffer decoder's getBody, getBodySize and getEntityCount from the event analysis pipeline as the analyzer makes no assumptions about the format of the scaler item.

Convention holds that getBodySize will give the size of the scaler item pointed to by getBody and getEntityCount returns the number of scalers in the item.

Called by the buffer decoder for other types of items. nType is the type of data item encountered. This value depends on the data acquisition system contributing data. Note that NSCLDAQ's ring buffer decoders map ring items to values in bftypes.h, buffer types for the NSCLDAQ-8.x system (prior to ring buffers).

Invoked by the data source, I/O subsystem when an endfile was detected on the data source. For pipe files, this implies the program on the other end of the pipe either exited or closed its stdout. For actual disk file data sources this is invoked whenthe entire file has been read.

Called by the SpecTcl main application object when SpecTcl initialization is completed. One of the expectations of this method is that it will invoke OnInitialize for all elements of the event analysis pipeline.

Called by the SpecTcl framework to attach a new buffer decoder, rDecoder. A pointer to the prior decoder is returned. If there is no prior decoder, a null pointer should be returned.

Detaches the current decoder from the the analyzer. This returns a pointer to the previous decoder. Note that attempting to use the analyzer when no decoder is attached will most likely cause program failure.

Attaches a new event sink to the analyzer. Normally, the event sink is an CEventSinkPipeline (defined in EventSinkPipeline.h). CEventSinkPipeline is a container for an ordered set of CEventSink objects (including a CHistogrammer).

It is rare that you'll need to invoke this method. The return value of this method is a pointer to the prior event sink object or nullptr if there is no prior event sink.

Detaches the event sink from the analyzer. The result of this method is a pointer to the previously attached event sink. It is likely that using the analyzer when no event sink is attached will cause program failure.

This method can be called from within the event processing pipeline's operator() method. It is called to indicate that when the event processing pipeline is complete, while the size of the event should be used to advance the event pointer, the number of entities should not be decremented.

The purpose of this method is to simplify event processing for data acquisition systems that have the capability to emit super events. A super event is an event like chunk of data that contains several events. An example of a use of super events would be processing hardware containing multi-event buffers. The devices might be drained responding to a single trigger leaving a structure that contains several physics events.

In cases like that, the event processing pipeline needs to be invoked for each event contained in the super event and therefore needs control over when to report that it has completed processing of the outer entity.

Another alternative is to produce a buffer decoder that treats each super event as a run of events, however that would require that the buffer decoder know enough about the internal structure of the super event to be able to determine the number of events each super event contains.

This is expected to return a BufferTranslator that, in turn, can be used to instantiate TranslatorPointers. These are part of SpecTcl's scheme to insulate programmers from byte order differences that might exist between the data source and SpecTcl.

NSCL data acquisition systems provide byte order signatures that allow consumers to determine if these differences exist (though the mechanism differs between NSCLDAQ 8 and earlier and NSCLDAQ 10 and later [there is no NSCLDAQ 9).

If you are processing data from a system that does not provide these hints, you'll need to use your knoweledge of the byte order of the source system and probe the system SpecTcl is running on to produce the proper BufferTranslator object.

This pure virtual method is expected to return the body of the item currently being processed. In many cases the item has a single logical entity (e.g. information about a state change), however in others, such as physics event items, the item may contain more than one entity in which case getBody returns a pointer to the first of these entities.

Returns the size of the block of data pointed to by the return value of getBody. The analyzer and event processing pipeline should ensure that processing is confined to the storage defined by getBody and getBodySize or else the results are not well defined.

If the underlying data acquisition system has run numbers that can be gotten from the data (presumably in data towards the start of an event file), this is expected to return the run number of the data set currently being analyzed.

Data acquisition systems may not make it possible to determine the run number from the data. In that case this method should just return some value such as UINT_MAX.

Returns the number of entities present in the current item. For scaler data this is, by convention, the number of scalers present. For event data this is the number of events in the block of data defined by getBody and getBodySize.

For data acquisition systems in which it's possible to extract an event number, or buffer number, this is expected to return that number. SpecTcl's GUI's use this information to attempt to provide information about the fraction of events analyzed by the online system.

If the underlying DAQ system does not provide this we recommend returning the number of physics triggers seen. This will result in an analysis fraction of 1.0 which while wrong, at least does not result in program failure (e.g. divide by zero).

NSCLDAQ 8 and earlier provide a buffer sequence number and that is used. NSCLDAQ 10 and later emit periodic trigger count records. The number of triggers in the most recent trigger count record is returne by those buffer decoders.

In CAMAC based system that provide masks of the LAMS seen in the crates involved in an event, this provides the number of LAM masks present. This is supplied by NSCLDAQ 8 and earlier but, as non CAMAC systems became the rule rapidly became obsolete.

If your DAQ system is not able to provide this just return 0.

In some event formats, Readout is driven by some trigger pattern register. In those systems, this is supposed to return the number of pattern register items each event will have (as the decoding of the event may depend on knowing this).

This value is also increasingly obsolete and, you may retrun 0 if the DAQ system you are using (NSCLDAQ 10.0 and later e.g.) cannot supply this information.

Returns the type of entity being processed. This should be a value from buftypes.h

If your DAQ system has packed heterogenous data into 'data units', the main job of the buffer decoder is to break each data unit up into one or more homogenously typed item.

Returns the 16 and 32 bit SpecTcl byte order signatures for the system that sourced the data. SpecTcl uses host and source byte order signatures to not only determine if there is a byte order difference between the two, but to map the transformation required to take data in source format to data in host format.

The 16 bit byte order signature, Signature16 will be writtenwith the value 0x0102 in the byte order of the source system. The Signature32 32 bit signature, on the other hand, will be written with the value 0x01020304 in the byte order of the source system.

The values provided allow SpecTcl to determine how to transform arbitrary byte order differences between 16 and 32 bit values. In practice, there are two byte orderings in use in computer systems throughout the world. Little endian (predominates because it is what Intel uses), and Big endian.

If we view memory as an array of 8 bit bytes, for multi-byte values, little endian systems store the low order bytes in lower addresses while big endian systems store the high order bytes in lower addresses.

Thus the byte-wise representation of 0x0102034, the 32 bit byte order signature for little endian systems is: 0x04, 0x03, 0x02, 0x01 while on a bit endian system, the same signature's byte-wise values are: 0x01, 0x02, 0x03, 0x04.

If the source system provides some indicatiuon of its byte ordering in the data, this method should transform that indicator into the byte order signatures expected by SpecTcl. If not, you have to use your knowledge of the byte ordering of the source system to construct these signatures out of thin air.

For data acquisition systems where runs have a textual title that can be extracted from the event data, this method returns this title. If the data acquisition system has no title or it cannot be extracted from the data we recommend returning an empty string.

Called when a block of data has been read from the data source. nBytes is the number of bytes of data and pBuffer points to the data block. rAnalyzer is the analyzer that's orchestrating the data analysis. This method will typically some methods of this analyzer.

The block of data must be parsed into individual items of specific data types containing individual items as well as blocks of event data. Depending on the data type, the approprite analyzer method(s) must be called.

Called when the buffer decoder is attached to the analyzer. Potentially this is done each time a data source is attached. rAnalyzer is a reference to the analyzer this buffer decoder is being attached to.

Called to detach the buffer decoder from the analyzer.

This should return true if the decoder expects fixed sized blocks and false oterhwsis.

Called when a new event soruce is attached.

Called when a data source is deteached from SpecTcl.

Called when an end file is detected on a data source. For file data sources this indicates the reads of the source have run into the end of the file. For pipe data sources this means either that the pipe program has exited or that it has closed its stdout.

Returns the raw byte at the byte offset specified by offset into the buffer on which the object was constructed.

Returns the translated 16 bit item at the byte offset specified by offset. The method invokes the virtual method GetBlock which is implemented in concrete classes and does the actual byte re-ordering if needed.

Returns the translated 32 bit item at the byte offset specified by offset. The method invokes the virtual method GetBlock which is implemented in concrete classes to do the actual byte-reordering.

The base class contains a pointer to the storage for the buffer being operated on by concrete classes. This returns a pointer to that buffer.

Replaces the pointer to the buffer operated on by the object with pBuffer.

Gets a block of data at the byte offset offset from the start of the buffer into. pItem. The block gotten is size bytes long. For swapping translators, the bytes from the buffer are reversed. This makes this method suitable for fetching multi-byte objects of 'normal' size like 16 bit, 32, or 64 bit integers.

Given an arbitrary 32 bit item, value, known to be in the source system byte ordering, returns it byte translated to the calling host.

Given the 64 bit value known to be in the source byte order representation, returns it translated into the calling host representation.