include/pthread/introspection.h

   1 /*
   2  * Copyright (c) 2013, 2016 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef __PTHREAD_INTROSPECTION__
  25 #define __PTHREAD_INTROSPECTION__
  26
  27 #include <sys/cdefs.h>
  28 #include <pthread/pthread.h>
  29 #include <Availability.h>
  30
  31 /*!
  32  * @header
  33  *
  34  * @abstract
  35  * Introspection API for libpthread.
  36  *
  37  * This should only be used for introspection and debugging tools.  Do not rely
  38  * on it in shipping code.
  39  */
  40
  41 __BEGIN_DECLS
  42
  43 /*!
  44  * @typedef pthread_introspection_hook_t
  45  *
  46  * @abstract
  47  * A function pointer called at various points in a PThread's lifetime.  The
  48  * function must be able to be called in contexts with invalid thread state.
  49  *
  50  * @param event
  51  * One of the events in pthread_introspection_event_t.
  52  *
  53  * @param thread
  54  * pthread_t associated with the event.
  55  *
  56  * @param addr
  57  * Address associated with the event, e.g. stack address.
  58  *
  59  * @param size
  60  * Size associated with the event, e.g. stack size.
  61  */
  62 typedef void (*pthread_introspection_hook_t)(unsigned int event,
  63                 pthread_t thread, void *addr, size_t size);
  64
  65 /*!
  66  * @enum pthread_introspection_event_t
  67  * Events sent by libpthread about threads lifetimes.
  68  *
  69  * @const PTHREAD_INTROSPECTION_THREAD_CREATE
  70  * The specified pthread_t was created, and there will be a paired
  71  * PTHREAD_INTROSPECTION_THREAD_DESTROY event. However, there may not be
  72  * a START/TERMINATE pair of events for this pthread_t.
  73  *
  74  * Starting with macOS 10.14, and iOS 12, this event is always sent before
  75  * PTHREAD_INTROSPECTION_THREAD_START is sent. This event is however not sent
  76  * for the main thread.
  77  *
  78  * This event may not be sent from the context of the passed in pthread_t.
  79  *
  80  * Note that all properties of this thread may not be functional yet, and it is
  81  * not permitted to call functions on this thread past observing its address.
  82  *
  83  * @const PTHREAD_INTROSPECTION_THREAD_START
  84  * Thread has started and its stack was allocated. There will be a matching
  85  * PTHREAD_INTROSPECTION_THREAD_TERMINATE event.
  86  *
  87  * This event is always sent from the context of the passed in pthread_t.
  88  *
  89  * @const PTHREAD_INTROSPECTION_THREAD_TERMINATE
  90  * Thread is about to be terminated and stack will be deallocated. This always
  91  * matches a PTHREAD_INTROSPECTION_THREAD_START event.
  92  *
  93  * This event is always sent from the context of the passed in pthread_t.
  94  *
  95  * @const PTHREAD_INTROSPECTION_THREAD_DESTROY
  96  * pthread_t is about to be destroyed. This always matches
  97  * a PTHREAD_INTROSPECTION_THREAD_CREATE event, but there may not have been
  98  * a START/TERMINATE pair of events for this pthread_t.
  99  *
 100  * This event may not be sent from the context of the passed in pthread_t.
 101  */
 102 enum {
 103         PTHREAD_INTROSPECTION_THREAD_CREATE = 1,
 104         PTHREAD_INTROSPECTION_THREAD_START,
 105         PTHREAD_INTROSPECTION_THREAD_TERMINATE,
 106         PTHREAD_INTROSPECTION_THREAD_DESTROY,
 107 };
 108
 109 /*!
 110  * @function pthread_introspection_hook_install
 111  *
 112  * @abstract
 113  * Install introspection hook function into libpthread.
 114  *
 115  * @discussion
 116  * The caller is responsible for implementing chaining to the hook that was
 117  * previously installed (if any).
 118  *
 119  * @param hook
 120  * Pointer to hook function.
 121  *
 122  * @result
 123  * Previously installed hook function or NULL.
 124  */
 125
 126 __API_AVAILABLE(macos(10.9), ios(7.0))
 127 __attribute__((__nonnull__, __warn_unused_result__))
 128 extern pthread_introspection_hook_t
 129 pthread_introspection_hook_install(pthread_introspection_hook_t hook);
 130
 131 /*!
 132  * @function pthread_introspection_setspecific_np
 133  *
 134  * @abstract
 135  * Performs the moral equivalent of pthread_setspecific() on a target thread
 136  * during the @c PTHREAD_INTROSPECTION_START callback.
 137  *
 138  * @description
 139  * This function is only valid to call during the delivery
 140  * of an @c PTHREAD_INTROSPECTION_THREAD_CREATE introspection hook.
 141  *
 142  * Using this function outside of this context is undefined.
 143  *
 144  * If the created thread is started, then the destructor for this key
 145  * will be called when the thread is terminated. However if the thread
 146  * is not started, it will not be called, and
 147  * pthread_introspection_getspecific_np() must be called manually during
 148  * the @c PTHREAD_INTROSPECTION_THREAD_DESTROY callback to perform manual
 149  * cleanup.
 150  */
 151 __API_AVAILABLE(macos(10.16), ios(14.0), tvos(14.0), watchos(7.0))
 152 int
 153 pthread_introspection_setspecific_np(pthread_t thread,
 154                 pthread_key_t key, const void * _Nullable value);
 155
 156 /*!
 157  * @function pthread_introspection_getspecific_np
 158  *
 159  * @abstract
 160  * Performs the moral equivalent of pthread_getspecific() on a target thread
 161  * during the @c PTHREAD_INTROSPECTION_THREAD_DESTROY callback.
 162  *
 163  * @description
 164  * This function is only valid to call during the delivery
 165  * of an @c PTHREAD_INTROSPECTION_THREAD_DESTROY introspection hook.
 166  *
 167  * If the thread was started then this will always return NULL even
 168  * when pthread_introspection_setspecific_np() was used.
 169  */
 170 __API_AVAILABLE(macos(10.16), ios(14.0), tvos(14.0), watchos(7.0))
 171 void * _Nullable
 172 pthread_introspection_getspecific_np(pthread_t _Nonnull thread,
 173                 pthread_key_t key);
 174
 175 __END_DECLS
 176
 177 #endif