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 __END_DECLS
 132
 133 #endif