Usage notes for default message handlers - September 2011

15-Sep-2011, KAB - I've just some committed changes to the NovaRunControlClient package, and these notes are intended to describe the new features.


The goal was to ensure that Run Control could expect to receive replies from all processes in the DAQ system, independent of which message it sent. And, we wanted to accomplish this without asking individual subsystem developers to add handlers for all RC messages in their code.

The solution was to modify the RunControlReceiver class to take care of this.

Going forward, the following RC messages will have default handlers installed by the RunControlReceiver class:
  • LoadConnectionsConfiguration
  • MakeConnections
  • LoadHardwareConfiguration
  • ConfigureHardware
  • LoadRunConfiguration
  • ConfigureRun
  • BeginRun
  • AbortRun
  • PauseRun
  • ResumeRun
  • StopRun
  • BreakConnections
The following messages will not have default handlers, for the given reasons:
  • EstablishPartition - applications need to define this one, if only to specify which real-partition messages they want to listen to
  • StatusRequest - applications should reply to this explicitly so that they can return a meaningful status code
  • DetachFromPartition - applications need to handle this explicitly, if only to disconnect the message handlers that they have installed
  • PrepareXYZConfiguration - these seem specific to RC/CfgMgr communication
  • BeginNewSubrun/RolloverRun - these seem specific to RC/DL communication
Some of the features of the modified RunControlReceiver class:
  • default handlers are over-ridden by application-specified handlers
  • multiple application-specified handlers can still be specified for a given message (unlikely, but supported)
  • it is safe to use multiple RunControlReceiver instances in an application - only one will install default handlers
  • the reply to RunControl has a special status message when it is sent by a default message handler (message = "Success (default handler)" instead of just "Success")
  • if you set the RMS_MESSAGE_CLIENT_DEBUG environmental variable to 1 before running your application, you'll enable debug messages that show which handlers are being installed (and possibly over-ridden)
  • if you want to disable the creation of default message handlers, you can do that by specifying "false" for the "provideDefaultHandlers" argument in the RunControlReceiver constructor