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