Coding

#Coding How to extend cheetah.

##Overview of threaded hit-finder.

Main loop:

1. myana boilerplate code reads data from single diffraction frame in xtc;

2. data from single frame is stored in freshly allocated workspace memory for a new thread;

3. if new threads are allowed to spawned, spawn a worker thread and hand it frame's data for processing; myana code proceeds to the next frame.

When a worker thread is spawned:

a. worker thread processes frame's data (e.g. darkcal subtraction, pixel masking, gaincal equalization, hit-finding);

b. worker thread decides if frame contains diffraction signal, and records frame's information in a thread-safe manner (e.g. add frame to running sum, write frame's data to HDF5);

c. thread frees its own memory, thread exits and broadcasts that a new thread can be spawned in its place.

##Thread-safe coding

• Global variables and Mutexes (read-operations, write-operations) For each global variable that the threads write to (e.g. the array that stores the powder sum), we need a lock that prevents more than one thread writing to the variable at once. The lock is of type pthread_mutex_t and should be added to the cGlobal class of setup.h. The code where you write to the variable should look like this:

  pthread_mutex_lock(&global->YourMutexVariable); (Your code where you change the value of the global variable); pthread_mutex_unlock(&global->YourMutexVariable);

Please don't reuse locks for different variables. One lock per global variable that we write to.

The mutex variables are initialised in setup.cpp in the function cGlobal::setup() with the function pthread_mutex_init(). Variables are destroyed in cheetah.cpp in end_job() using pthread_mutex_destroy().

• Thread-level local variables

  How a thread receives data from xtc stream.

  Variables that store data from the xtc stream are defined in worker.h in the struct tThreadInfo. If you read a new variable from the xtc, define the new variable here. In order to get some information from the xtc you need to call the appropriate myana functions (which probably won't be trivial).

• Maintaining a certain number of threads

  Traffic cop model. Letting threads exit properly. How many threads should one use?

##Adding your own modules ###Adding a parameter to the input file In setup.h :

Add the variable to cGobal class in the the setup.h file

In setup.cpp :

Add the default setting of the variable to cGlobal::defaultConfiguration(void)

Add the name to the ini parser cGlobal::parseConfigTag(char *tag, char *value). Note that all input tags are in lowercase (because the ini file tag is converted to lower case before parsing).

The variable can now be accessed in the worker function (or anlysis modules) as global->YourVariableName

###Framework for adding global variables In setup.h :

Add the variable to cGobal class in the the setup.h file

The variable can now be accessed in the worker function (or anlysis modules) as global->YourVariableName

If you intend to write to the global variable see the section Thread-safe Coding

Adding your module

To add a new analysis function to the worker() function (e.g. streak finding), then

Create new files YourModule.cpp and YourModule.h. Copy the comment preamble and the #includes from another module like hitfinding.cpp/.h.

Add #include "YourModule.h" at the start of the worker.cpp file. And insert a call to your function in the worker() function in worker.cpp

Add a line to the Makefile to compile your new file. Copy what is done for hitfinder.cpp

###Framework for adding thread-level local variables ###Universal INI file for parameter input ###An example: triggering intensities off certain pixel regions.

##Auxiliaries (maybe?) ###Working with HDF5 containers.

• h5ls
• hdfviewer

##Gaincal This is implemented as a multiplication. There is an option “invertGain” which allows the gain to be inverted if in fact we need to divide.