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 44 typedef struct isc__trampoline isc__trampoline_t; 45 46 void 47 isc__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 53 void 54 isc__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 60 isc__trampoline_t * 61 isc__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 70 void 71 isc__trampoline_attach(isc__trampoline_t *trampoline); 72 void 73 isc__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 81 isc_threadresult_t 82 isc__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