1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryOSSL_thread_stop_handler_fn, 6*b077aed3SPierre Proncheryossl_init_thread_start, 7*b077aed3SPierre Proncheryossl_init_thread_deregister 8*b077aed3SPierre Pronchery- internal thread routines 9*b077aed3SPierre Pronchery 10*b077aed3SPierre Pronchery=head1 SYNOPSIS 11*b077aed3SPierre Pronchery 12*b077aed3SPierre Pronchery #include "crypto/cryptlib.h" 13*b077aed3SPierre Pronchery #include <openssl/core.h> 14*b077aed3SPierre Pronchery 15*b077aed3SPierre Pronchery typedef void (*OSSL_thread_stop_handler_fn)(void *arg); 16*b077aed3SPierre Pronchery 17*b077aed3SPierre Pronchery int ossl_init_thread_start(const void *index, void *arg, 18*b077aed3SPierre Pronchery OSSL_thread_stop_handler_fn handfn); 19*b077aed3SPierre Pronchery int ossl_init_thread_deregister(void *index); 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery=head1 DESCRIPTION 22*b077aed3SPierre Pronchery 23*b077aed3SPierre ProncheryThread aware code may be informed about when a thread is stopping, typically to 24*b077aed3SPierre Proncheryperform some cleanup operation. 25*b077aed3SPierre ProncheryThread stop events may be detected by OpenSSL either automatically (using the 26*b077aed3SPierre Proncherycapabilities of the underlying threading library) where possible or explicitly 27*b077aed3SPierre Proncheryby the application calling OPENSSL_thread_stop() or OPENSSL_thread_stop_ex(). 28*b077aed3SPierre Pronchery 29*b077aed3SPierre ProncheryThread aware code registers a "stop handler" for each new thread that it uses. 30*b077aed3SPierre ProncheryTypically, when a new thread is being used, code will add a new value to some 31*b077aed3SPierre Proncherythread local variable and then register a stop handler. When the thread is 32*b077aed3SPierre Proncherystopping the stop handler is called (while on that thread) and the code can 33*b077aed3SPierre Proncheryclean up the value stored in the thread local variable. 34*b077aed3SPierre Pronchery 35*b077aed3SPierre ProncheryA new stop handler is registered using the function ossl_init_thread_start(). 36*b077aed3SPierre ProncheryThe I<index> parameter should be a unique value that can be used to identify a 37*b077aed3SPierre Proncheryset of common stop handlers and is passed in a later call to 38*b077aed3SPierre Proncheryossl_init_thread_deregister. If no later call to ossl_init_thread_deregister is 39*b077aed3SPierre Proncherymade then NULL can be passed for this parameter. The I<arg> parameter is passed 40*b077aed3SPierre Proncheryback as an argument to the stop handler when it is later invoked. Finally the 41*b077aed3SPierre ProncheryI<handfn> is a function pointer to the stop handler itself. 42*b077aed3SPierre Pronchery 43*b077aed3SPierre ProncheryIn the event that previously registered stop handlers need to be deregistered 44*b077aed3SPierre Proncherythen this can be done using the function ossl_init_thread_deregister(). 45*b077aed3SPierre ProncheryThis will deregister all stop handlers (no matter which thread they were 46*b077aed3SPierre Proncheryregistered for) which the same I<index> value. 47*b077aed3SPierre Pronchery 48*b077aed3SPierre Pronchery=head1 RETURN VALUES 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Proncheryossl_init_thread_start() and ossl_init_thread_deregister() return 1 for success 51*b077aed3SPierre Proncheryor 0 on error. 52*b077aed3SPierre Pronchery 53*b077aed3SPierre Pronchery=head1 HISTORY 54*b077aed3SPierre Pronchery 55*b077aed3SPierre ProncheryThe functions described here were all added in OpenSSL 3.0. 56*b077aed3SPierre Pronchery 57*b077aed3SPierre Pronchery=head1 COPYRIGHT 58*b077aed3SPierre Pronchery 59*b077aed3SPierre ProncheryCopyright 2019 The OpenSSL Project Authors. All Rights Reserved. 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 62*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 63*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 64*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 65*b077aed3SPierre Pronchery 66*b077aed3SPierre Pronchery=cut 67