private/private.h

   1 /*
   2  * Copyright (c) 2008-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 /*
  22  * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
  23  * which are subject to change in future releases of Mac OS X. Any applications
  24  * relying on these interfaces WILL break.
  25  */
  26
  27 #ifndef __DISPATCH_PRIVATE__
  28 #define __DISPATCH_PRIVATE__
  29
  30 #ifdef __APPLE__
  31 #include <TargetConditionals.h>
  32 #endif
  33
  34 #if TARGET_OS_MAC
  35 #include <mach/boolean.h>
  36 #include <mach/mach.h>
  37 #include <mach/message.h>
  38 #endif
  39 #if HAVE_UNISTD_H
  40 #include <unistd.h>
  41 #endif
  42 #if HAVE_SYS_CDEFS_H
  43 #include <sys/cdefs.h>
  44 #endif
  45 #include <pthread.h>
  46
  47 #ifndef __DISPATCH_BUILDING_DISPATCH__
  48 #include <dispatch/dispatch.h>
  49
  50 #ifndef __DISPATCH_INDIRECT__
  51 #define __DISPATCH_INDIRECT__
  52 #endif
  53
  54 #include <dispatch/benchmark.h>
  55 #include <dispatch/queue_private.h>
  56 #include <dispatch/source_private.h>
  57 #if DISPATCH_MACH_SPI
  58 #include <dispatch/mach_private.h>
  59 #endif // DISPATCH_MACH_SPI
  60 #include <dispatch/data_private.h>
  61 #include <dispatch/io_private.h>
  62 #include <dispatch/layout_private.h>
  63
  64 #undef __DISPATCH_INDIRECT__
  65
  66 #endif /* !__DISPATCH_BUILDING_DISPATCH__ */
  67
  68 // <rdar://problem/9627726> Check that public and private dispatch headers match
  69 #if DISPATCH_API_VERSION != 20160712 // Keep in sync with <dispatch/dispatch.h>
  70 #error "Dispatch header mismatch between /usr/include and /usr/local/include"
  71 #endif
  72
  73 DISPATCH_ASSUME_NONNULL_BEGIN
  74
  75 __BEGIN_DECLS
  76
  77 /*!
  78  * @function _dispatch_is_multithreaded
  79  *
  80  * @abstract
  81  * Returns true if the current process has become multithreaded by the use
  82  * of libdispatch functionality.
  83  *
  84  * @discussion
  85  * This SPI is intended for use by low-level system components that need to
  86  * ensure that they do not make a single-threaded process multithreaded, to
  87  * avoid negatively affecting child processes of a fork (without exec).
  88  *
  89  * Such components must not use any libdispatch functionality if this function
  90  * returns false.
  91  *
  92  * @result
  93  * Boolean indicating whether the process has used libdispatch and become
  94  * multithreaded.
  95  */
  96 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_6_0)
  97 DISPATCH_EXPORT DISPATCH_NOTHROW
  98 bool _dispatch_is_multithreaded(void);
  99
 100 /*!
 101  * @function _dispatch_is_fork_of_multithreaded_parent
 102  *
 103  * @abstract
 104  * Returns true if the current process is a child of a parent process that had
 105  * become multithreaded by the use of libdispatch functionality at the time of
 106  * fork (without exec).
 107  *
 108  * @discussion
 109  * This SPI is intended for use by (rare) low-level system components that need
 110  * to continue working on the child side of a fork (without exec) of a
 111  * multithreaded process.
 112  *
 113  * Such components must not use any libdispatch functionality if this function
 114  * returns true.
 115  *
 116  * @result
 117  * Boolean indicating whether the parent process had used libdispatch and
 118  * become multithreaded at the time of fork.
 119  */
 120 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 121 DISPATCH_EXPORT DISPATCH_NOTHROW
 122 bool _dispatch_is_fork_of_multithreaded_parent(void);
 123
 124 /*!
 125  * @function _dispatch_prohibit_transition_to_multithreaded
 126  *
 127  * @abstract
 128  * Sets a mode that aborts if a program tries to use dispatch.
 129  *
 130  * @discussion
 131  * This SPI is intended for use by programs that know they will use fork() and
 132  * want their children to be able to use dispatch before exec(). Such programs
 133  * should call _dispatch_prohibit_transition_to_multithreaded(true) as early as
 134  * possible, which will cause any use of dispatch API that would make the
 135  * process multithreaded to abort immediately.
 136  *
 137  * Once the program no longer intends to call fork() it can call
 138  * _dispatch_prohibit_transition_to_multithreaded(false).
 139  *
 140  * This status is not inherited by the child process, so if the behavior
 141  * is required after fork, _dispatch_prohibit_transition_to_multithreaded(true)
 142  * should be called manually in the child after fork.
 143  *
 144  * If the program already used dispatch before the guard is enabled, then
 145  * this function will abort immediately.
 146  */
 147 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 148 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 149 DISPATCH_EXPORT DISPATCH_NOTHROW
 150 void _dispatch_prohibit_transition_to_multithreaded(bool prohibit);
 151
 152 /*
 153  * dispatch_time convenience macros
 154  */
 155
 156 #define _dispatch_time_after_nsec(t) \
 157                 dispatch_time(DISPATCH_TIME_NOW, (t))
 158 #define _dispatch_time_after_usec(t) \
 159                 dispatch_time(DISPATCH_TIME_NOW, (t) * NSEC_PER_USEC)
 160 #define _dispatch_time_after_msec(t) \
 161                 dispatch_time(DISPATCH_TIME_NOW, (t) * NSEC_PER_MSEC)
 162 #define _dispatch_time_after_sec(t) \
 163                 dispatch_time(DISPATCH_TIME_NOW, (t) * NSEC_PER_SEC)
 164
 165 /*
 166  * SPI for CoreFoundation/Foundation ONLY
 167  */
 168
 169 #if TARGET_OS_MAC
 170 #define DISPATCH_COCOA_COMPAT 1
 171 #elif defined(__linux__)
 172 #define DISPATCH_COCOA_COMPAT 1
 173 #else
 174 #define DISPATCH_COCOA_COMPAT 0
 175 #endif
 176
 177 #if DISPATCH_COCOA_COMPAT
 178
 179 #define DISPATCH_CF_SPI_VERSION 20160712
 180
 181 #if TARGET_OS_MAC
 182 typedef mach_port_t dispatch_runloop_handle_t;
 183 #elif defined(__linux__)
 184 typedef int dispatch_runloop_handle_t;
 185 #else
 186 #error "runloop support not implemented on this platform"
 187 #endif
 188
 189 #if TARGET_OS_MAC
 190 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 191 DISPATCH_EXPORT DISPATCH_CONST DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 192 dispatch_runloop_handle_t
 193 _dispatch_get_main_queue_port_4CF(void);
 194 #endif
 195
 196 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 197 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 198 DISPATCH_EXPORT DISPATCH_NOTHROW
 199 dispatch_runloop_handle_t
 200 _dispatch_get_main_queue_handle_4CF(void);
 201
 202 #if TARGET_OS_MAC
 203 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 204 DISPATCH_EXPORT DISPATCH_NOTHROW
 205 void
 206 _dispatch_main_queue_callback_4CF(mach_msg_header_t *_Null_unspecified msg);
 207 #else
 208 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 209 DISPATCH_EXPORT DISPATCH_NOTHROW
 210 void
 211 _dispatch_main_queue_callback_4CF(void *_Null_unspecified msg);
 212 #endif
 213
 214 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 215 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 216 DISPATCH_NOTHROW
 217 dispatch_queue_t
 218 _dispatch_runloop_root_queue_create_4CF(const char *_Nullable label,
 219                 unsigned long flags);
 220
 221 #if TARGET_OS_MAC
 222 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 223 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 224 mach_port_t
 225 _dispatch_runloop_root_queue_get_port_4CF(dispatch_queue_t queue);
 226 #endif
 227
 228 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 229 DISPATCH_EXPORT DISPATCH_NOTHROW
 230 void
 231 _dispatch_runloop_root_queue_wakeup_4CF(dispatch_queue_t queue);
 232
 233 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 234 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 235 bool
 236 _dispatch_runloop_root_queue_perform_4CF(dispatch_queue_t queue);
 237
 238 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 239 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 240 void
 241 _dispatch_source_set_runloop_timer_4CF(dispatch_source_t source,
 242                 dispatch_time_t start, uint64_t interval, uint64_t leeway);
 243
 244 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 245 DISPATCH_EXPORT
 246 void *_Nonnull (*_Nullable _dispatch_begin_NSAutoReleasePool)(void);
 247
 248 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 249 DISPATCH_EXPORT
 250 void (*_Nullable _dispatch_end_NSAutoReleasePool)(void *);
 251
 252 #endif /* DISPATCH_COCOA_COMPAT */
 253
 254 __END_DECLS
 255
 256 DISPATCH_ASSUME_NONNULL_END
 257
 258 #endif // __DISPATCH_PRIVATE__