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