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 185