[apple/libdispatch.git] / dispatch / introspection.h

/*
 * Copyright (c) 2013 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

#ifndef __DISPATCH_INTROSPECTION__
#define __DISPATCH_INTROSPECTION__

#include <dispatch/dispatch.h>

/*!
 * @header
 *
 * @abstract
 * Interposable introspection hooks for libdispatch.
 *
 * @discussion
 * These hooks are only available in the introspection version of the library,
 * loaded by running a process with the environment variable
 * DYLD_LIBRARY_PATH=/usr/lib/system/introspection
 */

__BEGIN_DECLS

/*!
 * @function dispatch_introspection_hook_queue_create
 *
 * @abstract
 * Interposable hook function called when a dispatch queue was created.
 *
 * @param queue
 * The newly created dispatch queue.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_create(dispatch_queue_t queue);

/*!
 * @function dispatch_introspection_hook_queue_destroy
 *
 * @abstract
 * Interposable hook function called when a dispatch queue is about to be
 * destroyed.
 *
 * @param queue
 * The dispatch queue about to be destroyed.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_destroy(dispatch_queue_t queue);

/*!
 * @function dispatch_introspection_hook_queue_item_enqueue
 *
 * @abstract
 * Interposable hook function called when an item is about to be enqueued onto
 * a dispatch queue.
 *
 * @param queue
 * The dispatch queue enqueued onto.
 *
 * @param item
 * The object about to be enqueued.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_item_enqueue(dispatch_queue_t queue,
		dispatch_object_t item);

/*!
 * @function dispatch_introspection_hook_queue_item_dequeue
 *
 * @abstract
 * Interposable hook function called when an item was dequeued from a dispatch
 * queue.
 *
 * @param queue
 * The dispatch queue dequeued from.
 *
 * @param item
 * The dequeued object.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_item_dequeue(dispatch_queue_t queue,
		dispatch_object_t item);

/*!
 * @function dispatch_introspection_hook_queue_item_complete
 *
 * @abstract
 * Interposable hook function called when an item previously dequeued from a
 * dispatch queue has completed processing.
 *
 * @discussion
 * The object pointer value passed to this function must be treated as a value
 * only. It is intended solely for matching up with an earlier call to a
 * dequeue hook function and must NOT be dereferenced.
 *
 * @param item
 * Opaque dentifier for completed item. Must NOT be dereferenced.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_7_1)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_item_complete(dispatch_object_t item);

/*!
 * @function dispatch_introspection_hook_queue_callout_begin
 *
 * @abstract
 * Interposable hook function called when a client function is about to be
 * called out to on a dispatch queue.
 *
 * @param queue
 * The dispatch queue the callout is performed on.
 *
 * @param context
 * The context parameter passed to the function. For a callout to a block,
 * this is a pointer to the block object.
 *
 * @param function
 * The client function about to be called out to. For a callout to a block,
 * this is the block object's invoke function.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_callout_begin(dispatch_queue_t queue,
		void *context, dispatch_function_t function);

/*!
 * @function dispatch_introspection_hook_queue_callout_end
 *
 * @abstract
 * Interposable hook function called after a client function has returned from
 * a callout on a dispatch queue.
 *
 * @param queue
 * The dispatch queue the callout was performed on.
 *
 * @param context
 * The context parameter passed to the function. For a callout to a block,
 * this is a pointer to the block object.
 *
 * @param function
 * The client function that was called out to. For a callout to a block,
 * this is the block object's invoke function.
 */

__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
DISPATCH_EXPORT
void
dispatch_introspection_hook_queue_callout_end(dispatch_queue_t queue,
		void *context, dispatch_function_t function);

__END_DECLS

#endif
Commit	Line	Data
517da941 A	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
98cf8cd2 A	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
517da941 A	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