doc/internal/man3/ossl_init_thread_deregister.pod

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