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 /*!
  27  * @header
  28  *
  29  * @abstract
  30  * Interposable introspection hooks for libdispatch.
  31  *
  32  * @discussion
  33  * These hooks are only available in the introspection version of the library,
  34  * loaded by running a process with the environment variable
  35  * DYLD_LIBRARY_PATH=/usr/lib/system/introspection
  36  */
  37
  38 __BEGIN_DECLS
  39
  40 /*!
  41  * @function dispatch_introspection_hook_queue_create
  42  *
  43  * @abstract
  44  * Interposable hook function called when a dispatch queue was created.
  45  *
  46  * @param queue
  47  * The newly created dispatch queue.
  48  */
  49
  50 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
  51 DISPATCH_EXPORT
  52 void
  53 dispatch_introspection_hook_queue_create(dispatch_queue_t queue);
  54
  55 /*!
  56  * @function dispatch_introspection_hook_queue_destroy
  57  *
  58  * @abstract
  59  * Interposable hook function called when a dispatch queue is about to be
  60  * destroyed.
  61  *
  62  * @param queue
  63  * The dispatch queue about to be destroyed.
  64  */
  65
  66 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
  67 DISPATCH_EXPORT
  68 void
  69 dispatch_introspection_hook_queue_destroy(dispatch_queue_t queue);
  70
  71 /*!
  72  * @function dispatch_introspection_hook_queue_item_enqueue
  73  *
  74  * @abstract
  75  * Interposable hook function called when an item is about to be enqueued onto
  76  * a dispatch queue.
  77  *
  78  * @param queue
  79  * The dispatch queue enqueued onto.
  80  *
  81  * @param item
  82  * The object about to be enqueued.
  83  */
  84
  85 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
  86 DISPATCH_EXPORT
  87 void
  88 dispatch_introspection_hook_queue_item_enqueue(dispatch_queue_t queue,
  89                 dispatch_object_t item);
  90
  91 /*!
  92  * @function dispatch_introspection_hook_queue_item_dequeue
  93  *
  94  * @abstract
  95  * Interposable hook function called when an item was dequeued from a dispatch
  96  * queue.
  97  *
  98  * @param queue
  99  * The dispatch queue dequeued from.
 100  *
 101  * @param item
 102  * The dequeued object.
 103  */
 104
 105 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 106 DISPATCH_EXPORT
 107 void
 108 dispatch_introspection_hook_queue_item_dequeue(dispatch_queue_t queue,
 109                 dispatch_object_t item);
 110
 111 /*!
 112  * @function dispatch_introspection_hook_queue_item_complete
 113  *
 114  * @abstract
 115  * Interposable hook function called when an item previously dequeued from a
 116  * dispatch queue has completed processing.
 117  *
 118  * @discussion
 119  * The object pointer value passed to this function must be treated as a value
 120  * only. It is intended solely for matching up with an earlier call to a
 121  * dequeue hook function and must NOT be dereferenced.
 122  *
 123  * @param item
 124  * Opaque dentifier for completed item. Must NOT be dereferenced.
 125  */
 126
 127 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_7_1)
 128 DISPATCH_EXPORT
 129 void
 130 dispatch_introspection_hook_queue_item_complete(dispatch_object_t item);
 131
 132 /*!
 133  * @function dispatch_introspection_hook_queue_callout_begin
 134  *
 135  * @abstract
 136  * Interposable hook function called when a client function is about to be
 137  * called out to on a dispatch queue.
 138  *
 139  * @param queue
 140  * The dispatch queue the callout is performed on.
 141  *
 142  * @param context
 143  * The context parameter passed to the function. For a callout to a block,
 144  * this is a pointer to the block object.
 145  *
 146  * @param function
 147  * The client function about to be called out to. For a callout to a block,
 148  * this is the block object's invoke function.
 149  */
 150
 151 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 152 DISPATCH_EXPORT
 153 void
 154 dispatch_introspection_hook_queue_callout_begin(dispatch_queue_t queue,
 155                 void *context, dispatch_function_t function);
 156
 157 /*!
 158  * @function dispatch_introspection_hook_queue_callout_end
 159  *
 160  * @abstract
 161  * Interposable hook function called after a client function has returned from
 162  * a callout on a dispatch queue.
 163  *
 164  * @param queue
 165  * The dispatch queue the callout was performed on.
 166  *
 167  * @param context
 168  * The context parameter passed to the function. For a callout to a block,
 169  * this is a pointer to the block object.
 170  *
 171  * @param function
 172  * The client function that was called out to. For a callout to a block,
 173  * this is the block object's invoke function.
 174  */
 175
 176 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 177 DISPATCH_EXPORT
 178 void
 179 dispatch_introspection_hook_queue_callout_end(dispatch_queue_t queue,
 180                 void *context, dispatch_function_t function);
 181
 182 __END_DECLS
 183
 184 #endif