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  *
  68  * @constant PTHREAD_INTROSPECTION_THREAD_CREATE
  69  * pthread_t was created.
  70  *
  71  * @constant PTHREAD_INTROSPECTION_THREAD_START
  72  * Thread has started and stack was allocated.
  73  *
  74  * @constant PTHREAD_INTROSPECTION_THREAD_TERMINATE
  75  * Thread is about to be terminated and stack will be deallocated.
  76  *
  77  * @constant PTHREAD_INTROSPECTION_THREAD_DESTROY
  78  * pthread_t is about to be destroyed.
  79  */
  80 enum {
  81         PTHREAD_INTROSPECTION_THREAD_CREATE = 1,
  82         PTHREAD_INTROSPECTION_THREAD_START,
  83         PTHREAD_INTROSPECTION_THREAD_TERMINATE,
  84         PTHREAD_INTROSPECTION_THREAD_DESTROY,
  85 };
  86
  87 /*!
  88  * @function pthread_introspection_hook_install
  89  *
  90  * @abstract
  91  * Install introspection hook function into libpthread.
  92  *
  93  * @discussion
  94  * The caller is responsible for implementing chaining to the hook that was
  95  * previously installed (if any).
  96  *
  97  * @param hook
  98  * Pointer to hook function.
  99  *
 100  * @result
 101  * Previously installed hook function or NULL.
 102  */
 103
 104 __API_AVAILABLE(macos(10.9), ios(7.0))
 105 __attribute__((__nonnull__, __warn_unused_result__))
 106 extern pthread_introspection_hook_t
 107 pthread_introspection_hook_install(pthread_introspection_hook_t hook);
 108
 109 __END_DECLS
 110
 111 #endif