spectrodaq client application framework

0.2

Author:

Ron Fox

Eric Kasten (Spectrodaq)

Jason Venema

Introduction

This documentation describes an application framework which simplifies the process of writing clients to spectrodaq, the NSCL data acquisition and distribution system. This set of web pages provides general documenation as well as reference information for this class library.

Getting Started

To write programs under the client application framework you will need to know:

1. How to subclass the DAQROCNode class.
2. How to Write a Makefile to build your program.

Writing a subclass of DAQROCNode

DAQROCNode (DAQ Readout Controller Node) is the base class from which all spectrodaq clients are derived.

#include <iostream.h>
#include <spectrodaq.h>
#include <SpectroFramework.h>

class MyClass : public DAQROCNode
{
protected:
  int operator()(int argc, char** pargv);
};

int
MyClass::operator()(int argc, char** pargv)
{
  cout << "Hello World." << endl;
}

MyClass theApp;

is a minimal sample Spectrodaq client which uses the framework.

This example includes the following headers:

• <spectrodaq.h> - header which defines the spectrodaq client interface classes.
• <SpectroFramework.h> - header which defines the classes in the application framwork.
• <iostream.h> - Which defines classes in the C++ I/O subsystem.

The bulk of the program is the definition of a class: MyClass which extends DAQROCNode, definining and implementing the operator() member function. This member function is called when Spectrodaq has initialized and is ready to run application code. The implementation of that function simply puts the message "Hello World" to stdout.

The final line of the example declares an instance of MyClass. This instance is the application object which will actually be run by spectrodaq.

This example shows the general pattern which you must follow to write Spectrodaq clients:

• Include the necessary headers (<spectrodaq.h> <SpectroFramework.h> at a minimum.
• Write a subclass to DAQROCNode which defines the behavior of your application. The entry point to the program will be the operator() member function which has the same signature as the main function. be sure not to provide an implementation of main() as that's provided by the spectrodaq client libraries.
• Declare an instance of this class to provide spectrodaq with an application object to run.

Writing a Makefile for framework programs.

Writing a Makefile to build your application requires:

• Obtaining the compilation and link flags needed by spectrodaq.
• Listing the dependencies between modules, and build rules needed to get from indenendent to dependent half of these dependencies.

For the example in the previous section, the resulting Makefile might look like

SPECTRO_FLAGS=$(shell /opt/spectrodaq/bin/spectrodaq-conf --cflags)
SPECTRO_LDFLAGS=$(shell /opt/spectrodaq/bin/spectrodaq-conf --libs)

CXXFLAGS=$(SPECTRO_FLAGS) -I/opt/daq/Include -I/usr/X11/include
LDFLAGS = $(SPECTRO_LDFLAGS) -L /opt/daq/Lib -L/usr/X11/lib \
         -lEventFramework -ltk -ltcl -lm -lXm -lXt

minimal: minimal.o
        g++ -o minimal $< $(LDFLAGS)

minimal.o: minimal.cpp
        g++ -c $< $(CXXFLAGS) -ltcl 

The first four macro definitions group together the compilation and load flags needed by spectrodaq and the framework into two macros CXXFLAGS (compile flags), and LDFLAGS (loader flags).

Two dependencies describe how to build the object from the source, and the executable from the object. Note that it may also be wise to include the -ggdb flag in LDFLAGS so that you can use the gdb debugger.

General concepts.

The following is a list of general concepts which are used by the event framework and should be understood.

• Subclassing a base class to extend or provide functionality.
• Object registries and object naming.
• Event driven programming.
• TCP/IP client/server programming with sockets.
• The events which are understood by the application framework:
  1. Location monitors: Low latency monitoring of a volatile memory location.
  2. File descriptor events: Events which occur when a file descriptor is readable or writable or has some other special condition (exception) pending.
  3. Spectrodaq Buffer Events Events which occur when a spectrodaq makes a buffer available to the application along a link.
  4. Server accept events: Events which occur when a TCP/IP server receives a connection request from a client.
  5. Server Instance events: Events which occur when an instance of a TCP/IP server connected to an active client receives a request from the client.

Guest event loops including:

1. Synchronization of guest event loops with other framework code.
2. Tcl/Tk guest event loops
3. X11/Xt guest event loops

The Configuration subsystem.

---