Debian Codegraph @

src/backend/utils/misc/injection_point.c

raw
1 /*-------------------------------------------------------------------------
2 *
3 * injection_point.c
4 * Routines to control and run injection points in the code.
5 *
6 * Injection points can be used to run arbitrary code by attaching callbacks
7 * that would be executed in place of the named injection point.
8 *
9 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
10 * Portions Copyright (c) 1994, Regents of the University of California
11 *
12 *
13 * IDENTIFICATION
14 * src/backend/utils/misc/injection_point.c
15 *
16 *-------------------------------------------------------------------------
17 */
18 #include "postgres.h"
19
20 #include "utils/injection_point.h"
21
22 #ifdef USE_INJECTION_POINTS
23
24 #include <sys/stat.h>
25
26 #include "fmgr.h"
27 #include "miscadmin.h"
28 #include "storage/fd.h"
29 #include "storage/lwlock.h"
30 #include "storage/shmem.h"
31 #include "utils/hsearch.h"
32 #include "utils/memutils.h"
33
34 /* Field sizes */
35 #define INJ_NAME_MAXLEN 64
36 #define INJ_LIB_MAXLEN 128
37 #define INJ_FUNC_MAXLEN 128
38 #define INJ_PRIVATE_MAXLEN 1024
39
40 /* Single injection point stored in shared memory */
41 typedef struct InjectionPointEntry
42 {
43 /*
44 * Because injection points need to be usable without LWLocks, we use a
45 * generation counter on each entry to allow safe, lock-free reading.
46 *
47 * To read an entry, first read the current 'generation' value. If it's
48 * even, then the slot is currently unused, and odd means it's in use.
49 * When reading the other fields, beware that they may change while
50 * reading them, if the entry is released and reused! After reading the
51 * other fields, read 'generation' again: if its value hasn't changed, you
52 * can be certain that the other fields you read are valid. Otherwise,
53 * the slot was concurrently recycled, and you should ignore it.
54 *
55 * When adding an entry, you must store all the other fields first, and
56 * then update the generation number, with an appropriate memory barrier
57 * in between. In addition to that protocol, you must also hold
58 * InjectionPointLock, to prevent two backends from modifying the array at
59 * the same time.
60 */
61 pg_atomic_uint64 generation;
62
63 char name[INJ_NAME_MAXLEN]; /* point name */
64 char library[INJ_LIB_MAXLEN]; /* library */
65 char function[INJ_FUNC_MAXLEN]; /* function */
66
67 /*
68 * Opaque data area that modules can use to pass some custom data to
69 * callbacks, registered when attached.
70 */
71 char private_data[INJ_PRIVATE_MAXLEN];
72 } InjectionPointEntry;
73
74 #define MAX_INJECTION_POINTS 128
75
76 /*
77 * Shared memory array of active injection points.
78 *
79 * 'max_inuse' is the highest index currently in use, plus one. It's just an
80 * optimization to avoid scanning through the whole entry, in the common case
81 * that there are no injection points, or only a few.
82 */
83 typedef struct InjectionPointsCtl
84 {
85 pg_atomic_uint32 max_inuse;
86 InjectionPointEntry entries[MAX_INJECTION_POINTS];
87 } InjectionPointsCtl;
88
89 NON_EXEC_STATIC InjectionPointsCtl *ActiveInjectionPoints;
90
91 /*
92 * Backend local cache of injection callbacks already loaded, stored in
93 * TopMemoryContext.
94 */
95 typedef struct InjectionPointCacheEntry
96 {
97 char name[INJ_NAME_MAXLEN];
98 char private_data[INJ_PRIVATE_MAXLEN];
99 InjectionPointCallback callback;
100
101 /*
102 * Shmem slot and copy of its generation number when this cache entry was
103 * created. They can be used to validate if the cached entry is still
104 * valid.
105 */
106 int slot_idx;
107 uint64 generation;
108 } InjectionPointCacheEntry;
109
110 static HTAB *InjectionPointCache = NULL;
111
112 /*
113 * injection_point_cache_add
114 *
115 * Add an injection point to the local cache.
116 */
117 static InjectionPointCacheEntry *
118 injection_point_cache_add(const char *name,
119 int slot_idx,
120 uint64 generation,
121 InjectionPointCallback callback,
122 const void *private_data)
123 {
124 InjectionPointCacheEntry *entry;
125 bool found;
126
127 /* If first time, initialize */
128 if (InjectionPointCache == NULL)
129 {
130 HASHCTL hash_ctl;
131
132 hash_ctl.keysize = sizeof(char[INJ_NAME_MAXLEN]);
133 hash_ctl.entrysize = sizeof(InjectionPointCacheEntry);
134 hash_ctl.hcxt = TopMemoryContext;
135
136 InjectionPointCache = hash_create("InjectionPoint cache hash",
137 MAX_INJECTION_POINTS,
138 &hash_ctl,
139 HASH_ELEM | HASH_STRINGS | HASH_CONTEXT);
140 }
141
142 entry = (InjectionPointCacheEntry *)
143 hash_search(InjectionPointCache, name, HASH_ENTER, &found);
144
145 Assert(!found);
146 strlcpy(entry->name, name, sizeof(entry->name));
147 entry->slot_idx = slot_idx;
148 entry->generation = generation;
149 entry->callback = callback;
150 memcpy(entry->private_data, private_data, INJ_PRIVATE_MAXLEN);
151
152 return entry;
153 }
154
155 /*
156 * injection_point_cache_remove
157 *
158 * Remove entry from the local cache. Note that this leaks a callback
159 * loaded but removed later on, which should have no consequence from
160 * a testing perspective.
161 */
162 static void
163 injection_point_cache_remove(const char *name)
164 {
165 bool found PG_USED_FOR_ASSERTS_ONLY;
166
167 (void) hash_search(InjectionPointCache, name, HASH_REMOVE, &found);
168 Assert(found);
169 }
170
171 /*
172 * injection_point_cache_load
173 *
174 * Load an injection point into the local cache.
175 */
176 static InjectionPointCacheEntry *
177 injection_point_cache_load(InjectionPointEntry *entry, int slot_idx, uint64 generation)
178 {
179 char path[MAXPGPATH];
180 void *injection_callback_local;
181
182 snprintf(path, MAXPGPATH, "%s/%s%s", pkglib_path,
183 entry->library, DLSUFFIX);
184
185 if (!pg_file_exists(path))
186 elog(ERROR, "could not find library \"%s\" for injection point \"%s\"",
187 path, entry->name);
188
189 injection_callback_local = (void *)
190 load_external_function(path, entry->function, false, NULL);
191
192 if (injection_callback_local == NULL)
193 elog(ERROR, "could not find function \"%s\" in library \"%s\" for injection point \"%s\"",
194 entry->function, path, entry->name);
195
196 /* add it to the local cache */
197 return injection_point_cache_add(entry->name,
198 slot_idx,
199 generation,
200 injection_callback_local,
201 entry->private_data);
202 }
203
204 /*
205 * injection_point_cache_get
206 *
207 * Retrieve an injection point from the local cache, if any.
208 */
209 static InjectionPointCacheEntry *
210 injection_point_cache_get(const char *name)
211 {
212 bool found;
213 InjectionPointCacheEntry *entry;
214
215 /* no callback if no cache yet */
216 if (InjectionPointCache == NULL)
217 return NULL;
218
219 entry = (InjectionPointCacheEntry *)
220 hash_search(InjectionPointCache, name, HASH_FIND, &found);
221
222 if (found)
223 return entry;
224
225 return NULL;
226 }
227 #endif /* USE_INJECTION_POINTS */
228
229 /*
230 * Return the space for dynamic shared hash table.
231 */
232 Size
233 InjectionPointShmemSize(void)
234 {
235 #ifdef USE_INJECTION_POINTS
236 Size sz = 0;
237
238 sz = add_size(sz, sizeof(InjectionPointsCtl));
239 return sz;
240 #else
241 return 0;
242 #endif
243 }
244
245 /*
246 * Allocate shmem space for dynamic shared hash.
247 */
248 void
249 InjectionPointShmemInit(void)
250 {
251 #ifdef USE_INJECTION_POINTS
252 bool found;
253
254 ActiveInjectionPoints = ShmemInitStruct("InjectionPoint hash",
255 sizeof(InjectionPointsCtl),
256 &found);
257 if (!IsUnderPostmaster)
258 {
259 Assert(!found);
260 pg_atomic_init_u32(&ActiveInjectionPoints->max_inuse, 0);
261 for (int i = 0; i < MAX_INJECTION_POINTS; i++)
262 pg_atomic_init_u64(&ActiveInjectionPoints->entries[i].generation, 0);
263 }
264 else
265 Assert(found);
266 #endif
267 }
268
269 /*
270 * Attach a new injection point.
271 */
272 void
273 InjectionPointAttach(const char *name,
274 const char *library,
275 const char *function,
276 const void *private_data,
277 int private_data_size)
278 {
279 #ifdef USE_INJECTION_POINTS
280 InjectionPointEntry *entry;
281 uint64 generation;
282 uint32 max_inuse;
283 int free_idx;
284
285 if (strlen(name) >= INJ_NAME_MAXLEN)
286 elog(ERROR, "injection point name %s too long (maximum of %u characters)",
287 name, INJ_NAME_MAXLEN - 1);
288 if (strlen(library) >= INJ_LIB_MAXLEN)
289 elog(ERROR, "injection point library %s too long (maximum of %u characters)",
290 library, INJ_LIB_MAXLEN - 1);
291 if (strlen(function) >= INJ_FUNC_MAXLEN)
292 elog(ERROR, "injection point function %s too long (maximum of %u characters)",
293 function, INJ_FUNC_MAXLEN - 1);
294 if (private_data_size > INJ_PRIVATE_MAXLEN)
295 elog(ERROR, "injection point data too long (maximum of %u bytes)",
296 INJ_PRIVATE_MAXLEN);
297
298 /*
299 * Allocate and register a new injection point. A new point should not
300 * exist. For testing purposes this should be fine.
301 */
302 LWLockAcquire(InjectionPointLock, LW_EXCLUSIVE);
303 max_inuse = pg_atomic_read_u32(&ActiveInjectionPoints->max_inuse);
304 free_idx = -1;
305
306 for (int idx = 0; idx < max_inuse; idx++)
307 {
308 entry = &ActiveInjectionPoints->entries[idx];
309 generation = pg_atomic_read_u64(&entry->generation);
310 if (generation % 2 == 0)
311 {
312 /*
313 * Found a free slot where we can add the new entry, but keep
314 * going so that we will find out if the entry already exists.
315 */
316 if (free_idx == -1)
317 free_idx = idx;
318 }
319 else if (strcmp(entry->name, name) == 0)
320 elog(ERROR, "injection point \"%s\" already defined", name);
321 }
322 if (free_idx == -1)
323 {
324 if (max_inuse == MAX_INJECTION_POINTS)
325 elog(ERROR, "too many injection points");
326 free_idx = max_inuse;
327 }
328 entry = &ActiveInjectionPoints->entries[free_idx];
329 generation = pg_atomic_read_u64(&entry->generation);
330 Assert(generation % 2 == 0);
331
332 /* Save the entry */
333 strlcpy(entry->name, name, sizeof(entry->name));
334 entry->name[INJ_NAME_MAXLEN - 1] = '\0';
335 strlcpy(entry->library, library, sizeof(entry->library));
336 entry->library[INJ_LIB_MAXLEN - 1] = '\0';
337 strlcpy(entry->function, function, sizeof(entry->function));
338 entry->function[INJ_FUNC_MAXLEN - 1] = '\0';
339 memset(entry->private_data, 0, INJ_PRIVATE_MAXLEN);
340 if (private_data != NULL)
341 memcpy(entry->private_data, private_data, private_data_size);
342
343 pg_write_barrier();
344 pg_atomic_write_u64(&entry->generation, generation + 1);
345
346 if (free_idx + 1 > max_inuse)
347 pg_atomic_write_u32(&ActiveInjectionPoints->max_inuse, free_idx + 1);
348
349 LWLockRelease(InjectionPointLock);
350
351 #else
352 elog(ERROR, "injection points are not supported by this build");
353 #endif
354 }
355
356 /*
357 * Detach an existing injection point.
358 *
359 * Returns true if the injection point was detached, false otherwise.
360 */
361 bool
362 InjectionPointDetach(const char *name)
363 {
364 #ifdef USE_INJECTION_POINTS
365 bool found = false;
366 int idx;
367 int max_inuse;
368
369 LWLockAcquire(InjectionPointLock, LW_EXCLUSIVE);
370
371 /* Find it in the shmem array, and mark the slot as unused */
372 max_inuse = (int) pg_atomic_read_u32(&ActiveInjectionPoints->max_inuse);
373 for (idx = max_inuse - 1; idx >= 0; --idx)
374 {
375 InjectionPointEntry *entry = &ActiveInjectionPoints->entries[idx];
376 uint64 generation;
377
378 generation = pg_atomic_read_u64(&entry->generation);
379 if (generation % 2 == 0)
380 continue; /* empty slot */
381
382 if (strcmp(entry->name, name) == 0)
383 {
384 Assert(!found);
385 found = true;
386 pg_atomic_write_u64(&entry->generation, generation + 1);
387 break;
388 }
389 }
390
391 /* If we just removed the highest-numbered entry, update 'max_inuse' */
392 if (found && idx == max_inuse - 1)
393 {
394 for (; idx >= 0; --idx)
395 {
396 InjectionPointEntry *entry = &ActiveInjectionPoints->entries[idx];
397 uint64 generation;
398
399 generation = pg_atomic_read_u64(&entry->generation);
400 if (generation % 2 != 0)
401 break;
402 }
403 pg_atomic_write_u32(&ActiveInjectionPoints->max_inuse, idx + 1);
404 }
405 LWLockRelease(InjectionPointLock);
406
407 return found;
408 #else
409 elog(ERROR, "Injection points are not supported by this build");
410 return true; /* silence compiler */
411 #endif
412 }
413
414 #ifdef USE_INJECTION_POINTS
415 /*
416 * Common workhorse of InjectionPointRun() and InjectionPointLoad()
417 *
418 * Checks if an injection point exists in shared memory, and update
419 * the local cache entry accordingly.
420 */
421 static InjectionPointCacheEntry *
422 InjectionPointCacheRefresh(const char *name)
423 {
424 uint32 max_inuse;
425 int namelen;
426 InjectionPointEntry local_copy;
427 InjectionPointCacheEntry *cached;
428
429 /*
430 * First read the number of in-use slots. More entries can be added or
431 * existing ones can be removed while we're reading them. If the entry
432 * we're looking for is concurrently added or removed, we might or might
433 * not see it. That's OK.
434 */
435 max_inuse = pg_atomic_read_u32(&ActiveInjectionPoints->max_inuse);
436 if (max_inuse == 0)
437 {
438 if (InjectionPointCache)
439 {
440 hash_destroy(InjectionPointCache);
441 InjectionPointCache = NULL;
442 }
443 return NULL;
444 }
445
446 /*
447 * If we have this entry in the local cache already, check if the cached
448 * entry is still valid.
449 */
450 cached = injection_point_cache_get(name);
451 if (cached)
452 {
453 int idx = cached->slot_idx;
454 InjectionPointEntry *entry = &ActiveInjectionPoints->entries[idx];
455
456 if (pg_atomic_read_u64(&entry->generation) == cached->generation)
457 {
458 /* still good */
459 return cached;
460 }
461 injection_point_cache_remove(name);
462 cached = NULL;
463 }
464
465 /*
466 * Search the shared memory array.
467 *
468 * It's possible that the entry we're looking for is concurrently detached
469 * or attached. Or detached *and* re-attached, to the same slot or a
470 * different slot. Detach and re-attach is not an atomic operation, so
471 * it's OK for us to return the old value, NULL, or the new value in such
472 * cases.
473 */
474 namelen = strlen(name);
475 for (int idx = 0; idx < max_inuse; idx++)
476 {
477 InjectionPointEntry *entry = &ActiveInjectionPoints->entries[idx];
478 uint64 generation;
479
480 /*
481 * Read the generation number so that we can detect concurrent
482 * modifications. The read barrier ensures that the generation number
483 * is loaded before any of the other fields.
484 */
485 generation = pg_atomic_read_u64(&entry->generation);
486 if (generation % 2 == 0)
487 continue; /* empty slot */
488 pg_read_barrier();
489
490 /* Is this the injection point we're looking for? */
491 if (memcmp(entry->name, name, namelen + 1) != 0)
492 continue;
493
494 /*
495 * The entry can change at any time, if the injection point is
496 * concurrently detached. Copy it to local memory, and re-check the
497 * generation. If the generation hasn't changed, we know our local
498 * copy is coherent.
499 */
500 memcpy(&local_copy, entry, sizeof(InjectionPointEntry));
501
502 pg_read_barrier();
503 if (pg_atomic_read_u64(&entry->generation) != generation)
504 {
505 /*
506 * The entry was concurrently detached.
507 *
508 * Continue the search, because if the generation number changed,
509 * we cannot trust the result of the name comparison we did above.
510 * It's theoretically possible that it falsely matched a mixed-up
511 * state of the old and new name, if the slot was recycled with a
512 * different name.
513 */
514 continue;
515 }
516
517 /* Success! Load it into the cache and return it */
518 return injection_point_cache_load(&local_copy, idx, generation);
519 }
520 return NULL;
521 }
522 #endif
523
524 /*
525 * Load an injection point into the local cache.
526 *
527 * This is useful to be able to load an injection point before running it,
528 * especially if the injection point is called in a code path where memory
529 * allocations cannot happen, like critical sections.
530 */
531 void
532 InjectionPointLoad(const char *name)
533 {
534 #ifdef USE_INJECTION_POINTS
535 InjectionPointCacheRefresh(name);
536 #else
537 elog(ERROR, "Injection points are not supported by this build");
538 #endif
539 }
540
541 /*
542 * Execute an injection point, if defined.
543 */
544 void
545 InjectionPointRun(const char *name, void *arg)
546 {
547 #ifdef USE_INJECTION_POINTS
548 InjectionPointCacheEntry *cache_entry;
549
550 cache_entry = InjectionPointCacheRefresh(name);
551 if (cache_entry)
552 cache_entry->callback(name, cache_entry->private_data, arg);
553 #else
554 elog(ERROR, "Injection points are not supported by this build");
555 #endif
556 }
557
558 /*
559 * Execute an injection point directly from the cache, if defined.
560 */
561 void
562 InjectionPointCached(const char *name, void *arg)
563 {
564 #ifdef USE_INJECTION_POINTS
565 InjectionPointCacheEntry *cache_entry;
566
567 cache_entry = injection_point_cache_get(name);
568 if (cache_entry)
569 cache_entry->callback(name, cache_entry->private_data, arg);
570 #else
571 elog(ERROR, "Injection points are not supported by this build");
572 #endif
573 }
574
575 /*
576 * Test if an injection point is defined.
577 */
578 bool
579 IsInjectionPointAttached(const char *name)
580 {
581 #ifdef USE_INJECTION_POINTS
582 return InjectionPointCacheRefresh(name) != NULL;
583 #else
584 elog(ERROR, "Injection points are not supported by this build");
585 return false; /* silence compiler */
586 #endif
587 }