Introduction to using the Run Control Receiver » History » Version 2

Kurt Biery, 08/30/2011 01:09 PM

1 1 Kurt Biery
h1. Introduction to using the Run Control Receiver
2 1 Kurt Biery
3 1 Kurt Biery
13-May-2010, KAB
4 1 Kurt Biery
5 1 Kurt Biery
The basic idea behind the Run Control Receiver class is that you can specify callbacks that get invoked when Run Control messages arrive.  The receiving of the messages, the sending of any replies, and the management of the objects that do those things is handled for you.
6 1 Kurt Biery
7 1 Kurt Biery
The following are some sample steps for making use of a RunControlReceiver in your application:
8 1 Kurt Biery
* create a RunControlReceiver instance early in your application's lifecycle and store a handle to that instance for later use
9 1 Kurt Biery
** the two arguments to the RunControlReceiver constructor are the name of your application and a list of "RMS broadcast" targets that you want to listen to
10 1 Kurt Biery
** all of these strings should match the ones that are used to send messages to your application
11 1 Kurt Biery
** the application name is the RMS "target" that Run Control will use to send messages directly to your application (e.g. "dcm000" or "bufferNodeEVB000")  If you are uncertain about what names should be used, we should discuss them as a group.
12 1 Kurt Biery
** "RMS broadcast" targets are strings that Run Control may use to send messages to groups of applications.  For example, an "allDCMs" target name could be used to send messages to all DCMs in a partition.
13 1 Kurt Biery
* add a listener to the RunControlReceiver instance to handle the message from Run Control that tells your application which partition it belongs to
14 1 Kurt Biery
** obviously, this also should be done early in your application's life cycle
15 1 Kurt Biery
** the signatures of the addListener methods are the following:
16 1 Kurt Biery
*** <code>RunControlReceiver::addListener<MSGTYPE, LSTNR, REPLYTYPE>(int partitionNumber, LSNTR* listener);</code>
17 1 Kurt Biery
*** <code>RunControlReceiver::addListener<MSGTYPE, LSTNR, REPLYTYPE>(int partitionNumber, boost::shared_ptr<LSNTR> listener);</code>
18 1 Kurt Biery
** you can use either method, or both, for specifying your callback routines.  The first is probably most useful if you want to specify "this" as the listener pointer.  (That is, the class that adds a callback to the RunControlReceiver could specify itself as the listener.  Of course, in that case, that class would need to implement the appropriate callback method.)  The second signature can be used if you want to create separate classes (and objects) to handle the message processing.
19 1 Kurt Biery
** currently, I believe that <code>runcontrolmessages::EstablishPartitionRequest</code> should be used as the message type (MSGTYPE) for receiving a partition assignment and <code>runcontrolmessages::EstablishPartitionResponse</code> should be used for the reply type (REPLYTYPE) to respond to a partition assignment
20 1 Kurt Biery
** the "null partition" (partition number -1) should be used for the partition number in this case.  Please use the <code>gov::fnal::cd::rms::base::RmsDestination::NULL_PARTITION</code> constant for the null partition number, when possible.
21 1 Kurt Biery
* when an EstablishPartitionRequest is received, do whatever processing is appropriate to your application (of course), and also add listeners to the RunControlReceiver using the partition number that you have been assigned
22 1 Kurt Biery
* when a ReleaseFromPartitionRequest message is received, do whatever processing is appropriate and also tell the RunControlReceiver to disconnect from the partition
23 1 Kurt Biery
24 1 Kurt Biery
25 1 Kurt Biery
* each of your listeners must have a method with a signature like the following:
26 1 Kurt Biery
** <code>boost::shared_ptr<REPLYTYPE> handleMessage(boost::shared_ptr<MSGTYPE> message);</code>
27 1 Kurt Biery
* if your callback returns a non-empty shared pointer (to a response message), then that message will be automatically sent back to Run Control for you by the RunControlReceiver
28 1 Kurt Biery
* you should add the following line to the bottom of your SRT GNUmakefile to include the needed headers and libraries for using the RunControlReceiver:
29 1 Kurt Biery
** <code>include SoftRelTools/</code>
30 1 Kurt Biery
31 1 Kurt Biery
Example code:
32 1 Kurt Biery
* see attached SampleDCM.h/cpp files (latest and greatest versions are available from "here":
33 1 Kurt Biery
* only sample callbacks are provided in the SampleDCM code.  Your application will probably want to listen for every Run Control message.
34 1 Kurt Biery
35 1 Kurt Biery
Command-line utility for sending Run Control messages:
36 1 Kurt Biery
* the source code is in the "NovaRunControlClient/cxx/test area": (see <code></code>)
37 1 Kurt Biery
* to run the application, simply type <code>'sendRunControlMessage <arguments>'</code> (type <code>'sendRunControlMessage'</code> with no arguments to see the usage hints)
38 1 Kurt Biery
39 1 Kurt Biery
Sample steps to see the sendRunControlMessage application in action:
40 1 Kurt Biery
* create a personal ospl.xml file as described "here":, if needed
41 1 Kurt Biery
* in one shell window,
42 1 Kurt Biery
** <code>source /nova/novadaq/setup/ -r development</code> (or current)
43 1 Kurt Biery
** <code>export OSPL_URI=file://<yourWorkArea>/ospl.xml</code>
44 1 Kurt Biery
** <code>ospl start</code>
45 1 Kurt Biery
** <code>SampleDCMMain dcm000</code>
46 1 Kurt Biery
* in a second shell window,
47 1 Kurt Biery
** <code>source /nova/novadaq/setup/ -r development</code> (or current)
48 1 Kurt Biery
** <code>export OSPL_URI=file://<yourWorkArea>/ospl.xml</code>
49 1 Kurt Biery
** <code>sendRunControlMessage -1 establishpartition 0</code> (the first argument is a negative one, not a dash-el)
50 1 Kurt Biery
** <code>sendRunControlMessage 0 beginrun 100</code>
51 1 Kurt Biery
** <code>sendRunControlMessage 0 stoprun</code>
52 1 Kurt Biery
** <code>sendRunControlMessage 0 releasefrompartition</code>
53 1 Kurt Biery
* back in the first shell window,
54 1 Kurt Biery
** <code>ctrl-c</code> (to stop the SampleDCMMain)
55 1 Kurt Biery
** <code>ospl stop</code> (to stop the DDS daemon)
56 1 Kurt Biery
57 1 Kurt Biery
Run Control messages:
58 1 Kurt Biery
* to see the full list of Run Control messages that have been defined, see the "RunControlMessages.idl file in CVS":
59 1 Kurt Biery
* the sendRunControlMessage application may not have all of the official messages included.  Invoke it without any arguments to see which ones are included.  And feel free to add any new ones that you're anxious to see included!
60 2 Kurt Biery
61 2 Kurt Biery
* SampleDCM.h:
62 2 Kurt Biery
* SampleDCM.cpp: