]> git.saurik.com Git - apple/libdispatch.git/blob - dispatch/introspection.h
libdispatch-703.1.4.tar.gz
[apple/libdispatch.git] / 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 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_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 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_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 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_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 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_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 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_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 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_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 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_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