Merge remote-tracking branch 'JeffersonLab/master' into romanov_docs

JeffersonLab · Nov 20, 2024 · 59abb87 · 59abb87
2 parents c300319 + 9fcda10
commit 59abb87
Show file tree

Hide file tree

Showing 160 changed files with 5,537 additions and 7,429 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.16)
 cmake_policy(SET CMP0074 NEW) # find_package() uses <PackageName>_ROOT implicit hints
 
-project(jana2 VERSION 2.3.1)
+project(jana2 VERSION 2.3.3)
 
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)   # Enable -fPIC for all targets
 
@@ -220,6 +220,9 @@ add_subdirectory(src/python)
 install(DIRECTORY scripts/ DESTINATION bin FILES_MATCHING PATTERN "jana-*.py"
         PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ WORLD_READ WORLD_EXECUTE)
 
+    install(FILES "scripts/jana-status.sh" RENAME "jana-status" DESTINATION "bin"
+        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ WORLD_READ WORLD_EXECUTE)
+
 include(${CMAKE_SOURCE_DIR}/cmake/MakeConfig.cmake)
 include(${CMAKE_SOURCE_DIR}/cmake/MakeJanaThis.cmake)
 include(${CMAKE_SOURCE_DIR}/cmake/MakeJVersionH.cmake)
diff --git a/cmake/AddJanaPlugin.cmake b/cmake/AddJanaPlugin.cmake
@@ -2,12 +2,18 @@
 macro(add_jana_plugin plugin_name)
 
     # Parse remaining arguments
-    set(options)
+    set(options LINK_SHARED)
     set(oneValueArgs EXPORT)
     set(multiValueArgs SOURCES PUBLIC_HEADER TESTS)
 
     cmake_parse_arguments(PLUGIN "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
+    if (LINK_SHARED)
+        set(PLUGIN_JANA_LIB jana2_shared_lib)
+    else()
+        set(PLUGIN_JANA_LIB jana2_static_lib)
+    endif()
+
     if (NOT PLUGIN_SOURCES AND NOT PLUGIN_PUBLIC_HEADER AND NOT PLUGIN_TESTS)
         # If no arguments provided, glob everything
         file(GLOB HEADERS_IN_SUBDIR "include/*")
@@ -64,7 +70,7 @@ macro(add_jana_plugin plugin_name)
         INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib;${CMAKE_INSTALL_PREFIX}/lib/${INSTALL_NAMESPACE}/plugins"
     )
 
-    target_link_libraries(${plugin_name} PUBLIC "${JANA_NAMESPACE}jana2_static_lib")
+    target_link_libraries(${plugin_name} PUBLIC "${JANA_NAMESPACE}${PLUGIN_JANA_LIB}")
 
     # Handle public headers
     if (PLUGIN_PUBLIC_HEADER)

diff --git a/cmake/JANAConfig.cmake.in b/cmake/JANAConfig.cmake.in
@@ -32,4 +32,9 @@ set(JANA_INCLUDE_DIR ${JANA_INCLUDE_DIRS})
 set(JANA_LIBRARY ${JANA_LIBRARIES}) 
 set(JANA_LIB ${JANA_LIBRARIES}) 
 
+# Include JANA cmake helper macros
+include("${CMAKE_CURRENT_LIST_DIR}/AddJanaPlugin.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/AddJanaLibrary.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/AddJanaTest.cmake")
+
 
diff --git a/cmake/MakeConfig.cmake b/cmake/MakeConfig.cmake
@@ -27,5 +27,9 @@ install(FILES "${CMAKE_CURRENT_BINARY_DIR}/cmake/JANAConfigVersion.cmake"
 install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/cmake/AddJanaPlugin.cmake"
     DESTINATION "lib/JANA/cmake")
 
+install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/cmake/AddJanaLibrary.cmake"
+    DESTINATION "lib/JANA/cmake")
 
+install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/cmake/AddJanaTest.cmake"
+    DESTINATION "lib/JANA/cmake")
 
