1/*	$NetBSD: trampoline_p.h,v 1.1 2024/02/18 20:57:51 christos Exp $	*/
2
3/*
4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
5 *
6 * SPDX-License-Identifier: MPL-2.0
7 *
8 * This Source Code Form is subject to the terms of the Mozilla Public
9 * License, v. 2.0. If a copy of the MPL was not distributed with this
10 * file, you can obtain one at https://mozilla.org/MPL/2.0/.
11 *
12 * See the COPYRIGHT file distributed with this work for additional
13 * information regarding copyright ownership.
14 */
15
16#pragma once
17
18#include <isc/thread.h>
19
20/*! \file isc/trampoline_p.h
21 * \brief isc__trampoline: allows safe reuse of thread ID numbers.
22 *
23 * The 'isc_hp' hazard pointer API uses an internal thread ID
24 * variable ('tid_v') that is incremented for each new thread that uses
25 * hazard pointers. This thread ID is then used as an index into a global
26 * shared table of hazard pointer state.
27 *
28 * Since the thread ID is only incremented and never decremented, the
29 * table can overflow if threads are frequently created and destroyed.
30 *
31 * A trampoline is a thin wrapper around any function to be called from
32 * a newly launched thread. It maintains a table of thread IDs used by
33 * current and previous threads; when a thread is destroyed, its slot in
34 * the trampoline table becomes available, and the next thread to occupy
35 * that slot can use the same thread ID that its predecessor did.
36 *
37 * The trampoline table initially has space for 64 worker threads in
38 * addition to the main thread. If more threads than that are in
39 * concurrent use, the table is reallocated with twice as much space.
40 * (Note that the number of concurrent threads is currently capped at
41 * 128 by the queue and hazard pointer implementations.)
42 */
43
44typedef struct isc__trampoline isc__trampoline_t;
45
46void
47isc__trampoline_initialize(void);
48/*%<
49 * Initialize the thread trampoline internal structures, must be called only
50 * once as a library constructor (see lib/isc/lib.c).
51 */
52
53void
54isc__trampoline_shutdown(void);
55/*%<
56 * Destroy the thread trampoline internal structures, must be called only
57 * once as a library destructor (see lib/isc/lib.c).
58 */
59
60isc__trampoline_t *
61isc__trampoline_get(isc_threadfunc_t start_routine, isc_threadarg_t arg);
62/*%<
63 * Get a free thread trampoline structure and initialize it with
64 * start_routine and arg passed to start_routine.
65 *
66 * Requires:
67 *\li	'start_routine' is a valid non-NULL thread start_routine
68 */
69
70void
71isc__trampoline_attach(isc__trampoline_t *trampoline);
72void
73isc__trampoline_detach(isc__trampoline_t *trampoline);
74/*%<
75 * Attach/detach the trampoline to/from the current thread.
76 *
77 * Requires:
78 * \li  'trampoline' is a valid isc__trampoline_t
79 */
80
81isc_threadresult_t
82isc__trampoline_run(isc_threadarg_t arg);
83/*%<
84 * Run the thread trampoline, this will get passed to the actual
85 * pthread_create() (or Windows equivalent), initialize the isc_tid_v.
86 *
87 * Requires:
88 *\li	'arg' is a valid isc_trampoline_t
89 *
90 * Returns:
91 *\li	return value from start_routine (see isc__trampoline_get())
92 */
93