YAC 3.21.0
Yet Another Coupler
Loading...
Searching...
No Matches
instrument.c
Go to the documentation of this file.
1// Copyright (c) 2026 The YAC Authors
2//
3// SPDX-License-Identifier: BSD-3-Clause
4
5#include "instrument.h"
7#include "yac_assert.h"
8#include "utils_common.h"
9
10/* Reuses the codebase's generic id<->name lookup facility (see
11 * yac_name_type_pair_utils in utils_common.h; the same pattern is used e.g.
12 * for yac_location in location.c) instead of a bespoke, unbounded lookup
13 * table, so looking up an out-of-range id is caught below instead of
14 * reading out of bounds. */
16#define X(id, str) {.name = str, .type = (int)YAC_INSTR_##id},
18#undef X
19 {.name = "total number of instrumented regions",
20 .type = (int)YAC_INSTR_REGION_COUNT}
21};
22
23#define CHECK_REGION_ID(id) \
24 YAC_ASSERT_F( \
25 (int)(id) >= 0 && (int)(id) < YAC_INSTR_REGION_COUNT, \
26 "invalid instrumentation region id %d", (int)(id))
27
29
30 char const *name =
33 YAC_ASSERT_F(name != NULL, "invalid instrumentation region id %d", (int)id)
34 return name;
35}
36
44typedef struct {
45 void *handle; /* opaque handle returned by the create callback */
46 int resolved; /* 0/1: has the create callback been called for this id */
47 int depth; /* nesting depth at which this id is currently open, or -1 */
49
59typedef struct {
61 char const *file;
62 int line;
64
67
68// Callback function pointers and user data for instrumentation.
73static void *yac_user_data = NULL;
74
82
86#define INSTR_IS_ACTIVE() (yac_free_frame != NULL)
87#define INSTR_DEPTH() (int)(yac_free_frame - yac_region_open)
88#define INSTR_HAS_OPEN() (yac_free_frame != yac_region_open)
89#define INSTR_INNERMOST_OPEN() (yac_free_frame - 1)
90
93 frame->file = NULL;
94 frame->line = -1;
95}
96
100 yac_instrument_destroy_cb destroy_cb,
101 void *user_data) {
102
103 // Check that no regions are currently active/open, because changing the
104 // callbacks while regions are active would leave the instrumentation state
105 // inconsistent and could lead to memory leaks (e.g. if the destroy callback
106 // is changed while regions are still active, the handles owned by the
107 // previous registration would never be destroyed).
110 "Cannot change callbacks while regions are active — region '%s', "
111 "started at %s:%d, was never stopped.",
114
115 // Destroy handles owned by the *previous* registration, using the
116 // *previous* destroy_cb/user_data — not the ones being installed.
117 if (yac_destroy_cb) {
118 for (size_t i = 0; i < YAC_INSTR_REGION_COUNT; i++) {
119 if (yac_region[i].resolved)
120 yac_destroy_cb((int)i, yac_region[i].handle, yac_user_data);
121 }
122 }
123
124 // Reset all state for the new registration.
125 for (int i = 0; i < YAC_INSTR_REGION_COUNT; i++) {
126 yac_region[i] =
127 (yac_region_state){.handle = NULL, .resolved = 0, .depth = -1};
129 }
130
132 (start_cb || stop_cb) ||
133 (!create_cb && !destroy_cb && !user_data),
134 "At least one of start_cb or stop_cb must be provided, otherwise "
135 "instrumentation is disabled and all other callbacks/user_data must be "
136 "NULL.");
137
138 // Set the new callbacks and user data. If no start/stop callbacks are
139 // provided, disable instrumentation (yac_free_frame = NULL) to avoid
140 // unnecessary work in the start/stop
141 yac_free_frame = (start_cb || stop_cb) ? yac_region_open : NULL;
142 yac_create_cb = INSTR_IS_ACTIVE() ? create_cb : NULL;
143 yac_start_cb = start_cb;
144 yac_stop_cb = stop_cb;
145 yac_destroy_cb = INSTR_IS_ACTIVE() ? destroy_cb : NULL;
147}
148
150
151 yac_instrument_set_callbacks(NULL, NULL, NULL, NULL, NULL);
152}
153
155
156 return yac_region_name(id);
157}
158
159// Fortran-facing wrapper: takes a plain int (the C enum's interoperable
160// representation), converts it to yac_instrument_region_id, and delegates
161// to yac_instrument_region_name, which does the plausibility check.
163
165 id >= 0 && id < YAC_INSTR_REGION_COUNT,
166 "invalid instrumentation region id %d", id)
167
169}
170
172 yac_instrument_region_id id, char const *file, int line) {
173
174 CHECK_REGION_ID(id);
175
176 // Return early if instrumentation is disabled, to avoid unnecessary work
177 if (!INSTR_IS_ACTIVE()) return;
178
179 // Lazy registration: create the region handle on first entry, if a
180 // create callback was provided. Otherwise, the handle remains NULL.
181 if (!yac_region[id].resolved) {
185 }
186
187 // Check for self-nesting of the same region ID: if it is still open, this
188 // is either a genuine recursive re-entry, or a prior YAC_INSTRUMENT_STOP
189 // for this id was skipped (e.g. by an early return) — point at where that
190 // still-open region was started, so the mismatch is actionable.
192 yac_region[id].depth == -1,
193 "Region '%s' started at %s:%d while already active at depth %d "
194 "(opened at %s:%d) — recursive nesting of the same region is not "
195 "allowed, and a missing YAC_INSTRUMENT_STOP for the earlier call is a "
196 "likely cause.",
197 yac_region_name(id), file, line, yac_region[id].depth,
198 yac_region_open[yac_region[id].depth].file,
199 yac_region_open[yac_region[id].depth].line)
200
201 // Update the depth of this region ID, push it onto the open-region stack,
202 // and advance the free-frame pointer.
203 int curr_depth = INSTR_DEPTH();
204 yac_region[id].depth = curr_depth;
206 (yac_region_open_frame){.id = id, .file = file, .line = line};
208
209 // Call the start callback if it was provided.
210 if (yac_start_cb)
211 yac_start_cb(id, yac_region[id].handle, curr_depth, yac_user_data);
212}
213
215 yac_instrument_region_id id, char const *file, int line) {
216
217 CHECK_REGION_ID(id);
218
219 // Return early if instrumentation is disabled, to avoid unnecessary work
220 if (!INSTR_IS_ACTIVE()) return;
221
222 // Check that the region is currently active (depth != -1) - if it isn't,
223 // this is either a genuine stop of an inactive region, or a prior
224 // YAC_INSTRUMENT_START for this id was skipped (e.g. by an early return).
226 yac_region[id].depth != -1,
227 "Region '%s' stopped at %s:%d while not active — instrumentation is "
228 "corrupted.", yac_region_name(id), file, line)
229
230 // The region being stopped must be the innermost currently-open one
231 // (proper LIFO nesting). If it isn't, name the region that actually IS
232 // innermost and where it was opened - a much more actionable diagnostic
233 // than a bare depth mismatch, and the direct symptom of a skipped
234 // YAC_INSTRUMENT_STOP for that region (e.g. by an early return).
236 INSTR_INNERMOST_OPEN()->id == id,
237 "Region '%s' stopped at %s:%d, but the innermost open region is '%s' "
238 "(opened at %s:%d) — a YAC_INSTRUMENT_STOP for it was skipped.",
239 yac_region_name(id), file, line,
242
243 // Pop the open-region stack and reset the depth of this region ID.
244 yac_region[id].depth = -1;
247
248 // Call the stop callback if it was provided.
249 if (yac_stop_cb)
251}
#define YAC_ASSERT(exp, msg)
char const * yac_name_type_pair_get_name(struct yac_name_type_pair const *pairs, size_t count, int type)
Definition utils_core.c:14
#define INSTR_IS_ACTIVE()
Definition instrument.c:86
static yac_instrument_create_cb yac_create_cb
Definition instrument.c:69
static void * yac_user_data
Definition instrument.c:73
void yac_instrument_stop_impl(yac_instrument_region_id id, char const *file, int line)
Stop an instrumented region. Do not call directly — use the YAC_INSTRUMENT_STOP macro below,...
Definition instrument.c:214
static yac_instrument_stop_cb yac_stop_cb
Definition instrument.c:71
#define INSTR_HAS_OPEN()
Definition instrument.c:88
#define INSTR_INNERMOST_OPEN()
Definition instrument.c:89
static yac_region_state yac_region[YAC_INSTR_REGION_COUNT]
Definition instrument.c:65
const char * yac_instrument_region_name_f2c(int id)
Definition instrument.c:162
void yac_instrument_set_callbacks(yac_instrument_create_cb create_cb, yac_instrument_start_cb start_cb, yac_instrument_stop_cb stop_cb, yac_instrument_destroy_cb destroy_cb, void *user_data)
Definition instrument.c:97
static yac_instrument_start_cb yac_start_cb
Definition instrument.c:70
static struct yac_name_type_pair const yac_region_name_type_pair[]
Definition instrument.c:15
void yac_instrument_start_impl(yac_instrument_region_id id, char const *file, int line)
Start an instrumented region. Do not call directly — use the YAC_INSTRUMENT_START macro below,...
Definition instrument.c:171
#define CHECK_REGION_ID(id)
Definition instrument.c:23
static char const * yac_region_name(yac_instrument_region_id id)
Definition instrument.c:28
static yac_region_open_frame * yac_free_frame
Definition instrument.c:81
void yac_instrument_clear_callbacks(void)
Definition instrument.c:149
const char * yac_instrument_region_name(yac_instrument_region_id id)
Definition instrument.c:154
static yac_region_open_frame yac_region_open[YAC_INSTR_REGION_COUNT]
Definition instrument.c:66
static void yac_instrument_open_frame_reset(yac_region_open_frame *frame)
Definition instrument.c:91
static yac_instrument_destroy_cb yac_destroy_cb
Definition instrument.c:72
#define INSTR_DEPTH()
Definition instrument.c:87
yac_instrument_region_id
Definition instrument.h:53
@ YAC_INSTR_REGION_COUNT
Definition instrument.h:57
void(* yac_instrument_start_cb)(int id, void *region_handle, int depth, void *user_data)
Definition instrument.h:85
void *(* yac_instrument_create_cb)(int id, void *user_data)
Definition instrument.h:72
void(* yac_instrument_stop_cb)(int id, void *region_handle, int depth, void *user_data)
Definition instrument.h:101
void(* yac_instrument_destroy_cb)(int id, void *region_handle, void *user_data)
Definition instrument.h:116
#define YAC_INSTRUMENT_REGION_TABLE
Definition instrument.h:10
void * user_data
const char * name
String name (e.g., "true")
Frame of an open instrumented region.
Definition instrument.c:59
yac_instrument_region_id id
Definition instrument.c:60
char const * file
Definition instrument.c:61
State of a single instrumented region ID.
Definition instrument.c:44
char const * name
Definition toy_scrip.c:114
int id
Definition toy_scrip.c:115
#define YAC_ASSERT_F(exp, format,...)
Definition yac_assert.h:39