Explore opt-in fixed-team OpenMP worker timing mode

[jaharris87]

Problem or workflow

The current ftimer_openmp_t worker-timing contract is correctness-first: users register timer ids in serial context, call begin_parallel_region before each worker-timed level-1 OpenMP region, use start_id / stop_id on worker lanes, then call end_parallel_region after the region. That explicit epoch is important for the current design, but it is awkward for HPC Fortran codes that have many separate !$omp parallel regions and a stable thread-count policy for the whole simulation.

Many MPI+OpenMP applications effectively assume:

• dynamic OpenMP teams are disabled;
• the number of OpenMP threads is fixed for a run or phase;
• only level-1 teams are timed;
• worker thread ids are treated as stable lane ids for timing purposes.

For that common profile, it may be possible to add a more restrictive opt-in setup mode that preserves the current default semantics while reducing repeated begin_parallel_region / end_parallel_region boilerplate for future worker timing.

Current design context

This issue should be evaluated against the landed OpenMP/hybrid design, not as a replacement for it:

• docs/history/openmp-hybrid-api-design.md keeps true worker timing on the explicit ftimer_openmp_t surface, not the procedural default instance.
• docs/history/openmp-thread-lane-runtime-design.md defines the current lane-owned runtime state and explicit timed-region epoch model.
• docs/history/openmp-hybrid-summary-design.md defines stopped-run OpenMP summaries, region-envelope time, summed lane work, and participation semantics.
• docs/history/openmp-hybrid-mpi-reduction-design.md defines strict and sparse union MPI+OpenMP reductions and their rank/lane participation contracts.
• docs/openmp-timing-modes.md is the current user-facing guide.
• docs/semantics.md is the live runtime contract.

The current explicit-region model is not accidental. It gives fTimer:

• a monotonically increasing epoch so starts/stops cannot silently pair across separate OpenMP regions;
• a serial-context merge boundary for active-lane scans and deterministic diagnostics;
• an observed team/lane structure for eligible-lane and missing-lane semantics;
• a wall-clock timed_region_envelope_time with clear meaning;
• strict MPI+OpenMP descriptor identity that includes eligible-lane structure.

Possible future direction

Investigate an opt-in "fixed-team" or "assumed stable lanes" mode for ftimer_openmp_t. Exact names are intentionally unsettled, but the shape might be something like:

type(ftimer_openmp_config_t) :: config

config%mode = FTIMER_OPENMP_MODE_THREAD_LANES
config%max_lanes = 1 + fixed_worker_count
! future opt-in field(s), names TBD:
! config%lane_policy = FTIMER_OPENMP_LANE_POLICY_FIXED_TEAM
! config%fixed_worker_lanes = fixed_worker_count
! config%require_matching_team_size = .true.

Under such a policy, pre-registered start_id / stop_id calls could potentially be valid inside any level-1 OpenMP parallel region after initialization, without an explicit begin_parallel_region / end_parallel_region pair around every region.

This should be treated as a future ergonomics and semantics design issue, not a committed API.

Design questions to answer

• Can fTimer safely support worker start_id / stop_id without an explicit region epoch, or is a lighter-weight epoch/checkpoint still required?
• If no explicit end_parallel_region exists, how does fTimer detect or prevent an accidentally leaked worker timer from being stopped in a later parallel region on the same omp_get_thread_num() lane?
• What should happen to timed_region_envelope_time in this mode?
  • Keep it zero or unavailable?
  • Rename/define a different worker-active envelope such as first-start to last-stop?
  • Require explicit regions only when wall-clock region-envelope reporting is desired?
