nscl_logo_small.gif (2463 bytes)

Writing Xamine Restart Handlers.

HH00706_.wmf (6530 bytes)

SpecTcl Home  General Information User Guide Programmer's Guide Obtaining and Installing

This document describes how to detect when Xamine restarts and to execute application speficic code when that happens.


Now that SpecTcl implements interfaces to the Xamine client button boxes (see Xamine client button programming), SpecTcl applications may perform application specific actions at initialization time for Xamine. If Xamine exits (either through user action or as the result of a defect), SpecTcl detects the exit and restarts a new instance of Xamine.

Without a mechanism to allow the user to detect Xamine restarts, SpecTcl applications would not be able to recreate the client button box when Xamine restarts. This would have the effect or stripping the application of some of its functionality at an unpredictable time. This is clearly undesirable.

In order to deal with this issue, SpecTcl 3.2 and later include a facility for registering one or more event handlers that will execute when SpecTcl restarts Xamine. This would allow an application to re-create any Xamine client buttons displayed when the previous instance of Xamine exited.

Top Programmer's guide

How it works

When SpecTcl initializes, it starts Xamine in code located in the base class of the class you create in MySpecTclApp.cpp. At that time, it establishes a Tcl file handler to inform the Tcl/Tk event loop when the pipe through which Xamine sends gates becomes readable. When this pipe becomes readable, code in an object of type CXamineEventHandler is executed to process the event.

If Xamine exits, it will close its end of the pipe. When this happens, SpecTcl will see the pipe as readable. When the pipe becomes readable, SpecTcl tests for the presence of the Xamine process. If this test fails, SpecTcl executes the Xamine restart code. This restart code now has hooks that allow the application programmer to install user written handlers to be called after Xamine has been restarted.

Let's get down to the specifics of the implementation that you need to know to use it.

Top Programmer's guide

A sample use

This section shows how to modify the sample button code in SpecTcl's interface to Xamine Client Buttons so that the button box and its button gets rebuilt whenever Xamine is restarted. Take a little time to familiarize yourself with that example.

No modifications will be needed to the CFitButton class. We will instead:

The definition and implementation of our restart handler is:

class CButtonBoxSetup : public CXamineEventHandler::CRestartHandler
  CFitButton* m_pButtons;
  CButtonBoxSetup() : m_pButtons(0) {}
  virtual void operator()() {
    delete m_pButtons;
    m_pButtons = new CFitButton(myApp.getXamineEvents());
This code is added to MySpecTclApp.cpp so that it has access to app the instance of CMySpecTclApp that file creates.

The class takes advantage of the fact that the delete statement can be given a null pointer, and that doing so is a no-op. Therefore the constructor initializes the m_pButtons member to 0 (null), so that operator() does not need to worry about whether or not the button has already been created.

The only other thing we need to do is modify CMySpecTclApp::SelectDisplayer

CMySpecTclApp::SelectDisplayer(UInt_t nDisplaySize, CHistogrammer& rHistogrammer)  
  CTclGrammerApp::SelectDisplayer(nDisplaySize, rHistogrammer);

  // Hook in the button box and ensure that it gets re-hooked on exit.

  CXamineEventHandler* pEventHandler = getXamineEvents();
  CButtonBoxSetup*     pSetup        = new CButtonBoxSetup;
  (*pSetup)();			// Get it set up the first time.

The line (*pSetup)() manually invokes the handler function causing the creation of the initial button box and button. After that, whenever SpecTcl restarts, the handler code will automatically recreate the button box and button.

Top Programmer's guide
Last modified: Fri Apr 6 12:05:03 EDT 2007