diff options
Diffstat (limited to '')
-rw-r--r-- | lib/isc/trampoline_p.h | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/lib/isc/trampoline_p.h b/lib/isc/trampoline_p.h new file mode 100644 index 0000000..4599ea1 --- /dev/null +++ b/lib/isc/trampoline_p.h @@ -0,0 +1,90 @@ +/* + * Copyright (C) Internet Systems Consortium, Inc. ("ISC") + * + * SPDX-License-Identifier: MPL-2.0 + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, you can obtain one at https://mozilla.org/MPL/2.0/. + * + * See the COPYRIGHT file distributed with this work for additional + * information regarding copyright ownership. + */ + +#pragma once + +#include <isc/thread.h> + +/*! \file isc/trampoline_p.h + * \brief isc__trampoline: allows safe reuse of thread ID numbers. + * + * The 'isc_hp' hazard pointer API uses an internal thread ID + * variable ('tid_v') that is incremented for each new thread that uses + * hazard pointers. This thread ID is then used as an index into a global + * shared table of hazard pointer state. + * + * Since the thread ID is only incremented and never decremented, the + * table can overflow if threads are frequently created and destroyed. + * + * A trampoline is a thin wrapper around any function to be called from + * a newly launched thread. It maintains a table of thread IDs used by + * current and previous threads; when a thread is destroyed, its slot in + * the trampoline table becomes available, and the next thread to occupy + * that slot can use the same thread ID that its predecessor did. + * + * The trampoline table initially has space for 64 worker threads in + * addition to the main thread. If more threads than that are in + * concurrent use, the table is reallocated with twice as much space. + * (Note that the number of concurrent threads is currently capped at + * 128 by the queue and hazard pointer implementations.) + */ + +typedef struct isc__trampoline isc__trampoline_t; + +void +isc__trampoline_initialize(void); +/*%< + * Initialize the thread trampoline internal structures, must be called only + * once as a library constructor (see lib/isc/lib.c). + */ + +void +isc__trampoline_shutdown(void); +/*%< + * Destroy the thread trampoline internal structures, must be called only + * once as a library destructor (see lib/isc/lib.c). + */ + +isc__trampoline_t * +isc__trampoline_get(isc_threadfunc_t start_routine, isc_threadarg_t arg); +/*%< + * Get a free thread trampoline structure and initialize it with + * start_routine and arg passed to start_routine. + * + * Requires: + *\li 'start_routine' is a valid non-NULL thread start_routine + */ + +void +isc__trampoline_attach(isc__trampoline_t *trampoline); +void +isc__trampoline_detach(isc__trampoline_t *trampoline); +/*%< + * Attach/detach the trampoline to/from the current thread. + * + * Requires: + * \li 'trampoline' is a valid isc__trampoline_t + */ + +isc_threadresult_t +isc__trampoline_run(isc_threadarg_t arg); +/*%< + * Run the thread trampoline, this will get passed to the actual + * pthread_create() (or Windows equivalent), initialize the isc_tid_v. + * + * Requires: + *\li 'arg' is a valid isc_trampoline_t + * + * Returns: + *\li return value from start_routine (see isc__trampoline_get()) + */ |