diff --git a/docs/Download.md b/docs/Download.md
@@ -10,6 +10,62 @@
 - [See online doxygen documentation](http://www.jlab.org/JANA/jana_doc_latest/index.html)
 - [Download doxygen documentation](http://www.jlab.org/JANA/jana_doc_latest.tar.gz)
 
+### 2.3.3
+
+#### Bugfixes
+* Fix problem with user-defined factory generators (#366)
+* JEventProcessor::Process() called before BeginRun() (#367)
+* Lock overwrite in RootFillLock() (#369)
+* JFactory::Finish() is called (#377)
+
+#### Features
+* JTopologyBuilder supports topologies with arbitrarily nested levels (#346)
+* Barrier events are back (#371)
+
+#### Refactoring
+* Improved log output (#368)
+* JTest uses new-style component interfaces (#374)
+* JArrows now fire on individual events (#375, #378)
+
+- [See release on GitHub](https://github.com/JeffersonLab/JANA2/releases/tag/v2.3.3)
+
+### 2.3.2
+This release includes the following:
+
+#### Features
+- Added a simple `JWiringService` which can be used to wire `JOmniFactories` via a TOML file. (#353, #363)
+- Added `add_jana_plugin`, `add_jana_library`, and `add_jana_test` CMake macros (#364)
+
+#### Bugfixes
+- A multithreading bug in `JEventProcessor` has been fixed.
+- `JFactory::Create` now checks `JEventSource::GetObjects` (#361)
+- `JPluginLoader` no longer loads plugins twice in certain cases (#343)
+- `JParameterManager::FilterParameters` marks parameters as 'used', thereby avoiding spurious 'unused parameter' warnings. (#331)
+- `JTypeInfo::to_string_with_si_prefix` generates the correct SI prefix in certain cases (#348)
+
+#### Refactoring
+- Plugins and their headers are now installed to a directory that doesn't conflict with a system install (#330)
+- `JPluginLoader` has been extensively rewritten (#339)
+- `JCsvWriter` has been moved into `examples` (#350)
+- JANA's internal performance testing RNG has been refactored to be more reproducible, and to avoid ASAN violations. (#315)
+- `JPodioExample` has been split into several reusable examples. (#352)
+- Code was moved from `Omni` and `Status` into `Components`, making the layered architecture clearer (#351)
+- Documentation has been overhauled, including adding an extensive JANA1-to-JANA2 migration guide (#334, #336, #342, #354, #357, #359)
+- CI testing has been extended (#332, #341)
+
+#### Behavior changes:
+- JANA now has one internal logger, configurable via the `jana:loglevel` parameter. External loggers are now configurable via the `jana:global_loglevel` parameter.
+- Log output has been streamlined: oversized tables are now YAML, and essential information is now logged at `WARN` level. (#362)
+- `JPluginLoader` now stops when a plugin fails to load, rather than continuing searching for another plugin with the same name.
+- `JPluginLoader` no longer accepts paths as part of a valid plugin name
+- `JFactorySet` is no longer silent when the user attempts to include duplicates of the same factory (#343)
+- `JMetadata` is deprecated, to be replaced with `JMultifactory`. (#345)
+- All `JFactories` now call `JEventSource::GetObjects`, not just `JGetObjectsFactory`. (#361)
+
+- [See release on GitHub](https://github.com/JeffersonLab/JANA2/releases/tag/v2.3.2)
+- [See online doxygen documentation](http://www.jlab.org/JANA/jana_doc_2.3.1/index.html)
+- [Download doxygen documentation](http://www.jlab.org/JANA/jana_doc_2.3.1.tar.gz)
+
 ### 2.3.1
 This release fixes a bug which caused the `janadot` plugin to stop producing output. It also drops support for Podio <= 00-17 by replacing the user-provided `PodioTypeMap` with the built-in `PodioT::collection_type`. 
 

diff --git a/docs/doxygen/doxygen_index.md b/docs/doxygen/doxygen_index.md
@@ -30,14 +30,9 @@ This website provides documentation for JANA2 C++ API automatically generated by
 
 ## Internal services
 
-* [JLoggingService](class_j_logging_service.html): Furnish the user with a logger already configured for that particular component
 * [JParameterManager](class_j_parameter_manager.html): Furnish the user with parameters extracted from command line flags and configuration files
 
-## Parallelism engine
+* [JExecutionEngine](class_j_execution_engine.html): Runs the topology. Manages the thread team and the topology status.
 
-* [JProcessingController](class_j_processing_controller.html): The interface which any parallelism engine must adhere to
-* [JArrowProcessingController](class_j_arrow_processing_controller.html): The entry point into the "Arrow" engine
-* [JWorker](class_j_worker.html): Contains the loop for each worker thread, along with startup/shutdown logic and encapsulated worker state.
-* [JScheduler](class_j_scheduler.html): Contains the logic for giving a worker a new assignment
 
 
diff --git a/docs/howto/other-howtos.md b/docs/howto/other-howtos.md
@@ -68,70 +68,67 @@ The following configuration options are used most commonly:
 
 | Name | Type | Description |
 |:-----|:-----|:------------|
-nthreads                  | int     | Size of thread team (Defaults to the number of cores on your machine)
-plugins                   | string  | Comma-separated list of plugin filenames. JANA will look for these on the `$JANA_PLUGIN_PATH`
-plugins_to_ignore         | string  | This removes plugins which had been specified in `plugins`. 
-event_source_type         | string  | Manually override JANA's decision about which JEventSource to use
-jana:nevents              | int     | Limit the number of events each source may emit
-jana:nskip                | int     | Skip processing the first n events from each event source
-jana:extended_report      | bool    | The amount of status information to show while running
-jana:status_fname         | string  | Named pipe for retrieving status information remotely
-
-
-JANA has its own logger. You can control the verbosity of different components using 
-the parameters `log:off`, `log:fatal`, `log:error`, `log:warn`, `log:info`, `log:debug`, and `log:trace`.
-The following example shows how you would increase the verbosity of JPluginLoader and JComponentManager:
-```
-jana -Pplugins=JTest -Plog:debug=JPluginLoader,JComponentManager
-```
+| nthreads                  | int     | Size of thread team (Defaults to the number of cores on your machine) |
+| plugins                   | string  | Comma-separated list of plugin filenames. JANA will look for these on the `$JANA_PLUGIN_PATH` |
+| plugins_to_ignore         | string  | This removes plugins which had been specified in `plugins`. |
+| event_source_type         | string  | Manually specify which JEventSource to use |
+| jana:nevents              | int     | Limit the number of events each source may emit |
+| jana:nskip                | int     | Skip processing the first n events from each event source |
+| jana:status_fname         | string  | Named pipe for retrieving status information remotely |
+| jana:loglevel | string | Set the log level (trace,debug,info,warn,error,fatal,off) for loggers internal to JANA |
+| jana:global_loglevel | string | Set the default log level (trace,debug,info,warn,error,fatal,off) for all loggers |
+| jana:show_ticker          | bool    | Controls whether the status ticker is shown |
+| jana:ticker_interval          | int     | Controls how often the status ticker updates (in ms)  |
+| jana:extended_report       | bool    | Controls whether to show extra details in the status ticker and final report |
+
+JANA automatically provides each component with its own logger. You can control the logging verbosity of individual components
+just like any other parameter. For instance, if your component prefixes its parameters with `BCAL:tracking`,
+you can set its log level to `DEBUG` by setting `BCAL:tracking:loglevel=debug`. You can set the parameter prefix by calling `SetPrefix()`,
+and if you need the logger name to differ from the parameter prefix for any reason, you can override it by calling `SetLoggerName()`.
+
 
 The `JTest` plugin lets you test JANA's performance for different workloads. It simulates a typical reconstruction pipeline with four stages: parsing, disentangling, tracking, and plotting. Parsing and plotting are sequential, whereas disentangling and tracking are parallel. Each stage reads all of the data written during the previous stage. The time spent and bytes written (and random variation thereof) are set using the following parameters:
 
 | Name | Type | Default | Description |
 |:-----|:-----|:------------|:--------|
-jtest:parser_ms | int | 0 | Time spent during parsing
-jtest:parser_spread | int | 0.25 | Spread of time spent during parsing
-jtest:parser_bytes | int | 2000000 | Bytes written during parsing
-jtest:parser_bytes_spread | double | 0.25 | Spread of bytes written during parsing
-jtest:disentangler_ms | int | 20 | Time spent during disentangling
-jtest:disentangler_spread | double | 0.25 | Spread of time spent during disentangling
-jtest:disentangler_bytes | int | 500000 | Bytes written during disentangling
-jtest:disentangler_bytes_spread | double | 0.25 | Spread of bytes written during disentangling
-jtest:tracker_ms | int | 200 | Time spent during tracking
-jtest:tracker_spread | double | 0.25 | Spread of time spent during tracking
-jtest:tracker_bytes | int | 1000 | Bytes written during tracking
-jtest:tracker_bytes_spread | double | 0.25 | Spread of bytes written during tracking
-jtest:plotter_ms | int | 0 | Time spent during plotting
-jtest:plotter_spread | double | 0.25 | Spread of time spent during plotting
-jtest:plotter_bytes | int | 1000 | Bytes written during plotting
-jtest:plotter_bytes_spread | double | 0.25 | Spread of bytes written during plotting
+| jtest:parser:cputime_ms | int | 0 | Time spent during parsing |
+| jtest:parser:cputime_spread | int | 0.25 | Spread of time spent during parsing |
+| jtest:parser:bytes | int | 2000000 | Bytes written during parsing |
+| jtest:parser:bytes_spread | double | 0.25 | Spread of bytes written during parsing |
+| jtest:disentangler:cputime_ms | int | 20 | Time spent during disentangling |
+| jtest:disentangler:cputime_spread | double | 0.25 | Spread of time spent during disentangling |
+| jtest:disentangler:bytes | int | 500000 | Bytes written during disentangling |
+| jtest:disentangler:bytes_spread | double | 0.25 | Spread of bytes written during disentangling |
+| jtest:tracker:cputime_ms | int | 200 | Time spent during tracking |
+| jtest:tracker:cputime_spread | double | 0.25 | Spread of time spent during tracking |
+| jtest:tracker:bytes | int | 1000 | Bytes written during tracking |
+| jtest:tracker:bytes_spread | double | 0.25 | Spread of bytes written during tracking |
+| jtest:plotter:cputime_ms | int | 0 | Time spent during plotting |
+| jtest:plotter:cputime_spread | double | 0.25 | Spread of time spent during plotting |
+| jtest:plotter:bytes | int | 1000 | Bytes written during plotting |
+| jtest:plotter:bytes_spread | double | 0.25 | Spread of bytes written during plotting |
 
 
 
 The following parameters are used for benchmarking:
 
 | Name | Type | Default | Description |
 |:-----|:-----|:------------|:--------|
-benchmark:nsamples    | int    | 15 | Number of measurements made for each thread count
-benchmark:minthreads  | int    | 1  | Minimum thread count
-benchmark:maxthreads  | int    | ncores | Maximum thread count
-benchmark:threadstep  | int    | 1  | Thread count increment
-benchmark:resultsdir  | string | JANA_Test_Results | Directory name for benchmark test results
+| benchmark:nsamples    | int    | 15 | Number of measurements made for each thread count |
+| benchmark:minthreads  | int    | 1  | Minimum thread count |
+| benchmark:maxthreads  | int    | ncores | Maximum thread count |
+| benchmark:threadstep  | int    | 1  | Thread count increment |
+| benchmark:resultsdir  | string | JANA_Test_Results | Directory name for benchmark test results |
 
 
 The following parameters are more advanced, but may come in handy when doing performance tuning:
 
 | Name | Type | Default | Description |
 |:-----|:-----|:------------|:--------|
-jana:engine                       | int  | 0        | Which parallelism engine to use. 0: JArrowProcessingController. 1: JDebugProcessingController.
-jana:event_pool_size              | int  | nthreads | The number of events which may be in-flight at once
-jana:limit_total_events_in_flight | bool | 1        | Whether the number of in-flight events should be limited
-jana:affinity                     | int  | 0        | Thread pinning strategy. 0: None. 1: Minimize number of memory localities. 2: Minimize number of hyperthreads.
-jana:locality                     | int  | 0        | Memory locality strategy. 0: Global. 1: Socket-local. 2: Numa-domain-local. 3. Core-local. 4. Cpu-local
-jana:enable_stealing              | bool | 0        | Allow threads to pick up work from a different memory location if their local mailbox is empty.
-jana:event_queue_threshold        | int  | 80       | Mailbox buffer size
-jana:event_source_chunksize       | int  | 40       | Reduce mailbox contention by chunking work assignments
-jana:event_processor_chunksize    | int  | 1        | Reduce mailbox contention by chunking work assignments
+| jana:max_inflight_events          | int  | nthreads  | The number of events which may be in-flight at once. Should be at least `nthreads`, more gives better load balancing. |
+| jana:affinity                     | int  | 0         | Thread pinning strategy. 0: None. 1: Minimize number of memory localities. 2: Minimize number of hyperthreads. |
+| jana:locality                     | int  | 0         | Memory locality strategy. 0: Global. 1: Socket-local. 2: Numa-domain-local. 3. Core-local. 4. Cpu-local |
+| jana:enable_stealing              | bool | 0         | Allow threads to pick up work from a different memory location if their local mailbox is empty. |
 
 
 Creating code skeletons

diff --git a/docs/jana1to2/developers-transition-guide.md b/docs/jana1to2/developers-transition-guide.md
@@ -686,6 +686,26 @@ for (auto hit: results){
 Set(results)
 ```
 
+### Forcing Factory to Regenerate Objects
+
+##### **JANA1**
+In JANA1, adding `use_factory` in the constructor forces the factory to regenerate objects, regardless of whether they already exist in the input file. This prevents JANA from searching the input file for those objects. For example:
+
+```cpp
+DEventWriterROOT_factory_ReactionEfficiency() {
+    use_factory = 1;  // prevents JANA from searching the input file for these objects
+};
+```
+
+##### **JANA2**
+In JANA2, the `use_factory` flag is no longer used. To achieve the same functionality, the `SetRegenerateFlag` function must be called with `true` as the parameter. This will prevent JANA from searching the input file for these objects, similar to the behavior in JANA1. For example:
+
+```cpp
+DEventWriterROOT_factory_ReactionEfficiency() {
+    SetRegenerateFlag(true);  // prevents JANA from searching the input file for these objects
+};
+```
+
 ## JEvent
 ### Transition from JEventLoop to JEvent
 ##### **JANA1**

diff --git a/docs/jana1to2/parameter-changes.md b/docs/jana1to2/parameter-changes.md
@@ -10,9 +10,9 @@ The following table compares commonly used JANA parameters between JANA1 and JAN
 |-----------------------|------------------------|------------------------------|--------------------------------------------------|
 | **PLUGINS**           | `- `                   | `-`                          | `-`                                              |
 | **EVENTS_TO_KEEP**    | `EVENTS_TO_KEEP`       | `jana:nevents`               | `-`                                              |
-| **EVENTS_TO_SKIP**    | `EVENTS_TO_SKIP`       | `jana:nskips`                | `-`                                              |
+| **EVENTS_TO_SKIP**    | `EVENTS_TO_SKIP`       | `jana:nskip`                | `-`                                              |
 | **NTHREADS**          | `-`                    | `-`                          | `-`                                              |
-| **JANA:BATCH_MODE**   | `JANA:BATCH_MODE`      | `log:global`                 | `TRACE`, `DEBUG`, `INFO`, `WARN`, `FATAL`, `OFF` |
+| **JANA:BATCH_MODE**   | `JANA:BATCH_MODE`      | `jana:global_loglevel`                 | `TRACE`, `DEBUG`, `INFO`, `WARN`, `FATAL`, `OFF` |
 | **JANA_CALIB_CONTEXT**| `JANA_CALIB_CONTEXT`   | `jana:calib_context`         | `-`                                              |
 
 ## Changes in `halld_recon` Parameters
@@ -22,4 +22,4 @@ The following table compares commonly used JANA parameters between JANA1 and JAN
 - **JANA1:** The `-b` option was used for printing event status bits in `hd_dump`.
 - **JANA2:** The `-b` option is used for benchmarking in JANA2. Thus, `hd_dump` parameter for event status bits (`-b`) has been changed to `-B`. Update your usage accordingly.
 
-For additional assistance or questions, please contact [[email protected]](mailto:[email protected]).
+For additional assistance or questions, please contact [[email protected]](mailto:[email protected]).
diff --git a/scripts/jana-generate.py b/scripts/jana-generate.py
@@ -187,8 +187,6 @@ class {name} : public JEventSource {{
 public:
     {name}();
 
-    {name}(std::string resource_name, JApplication* app);
-
     virtual ~{name}() = default;
 
     void Open() override;
@@ -230,12 +228,6 @@ class {name} : public JEventSource {{
     SetCallbackStyle(CallbackStyle::ExpertMode);
 }}
 
-{name}::{name}(std::string resource_name, JApplication* app) : JEventSource(resource_name, app) {{
-    SetTypeName(NAME_OF_THIS); // Provide JANA with class name
-    SetCallbackStyle(CallbackStyle::ExpertMode);
-}}
-
-
 void {name}::Open() {{
 
     /// Open is called exactly once when processing begins.