• Should eligible lanes be the configured fixed worker count instead of observed per-epoch team lanes?
• If eligible lanes are configured, how do local OpenMP summaries avoid hiding real team-size drift or missing-lane bugs?
• Should strict MPI+OpenMP descriptor identity include the lane policy and fixed worker-lane count so fixed-team data cannot be reduced with observed-epoch data?
• In MPI+OpenMP builds, should strict hybrid mode require identical fixed-worker-lane configuration across ranks, while sparse union mode exposes differing or missing participation?
• Can dynamic teams, nested teams, task migration, and unsupported OpenMP levels be rejected reliably enough in worker calls?
• Does removing explicit region begin/end actually reduce overhead, or does an implicit policy need enough synchronization and team-size checking that the performance benefit is mostly ergonomic?
• Should this be library API, documentation/facade guidance, or a separate macro/preprocessor convenience layer around the existing explicit epoch model?

Constraints and caveats

Any proposed design should preserve:

• current ftimer / ftimer_core master-thread-only compatibility behavior;
• current ftimer_openmp_t explicit-region behavior as the default;
• serial-context timer registration before worker hot paths;
• id-first worker timing as the high-performance path;
• stopped-run-only OpenMP and MPI+OpenMP summaries;
• separate strict and sparse union MPI+OpenMP result families;
• no OpenMP task migration, nested team, accelerator/device, callback/profiler, or automatic MPI barrier claims.

Important caveat: the current explicit epoch prevents plausible but wrong cross-region pairings. A fixed-team mode without an equivalent protection may be easier to write but less safe. That tradeoff needs to be explicit before implementation.

Scope boundaries

In scope:

• Design an opt-in future mode or helper strategy for stable-thread-count HPC codes.
• Decide whether it can safely reduce or eliminate per-region begin_parallel_region / end_parallel_region calls.
• Define changed or unavailable summary fields, especially timed_region_envelope_time and eligible/missing lane counts.
• Define strict and sparse union MPI+OpenMP behavior under the new policy.
• Identify tests and benchmarks needed before implementation.

Out of scope:

• Changing current behavior in this issue.
• Making the existing procedural API perform worker timing.
• Supporting dynamic team sizes transparently in the fixed-team mode.
• Supporting nested OpenMP teams or OpenMP tasks.
• Replacing the current observed-epoch model for users who need exact region envelopes and per-epoch participation.

Suggested validation for a later implementation

• Local OpenMP tests showing multiple separate !$omp parallel regions can contribute to the same pre-registered timer without explicit per-region begin/end under the opt-in policy.
• Tests proving the current explicit-region mode remains unchanged.
• Tests for mismatched or drifting team sizes when fixed-team mode is enabled.
• Tests for active lane stacks at summary/reset/finalize.
• A deliberate cross-region leak scenario, with either a proven diagnostic or a documented unsupported-case decision.
• Summary tests for eligible, participating, and missing lane counts under configured fixed-team semantics.
• MPI+OpenMP strict tests for identical fixed-team configuration across ranks and mismatch failures when ranks disagree.
• MPI+OpenMP sparse union tests for rank/lane-conditional work under the new policy if allowed.
• Benchmark rows comparing explicit begin/end mode, fixed-team worker hot paths, and any implicit synchronization/checkpoint cost.
• Documentation updates to docs/openmp-timing-modes.md, docs/semantics.md, and the relevant docs/history design record.

Related context

• docs/openmp-timing-modes.md
• docs/semantics.md
• docs/history/openmp-hybrid-api-design.md
• docs/history/openmp-thread-lane-runtime-design.md
• docs/history/openmp-hybrid-summary-design.md
• docs/history/openmp-hybrid-mpi-reduction-design.md
• docs/history/openmp-hybrid-validation-plan.md
• src/ftimer_openmp.F90
• examples/openmp_worker_example.F90
• examples/mpi_openmp_example.F90

[jaharris87]

Mapped into the v1.0 readiness umbrella #348 as V1-NB-01: Future fixed-team OpenMP worker ergonomics.

Disposition for v1.0 planning: this remains an explicitly non-blocking post-v1.0 strategic/enhancement issue unless a maintainer decides the current explicit begin_parallel_region / end_parallel_region worker timing model is unacceptable for v1.0. The v1.0 blocker is only to keep release claims clear that fixed-team ergonomics are future work, not part of the 1.0 contract.