Locking in JANA

Nested Locks

Overview

• Don't EVER acquire a lock from within another lock. This is extremely dangerous, and can easily result in deadlock: program hangs, because two threads are waiting for each other to unlock.
  • If you think you need to do a nested lock, you are probably doing it wrong.
  • If you absolutely must have nested lock, be sure to acquire & release the locks in the exact same order everywhere. This is of course, very difficult to guarantee, because once someone starts doing it one plugin, someone else may have a different convention in another plugin ...

Avoiding Nested Locks

• To avoid nested locking, when you're in a lock, never:
  • Query JANA for calibration constants
  • Query JANA for global parameters
  • Query JANA for objects (JEventLoop::Get()) //This is also potentially incredibly slow
  • Call the event writers to save your EVIO skims, REST files, ROOT trees, etc.

Plugin Processor Variables

Basics

• Do not place use any locks in JEventProcessor::init() or ::fini(): they are unnecessary, and a waste of time.
  • JANA is guaranteed to be single-threaded in these functions.

• Do not use or modify any global variables, unless you are in a lock.
  • Or even better, just avoid them at all possible. It's terrible programming practice.

Class members

• Do NOT use or modify any class member-variables that you define for your JEventProcessor (i.e. in header file), unless you are in a lock (or in init(), fini()). These variables can be modified by other threads. This locking can be done via:

LockState(); //ACQUIRE PROCESSOR LOCK
UnlockState(); //RELEASE PROCESSOR LOCK

• For data updated in brun() and read in evnt(), it is sometimes unfeasible to work around this, such as when working with calibration constants. As long as the run number doesn't change, this should still be OK (they should just be overwriting the same value).
  • However, running your program over data with two different runs may result in unpredictable behavior.

• Just to be safe, have as few class member variables as possible, and reduce the amount of time spent in locks. In other words, use function-scope (local) variables instead.
  • Where possible of course. E.g. you can't avoid it with histograms, but you need to lock to fill those anyway.

Creating Histograms or TTrees

• If you are creating histograms or trees (outside of JEventProcessor::init() or ::fini()): Use the global ROOT JANA lock functions below.
  • This is because they depend on gDirectory being constant.

japp->RootWriteLock(); //ACQUIRE ROOT LOCK
japp->RootUnLock(); //RELEASE ROOT LOCK

Filling Histograms

• If you are filling histograms, you do NOT need to grab the global ROOT JANA lock functions. Try to instead grab a lock with a smaller scope, so that other threads can write to other histograms that don't interfere with yours.
  • In you are directly in the plugin processor, there's a special function to do this, that locks for the current plugin only. It is:

japp->RootFillLock(this); //ACQUIRE ROOT FILL LOCK //this: JEventProcessor pointer
japp->RootFillUnLock(this); //RELEASE ROOT FILL LOCK //this: JEventProcessor pointer

Filling TTrees

hd_root.root

• If you are filling TTrees to the global ROOT file (i.e. hd_root.root), write to the TTrees with the global ROOT JANA lock functions below:
  • This is because TTree::Fill() periodically writes to the file, modifying it.

japp->RootWriteLock(); //ACQUIRE ROOT LOCK
japp->RootUnLock(); //RELEASE ROOT LOCK

Other output files

• If you are filling TTrees to a local ROOT file (i.e. NOT hd_root.root), you do NOT need to grab the global ROOT JANA lock functions. Try to instead grab a lock with a smaller scope, so that other threads can write to other trees that don't interfere with yours.
  • Grab the same for every tree that is written to the same output file. This is because TTree::Fill() periodically writes to the file, modifying it.
  • This can be done with:

japp->WriteLock("MyFileName"); //ACQUIRE FILE LOCK
japp->Unlock("MyFileName"); //RELEASE FILE LOCK