doc/internal/man3/ossl_init_thread_deregister.pod

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