Warning, /jana2/docs/howto/group-events.md is written in an unsupported language. File is not indexed.
0001
0002 # Group events <!-- {docsify-ignore-all} -->
0003
0004 ## Detect when a group of events has finished
0005
0006 Sometimes it is necessary to organize events into groups, process the events the usual way, but then notify
0007 some component whenever a group has completely finished. The original motivating example for this was EPICS data,
0008 which was maintained as a bundle of shared state. Whenever updates arrived, JANA1 would emit a 'barrier event'
0009 which would stop the data flow until all in-flight events completed, so that preceding events could only read the old
0010 state and subsequent events could only read the new state. [We now recommend EPICS data be handled differently.](howto_epicsdata)
0011 Nevertheless this pattern still occasionally comes into play.
0012
0013 One example is a JEventProcessor which writes statistics for the previous run every time the run number changes.
0014 This is trickier than it first appears because events may arrive out of order. The JEventProcessor can easily maintain
0015 a set of run numbers it has already seen, but it won't know when it has seen all of the events for a given run number.
0016 For that it needs an additional piece of information: the number of events emitted with that run number.
0017 Complicating things further, this information needs to be read and modified by both the JEventSource and the JEventProcessor.
0018
0019 Our current recommendation is a `JService` called `JEventGroupManager`. This is designed to be used as follows:
0020
0021 1. A JEventSource should keep a pointer to the current JEventGroup, which it obtains through the JEventGroupManager.
0022 Groups are given a unique id, which
0023
0024 2. Whenever the JEventSource emits a new event, it should insert the JEventGroup into the JEvent. The event is
0025 now tagged as belonging to that group.
0026
0027 3. When the JEventSource moves on to the next group, e.g. if the run number changed, it should close out the old group
0028 by calling JEventGroup::CloseGroup(). The group needs to be closed before it will report itself as finished, even
0029 if there are no events still in-flight.
0030
0031 4. A JEventProcessor should retrieve the JEventGroup object by calling JEvent::Get. It should report that an event is
0032 finished by calling JEventGroup::FinishEvent. Please only call this once; although we could make JEventGroup robust
0033 against repeated calls, it would add some overhead.
0034
0035 5. A JEventSource or JEventProcessor (or technically anything whose lifespan is enclosed by the lifespan of JServices)
0036 may then test whether this is the last event in its group by calling JEventGroup::IsGroupFinished(). A blocking version,
0037 JEventGroup::WaitUntilGroupFinished(), is also provided. This mechanism allows relatively arbitrary hooks into the
0038 event stream.
0039
0040
0041
