caliper_utils.hpp File Reference

Zero-overhead Caliper guards for the inactive (no CALI_CONFIG) case. More...

#include <config/config.hpp>
#include <caliper/cali.h>
#include <cstdlib>

Include dependency graph for caliper_utils.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	EspressoCaliRegion
	RAII region guard: begin on construction, end on destruction. More...
struct	EspressoCaliIteration
	RAII iteration annotation for one pass through a loop body. More...
struct	EspressoCaliLoop
	RAII loop wrapper replacing the CALI_CXX_MARK_LOOP_BEGIN / CALI_CXX_MARK_LOOP_ITERATION / CALI_CXX_MARK_LOOP_END macro triplet. More...

Macros
#define	ESPRESSO_CALI_MARK_FUNCTION
	Guarded drop-in replacement for CALI_CXX_MARK_FUNCTION.
#define	ESPRESSO_CALI_MARK_BEGIN(name)
	Guarded CALI_MARK_BEGIN — no-op when inactive.
#define	ESPRESSO_CALI_MARK_END(name)
	Guarded CALI_MARK_END — no-op when inactive.

Functions
bool	espresso_cali_active () noexcept
	Return true if Caliper is configured for this process.

Detailed Description

Zero-overhead Caliper guards for the inactive (no CALI_CONFIG) case.

When Caliper is compiled in but CALI_CONFIG is not set (the common production case), the standard CALI_MARK_BEGIN/END and CALI_CXX_MARK_FUNCTION macros still pay the full Caliper entry cost (thread-blackboard update, siglock acquisition). On a hot path with many markers per step this amounts to measurable wall-clock overhead.

This header provides guarded replacements:

• espresso_cali_active() — checked once per process; in steady state this is a single byte load + branch.
• ESPRESSO_CALI_MARK_FUNCTION — RAII guard equivalent to CALI_CXX_MARK_FUNCTION but zero-cost when inactive.
• ESPRESSO_CALI_MARK_BEGIN(name) / ESPRESSO_CALI_MARK_END(name)
• EspressoCaliLoop — RAII loop wrapper replacing the ESPRESSO_CALI_MARK_LOOP_BEGIN / ESPRESSO_CALI_MARK_LOOP_ITERATION / ESPRESSO_CALI_MARK_LOOP_END macro triplet.

All macros and types are no-ops / empty when ESPRESSO_CALIPER is not defined.

Activation path limitation

espresso_cali_active() detects Caliper activation solely via the CALI_CONFIG environment variable. Activation through CALI_SERVICES_ENABLE, Caliper config files, or programmatic cali::ConfigManager::start() is not detected — hot-path regions will silently produce no output for those activation paths. CALI_CONFIG is the supported activation path for ESPResSo profiling (used by testsuite/python/caliper.py). This restriction is intentional: checking CALI_CONFIG once and caching the result eliminates the Caliper entry cost (siglock + thread-blackboard update) on every hot-path marker when profiling is inactive.

Definition in file caliper_utils.hpp.

Macro Definition Documentation

ESPRESSO_CALI_MARK_BEGIN

#define ESPRESSO_CALI_MARK_BEGIN

(

name

)

Value:

  do {                                                                         \
    if (::espresso_cali_active())                                              \
      CALI_MARK_BEGIN(name);                                                   \
  } while (false)

Guarded CALI_MARK_BEGIN — no-op when inactive.

Definition at line 210 of file caliper_utils.hpp.

ESPRESSO_CALI_MARK_END

#define ESPRESSO_CALI_MARK_END

(

name

)

Value:

  do {                                                                         \
    if (::espresso_cali_active())                                              \
      CALI_MARK_END(name);                                                     \
  } while (false)

Guarded CALI_MARK_END — no-op when inactive.

Definition at line 219 of file caliper_utils.hpp.

ESPRESSO_CALI_MARK_FUNCTION

#define ESPRESSO_CALI_MARK_FUNCTION

Value:

  EspressoCaliRegion CALI_CREATE_VAR_NAME(__espresso_cali_fn, __LINE__)(       \
      __func__, ::espresso_cali_active())

Guarded drop-in replacement for CALI_CXX_MARK_FUNCTION.

Captures __func__ at the call site so that the region name is the enclosing function name, not the destructor name.

Definition at line 203 of file caliper_utils.hpp.

Function Documentation

espresso_cali_active()

bool espresso_cali_active ( )

inlinenoexcept

Return true if Caliper is configured for this process.

Reads CALI_CONFIG from the environment exactly once (on the first call) and caches the result. Subsequent calls pay only one byte load + branch.

inline ensures a single shared static across all translation units (C++ ODR for inline functions with static locals).

Note

Only CALI_CONFIG activation is detected; see the file-level documentation for the rationale and limitation.

Definition at line 78 of file caliper_utils.hpp.

Referenced by EspressoCaliLoop::EspressoCaliLoop(), ghost_reduce_async_attr(), GhostComm::halo_exchange_finish(), and GhostComm::halo_exchange_start().