Major classes and objects

Major classes and objects

Several majore classes and objects (instances) of those classes are described in this section. Knowing your way around these classes helps you both to understand the way the readout program works as well as how to extend it. This section will also describe:

• How to locate the key objects.
• Major member functions for each of the classes.

For detailed reference information on the software, see the Doxygen documentation of they software referenced in Reference documentation for the internals of Readout.

The figure below shows the major classes and their relationships:

CReadoutMain is a singleton object. Its operator() gets initial control. Note that usually, you will override this class to tailor its virtual functions (see Modifiying the Readout skeleton). CReadoutMain's member functions allow you to get pointers to the instances of the classes it contains:

CTimer& getClock() Returns a reference to the clock manager. The clock manager runs when the run is active and is a scheduler of timed events.

CRunState* getRunState() Returns a pointer to the run state object. The run state object encapsulates the state machine that describes the current state of the run and allowed state transitions. See: System State Machine.

CExperiment* getExperiment() Returns a pointer to the experiment. The experiment object houses all of the functionality of the experiment itself, divorced from the flow control, command processing and so forth.

CInterpreterShell* getInterpreter() Returns a pointer to the Interpreter shell object. This will actually be either a CTkInterpreterShell or a CTclInterpreterShell. Each of these classes doubly inherits from CInterpreterShell and from CInterpreterStartup. CInterpreterStartup gives Interpreter shells the behavior of a guest event loop running Tcl or Tk. While CInterpreterShell gives the property of holding a core set of common interpreter extensions regardless of whether or not the underlying interpreter is a Tcl or Tk interpreter.

---

CTimer is a class that manages timed events. The CReadoutMain class/objects maintains one of these for use by the experiment. When the run is active, this timer is "turned on", and starts scheduling events. Normally the experiment will register a scaler trigger that will fire periodically to read out run time scalers. Major function of CTimer are:

void Start(int ms, bool reset=false) Enables the timer to schedule events. ms is the timer resolution in milliseconds. The timer will wake up every ms and check for events that have come due. reset should be set true if you want the object's concept of elapsed time to be reset to zero.

void Stop() Disables the timer. The timer will no longer schedule events.

int GetElapsedTime() Returns the elapsed time in milliseconds.

void EstablishEvent(CTimedEvent& rEvent Adds the object rEvent to the list of items that the timer will periodically schedule.

---

CRunState Run state objects encapsulate the state machine that defines legal transitions between states of the run and the current state as well. Major functions are:

CRunState::RunState getState() Returns the current state. The CRunState::RunState data type is an enumerated data type with values: Inactive, Active, or Paused.

bool Allowed(CRunState::RunState NewState Returns true if it is now legal to make a transition to the state NewState, false if not. note as well that the state transition functions described below also throw a CBadTransition exception if the transition is not legal.

void Begin() Transition to the Active state.

void End() Transition to the Inactive state.

void Pause() Transition from Active to Paused.

void Resume() Transition from Paused to Active.

string getStateName() Returns a string version of the name of the state.

---

CExperiment is a class that contains configuration information and functions relelvant to the experiment itself. Major member functions include:

void AddEventSegment(CEventSegment* pSegment) Adds an event segment to the readout. For more about event segments, see: How to structure your readout.

void RemoveEventSegment(CEventSegment* pSegment) Removes an event segment from the readout. For more about event segments, see: How to structure your readout.

void EstablishTrigger(CTrigger* pTrigger) Replaces the current trigger object with a new one. Trigger modules supply a mechanism to watch for the event readout trigger. For more about the CTrigger class, see: Specifying a trigger.

void EstablishBusy(CBusy* pBusy) Replaces the current Busy management object with a new one. The CBusy object provides a mechanism to manage the computer busy signal required by experimental electronics. For more about the CBusy class, see: Specifying a busy manager.

void AddScalerModule(CScaler* pScaler) Adds a scaler module to the list of modules that will be read on a scaler trigger. Note that CScalerBank is derived from CScaler so you can hierarchically organize the readout.

void RemoveScalerModule(CScaler* pScaler) Removes an existing scaler module from the scaler readout.

---

CInterpreterShell encapsulates the Tcl or Tk interpreter relevant to the readout system. Complete coverage of the Tcl/Tk interpreter structure will be given in several sections of Tailoring the software. The main functions you will need is CInterpreterCore* getInterpreterCore() which gets the interpreter core. The interpreter core object is the set of extensions that Readout has layered on to the base Tcl/or Tk interpreter, and CTCLInterpreter& Interp() which gets the interpreter object itself.

---

CReaper monitors threads that must be deleted on exit. Threads are normally objects of type derived from CEvent. Deleting dynamically created CEvent objects is problematic as it must be done by some `force' outside the thread itself. CReaper is a singleton class that can be used to ensure that dynamically created thread objects are deleted on exit. Key member functions are:

CReaper* getInstance() Returns a pointer to the single reaper object.

void Add(CEvent* pEvent) Called by a thread on entry to add itself to the reapers list of monitored processes.

A typical sequence of code might be:

		  CReaper::getInstance()->Add(this);   // Auto delete on exit.
	       

Major classes and objects