1/*
2 * Copyright (c) 2007, 2012 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24#ifndef __PTHREAD_WORKQUEUE_H__
25#define __PTHREAD_WORKQUEUE_H__
26
27#include <sys/cdefs.h>
28#include <Availability.h>
29#include <pthread/pthread.h>
30#include <pthread/qos.h>
31#ifndef _PTHREAD_BUILDING_PTHREAD_
32#include <pthread/qos_private.h>
33#endif
34
35#define PTHREAD_WORKQUEUE_SPI_VERSION 20140730
36
37/* Feature checking flags, returned by _pthread_workqueue_supported()
38 *
39 * Note: These bits should match the definition of PTHREAD_FEATURE_*
40 * bits defined in libpthread/kern/kern_internal.h */
41
42#define WORKQ_FEATURE_DISPATCHFUNC	0x01	// pthread_workqueue_setdispatch_np is supported (or not)
43#define WORKQ_FEATURE_FINEPRIO		0x02	// fine grained pthread workq priorities
44#define WORKQ_FEATURE_MAINTENANCE	0x10	// QOS class maintenance
45
46/* Legacy dispatch priority bands */
47
48#define WORKQ_NUM_PRIOQUEUE	4
49
50#define WORKQ_HIGH_PRIOQUEUE	0	// high priority queue
51#define WORKQ_DEFAULT_PRIOQUEUE	1	// default priority queue
52#define WORKQ_LOW_PRIOQUEUE	2	// low priority queue
53#define WORKQ_BG_PRIOQUEUE	3	// background priority queue
54#define WORKQ_NON_INTERACTIVE_PRIOQUEUE 128 // libdispatch SPI level
55
56/* Legacy dispatch workqueue function flags */
57#define WORKQ_ADDTHREADS_OPTION_OVERCOMMIT 0x00000001
58
59__BEGIN_DECLS
60
61// Legacy callback prototype, used with pthread_workqueue_setdispatch_np
62typedef void (*pthread_workqueue_function_t)(int queue_priority, int options, void *ctxt);
63// New callback prototype, used with pthread_workqueue_init
64typedef void (*pthread_workqueue_function2_t)(pthread_priority_t priority);
65
66// Initialises the pthread workqueue subsystem, passing the new-style callback prototype,
67// the dispatchoffset and an unused flags field.
68__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
69int
70_pthread_workqueue_init(pthread_workqueue_function2_t func, int offset, int flags);
71
72// Non-zero enables kill on current thread, zero disables it.
73__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2)
74int
75__pthread_workqueue_setkill(int);
76
77// Dispatch function to be called when new worker threads are created.
78__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
79int
80pthread_workqueue_setdispatch_np(pthread_workqueue_function_t worker_func);
81
82// Dispatch offset to be set in the kernel.
83__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
84void
85pthread_workqueue_setdispatchoffset_np(int offset);
86
87// Request additional worker threads.
88__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
89int
90pthread_workqueue_addthreads_np(int queue_priority, int options, int numthreads);
91
92// Retrieve the supported pthread feature set
93__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
94int
95_pthread_workqueue_supported(void);
96
97// Request worker threads (fine grained priority)
98__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
99int
100_pthread_workqueue_addthreads(int numthreads, pthread_priority_t priority);
101
102// Apply a QoS override without allocating userspace memory
103__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
104int
105_pthread_override_qos_class_start_direct(mach_port_t thread, pthread_priority_t priority);
106
107// Drop a corresponding QoS override made above.
108__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
109int
110_pthread_override_qos_class_end_direct(mach_port_t thread);
111
112// Apply a QoS override on a given workqueue thread.
113__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
114int
115_pthread_workqueue_override_start_direct(mach_port_t thread, pthread_priority_t priority);
116
117// Drop all QoS overrides on the current workqueue thread.
118__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
119int
120_pthread_workqueue_override_reset(void);
121
122__END_DECLS
123
124#endif // __PTHREAD_WORKQUEUE_H__
125