dispatch/introspection.h

   1 /*
   2  * Copyright (c) 2013 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 #ifndef __DISPATCH_INTROSPECTION__
  22 #define __DISPATCH_INTROSPECTION__
  23
  24 #include <dispatch/dispatch.h>
  25
  26 DISPATCH_ASSUME_NONNULL_BEGIN
  27
  28 /*!
  29  * @header
  30  *
  31  * @abstract
  32  * Interposable introspection hooks for libdispatch.
  33  *
  34  * @discussion
  35  * These hooks are only available in the introspection version of the library,
  36  * loaded by running a process with the environment variable
  37  * DYLD_LIBRARY_PATH=/usr/lib/system/introspection
  38  */
  39
  40 __BEGIN_DECLS
  41
  42 /*!
  43  * @function dispatch_introspection_hook_queue_create
  44  *
  45  * @abstract
  46  * Interposable hook function called when a dispatch queue was created.
  47  *
  48  * @param queue
  49  * The newly created dispatch queue.
  50  */
  51
  52 API_AVAILABLE(macos(10.9), ios(7.0))
  53 DISPATCH_EXPORT
  54 void
  55 dispatch_introspection_hook_queue_create(dispatch_queue_t queue);
  56
  57 /*!
  58  * @function dispatch_introspection_hook_queue_destroy
  59  *
  60  * @abstract
  61  * Interposable hook function called when a dispatch queue is about to be
  62  * destroyed.
  63  *
  64  * @param queue
  65  * The dispatch queue about to be destroyed.
  66  */
  67
  68 API_AVAILABLE(macos(10.9), ios(7.0))
  69 DISPATCH_EXPORT
  70 void
  71 dispatch_introspection_hook_queue_destroy(dispatch_queue_t queue);
  72
  73 /*!
  74  * @function dispatch_introspection_hook_queue_item_enqueue
  75  *
  76  * @abstract
  77  * Interposable hook function called when an item is about to be enqueued onto
  78  * a dispatch queue.
  79  *
  80  * @param queue
  81  * The dispatch queue enqueued onto.
  82  *
  83  * @param item
  84  * The object about to be enqueued.
  85  */
  86
  87 API_AVAILABLE(macos(10.9), ios(7.0))
  88 DISPATCH_EXPORT
  89 void
  90 dispatch_introspection_hook_queue_item_enqueue(dispatch_queue_t queue,
  91                 dispatch_object_t item);
  92
  93 /*!
  94  * @function dispatch_introspection_hook_queue_item_dequeue
  95  *
  96  * @abstract
  97  * Interposable hook function called when an item was dequeued from a dispatch
  98  * queue.
  99  *
 100  * @param queue
 101  * The dispatch queue dequeued from.
 102  *
 103  * @param item
 104  * The dequeued object.
 105  */
 106
 107 API_AVAILABLE(macos(10.9), ios(7.0))
 108 DISPATCH_EXPORT
 109 void
 110 dispatch_introspection_hook_queue_item_dequeue(dispatch_queue_t queue,
 111                 dispatch_object_t item);
 112
 113 /*!
 114  * @function dispatch_introspection_hook_queue_item_complete
 115  *
 116  * @abstract
 117  * Interposable hook function called when an item previously dequeued from a
 118  * dispatch queue has completed processing.
 119  *
 120  * @discussion
 121  * The object pointer value passed to this function must be treated as a value
 122  * only. It is intended solely for matching up with an earlier call to a
 123  * dequeue hook function and must NOT be dereferenced.
 124  *
 125  * @param item
 126  * Opaque dentifier for completed item. Must NOT be dereferenced.
 127  */
 128
 129 API_AVAILABLE(macos(10.10), ios(7.1))
 130 DISPATCH_EXPORT
 131 void
 132 dispatch_introspection_hook_queue_item_complete(dispatch_object_t item);
 133
 134 /*!
 135  * @function dispatch_introspection_hook_queue_callout_begin
 136  *
 137  * @abstract
 138  * Interposable hook function called when a client function is about to be
 139  * called out to on a dispatch queue.
 140  *
 141  * @param queue
 142  * The dispatch queue the callout is performed on.
 143  *
 144  * @param context
 145  * The context parameter passed to the function. For a callout to a block,
 146  * this is a pointer to the block object.
 147  *
 148  * @param function
 149  * The client function about to be called out to. For a callout to a block,
 150  * this is the block object's invoke function.
 151  */
 152
 153 API_AVAILABLE(macos(10.9), ios(7.0))
 154 DISPATCH_EXPORT
 155 void
 156 dispatch_introspection_hook_queue_callout_begin(dispatch_queue_t queue,
 157                 void *_Nullable context, dispatch_function_t function);
 158
 159 /*!
 160  * @function dispatch_introspection_hook_queue_callout_end
 161  *
 162  * @abstract
 163  * Interposable hook function called after a client function has returned from
 164  * a callout on a dispatch queue.
 165  *
 166  * @param queue
 167  * The dispatch queue the callout was performed on.
 168  *
 169  * @param context
 170  * The context parameter passed to the function. For a callout to a block,
 171  * this is a pointer to the block object.
 172  *
 173  * @param function
 174  * The client function that was called out to. For a callout to a block,
 175  * this is the block object's invoke function.
 176  */
 177
 178 API_AVAILABLE(macos(10.9), ios(7.0))
 179 DISPATCH_EXPORT
 180 void
 181 dispatch_introspection_hook_queue_callout_end(dispatch_queue_t queue,
 182                 void *_Nullable context, dispatch_function_t function);
 183
 184 __END_DECLS
 185
 186 DISPATCH_ASSUME_NONNULL_END
 187
 188 #endif