RunLoop.subproj/CFRunLoop.h

   1 /*
   2  * Copyright (c) 2005 Apple Computer, 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 /*      CFRunLoop.h
  24         Copyright (c) 1998-2005, Apple, Inc. All rights reserved.
  25 */
  26
  27 /*!
  28         @header CFRunLoop
  29         CFRunLoops monitor sources of input to a task and dispatch control
  30         when sources become ready for processing. Examples of input sources
  31         might include user input devices, network connections, periodic
  32         or time-delayed events, and asynchronous callbacks. Input sources
  33         are registered with a run loop, and when a run loop is "run",
  34         callback functions associated with each source are called when
  35         the sources have some activity.
  36
  37         There is one run loop per thread. Each run loop has different
  38         sets of input sources, called modes, which are named with strings.
  39         A run loop is run -- in a named mode -- to have it monitor the
  40         sources that have been registered in that mode, and the run loop
  41         blocks there until something happens. Examples of modes include
  42         the default mode, which a process would normally spend most of
  43         its time in, and a modal panel mode, which might be run when
  44         a modal panel is up, to restrict the set of input sources that
  45         are allowed to "fire". This is not to the granularity of, for
  46         example, what type of user input events are interesting, however.
  47         That sort of finer-grained granularity is given by UI-level
  48         frameworks with "get next event matching mask" or similar
  49         functionality.
  50
  51         The CFRunLoopSource type is an abstraction of input sources that
  52         can be put in a run loop. An input source type would normally
  53         define an API for creating and operating on instances of the type,
  54         as if it were a separate entity from the run loop, then provide a
  55         function to create a CFRunLoopSource for an instance. The
  56         CFRunLoopSource can then be registered with the run loop,
  57         represents the input source to the run loop, and acts as
  58         intermediary between the run loop and the actual input source
  59         type instance. Examples include CFMachPort and CFSocket.
  60
  61         A CFRunLoopTimer is a specialization of run loop sources, a way
  62         to generate either a one-shot delayed action, or a recurrent
  63         action.
  64
  65         While being run, a run loop goes through a cycle of activities.
  66         Input sources are checked, timers which need firing are fired,
  67         and then the run loop blocks, waiting for something to happen
  68         (or in the case of timers, waiting for it to be time for
  69         something to happen). When something does happen, the run loop
  70         wakes up, processes the activity (usually by calling a callback
  71         function for an input source), checks other sources, fires timers,
  72         and goes back to sleep. And so on. CFRunLoopObservers can be
  73         used to do processing at special points in this cycle.
  74
  75
  76
  77
  78 */
  79
  80 #if !defined(__COREFOUNDATION_CFRUNLOOP__)
  81 #define __COREFOUNDATION_CFRUNLOOP__ 1
  82
  83 #include <CoreFoundation/CFBase.h>
  84 #include <CoreFoundation/CFArray.h>
  85 #include <CoreFoundation/CFDate.h>
  86 #include <CoreFoundation/CFString.h>
  87 #if defined(__MACH__)
  88     #include <mach/port.h>
  89 #endif
  90
  91 #if defined(__cplusplus)
  92 extern "C" {
  93 #endif
  94
  95 /*!
  96         @typedef CFRunLoopRef
  97         This is the type of a reference to a run loop.
  98 */
  99 typedef struct __CFRunLoop * CFRunLoopRef;
 100
 101 /*!
 102         @typedef CFRunLoopSourceRef
 103         This is the type of a reference to general run loop input sources.
 104 */
 105 typedef struct __CFRunLoopSource * CFRunLoopSourceRef;
 106
 107 /*!
 108         @typedef CFRunLoopObserverRef
 109         This is the type of a reference to a run loop observer.
 110 */
 111 typedef struct __CFRunLoopObserver * CFRunLoopObserverRef;
 112
 113 /*!
 114         @typedef CFRunLoopTimerRef
 115         This is the type of a reference to a run loop timer.
 116 */
 117 typedef struct __CFRunLoopTimer * CFRunLoopTimerRef;
 118
 119 /* Reasons for CFRunLoopRunInMode() to Return */
 120 enum {
 121     kCFRunLoopRunFinished = 1,
 122     kCFRunLoopRunStopped = 2,
 123     kCFRunLoopRunTimedOut = 3,
 124     kCFRunLoopRunHandledSource = 4
 125 };
 126
 127 /* Run Loop Observer Activities */
 128 typedef enum {
 129     kCFRunLoopEntry = (1 << 0),
 130     kCFRunLoopBeforeTimers = (1 << 1),
 131     kCFRunLoopBeforeSources = (1 << 2),
 132     kCFRunLoopBeforeWaiting = (1 << 5),
 133     kCFRunLoopAfterWaiting = (1 << 6),
 134     kCFRunLoopExit = (1 << 7),
 135     kCFRunLoopAllActivities = 0x0FFFFFFFU
 136 } CFRunLoopActivity;
 137
 138 CF_EXPORT const CFStringRef kCFRunLoopDefaultMode;
 139 CF_EXPORT const CFStringRef kCFRunLoopCommonModes;
 140
 141 /*!
 142         @function CFRunLoopGetTypeID
 143         Returns the type identifier of all CFRunLoop instances.
 144 */
 145 CF_EXPORT CFTypeID CFRunLoopGetTypeID(void);
 146
 147 /*!
 148         @function CFRunLoopGetCurrent
 149         Returns the run loop for the current thread. There is exactly
 150         one run loop per thread.
 151 */
 152 CF_EXPORT CFRunLoopRef CFRunLoopGetCurrent(void);
 153
 154 /*!
 155         @function CFRunLoopCopyCurrentMode
 156         Returns the name of the mode in which the run loop is running.
 157         NULL is returned if the run loop is not running.
 158         @param rl The run loop for which the current mode should be
 159                 reported.
 160 */
 161 CF_EXPORT CFStringRef CFRunLoopCopyCurrentMode(CFRunLoopRef rl);
 162
 163 /*!
 164         @function CFRunLoopCopyAllModes
 165         Returns an array of all the names of the modes known to the run
 166         loop.
 167         @param rl The run loop for which the mode list should be returned.
 168 */
 169 CF_EXPORT CFArrayRef CFRunLoopCopyAllModes(CFRunLoopRef rl);
 170
 171 /*!
 172         @function CFRunLoopAddCommonMode
 173         Makes the named mode a "common mode" for the run loop. The set of
 174         common modes are collectively accessed with the global constant
 175         kCFRunLoopCommonModes. Input sources previously added to the
 176         common modes are added to the new common mode.
 177         @param rl The run loop for which the mode should be made common.
 178         @param mode The name of the mode to mark as a common mode.
 179 */
 180 CF_EXPORT void CFRunLoopAddCommonMode(CFRunLoopRef rl, CFStringRef mode);
 181
 182 /*!
 183         @function CFRunLoopGetNextTimerFireDate
 184         Returns the time at which the next timer will fire.
 185         @param rl The run loop for which the next timer fire date should
 186                 be reported.
 187         @param mode The name of the mode to query.
 188 */
 189 CF_EXPORT CFAbsoluteTime CFRunLoopGetNextTimerFireDate(CFRunLoopRef rl, CFStringRef mode);
 190
 191
 192
 193
 194
 195 CF_EXPORT void CFRunLoopRun(void);
 196 CF_EXPORT SInt32 CFRunLoopRunInMode(CFStringRef mode, CFTimeInterval seconds, Boolean returnAfterSourceHandled);
 197 CF_EXPORT Boolean CFRunLoopIsWaiting(CFRunLoopRef rl);
 198 CF_EXPORT void CFRunLoopWakeUp(CFRunLoopRef rl);
 199 CF_EXPORT void CFRunLoopStop(CFRunLoopRef rl);
 200
 201 CF_EXPORT Boolean CFRunLoopContainsSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
 202 CF_EXPORT void CFRunLoopAddSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
 203 CF_EXPORT void CFRunLoopRemoveSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode);
 204
 205 CF_EXPORT Boolean CFRunLoopContainsObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
 206 CF_EXPORT void CFRunLoopAddObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
 207 CF_EXPORT void CFRunLoopRemoveObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode);
 208
 209 CF_EXPORT Boolean CFRunLoopContainsTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
 210 CF_EXPORT void CFRunLoopAddTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
 211 CF_EXPORT void CFRunLoopRemoveTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode);
 212
 213 /*!
 214         @typedef CFRunLoopSourceContext
 215         Structure containing the callbacks of a CFRunLoopSource.
 216         @field version The version number of the structure type being
 217                 passed in as a parameter to the CFArray creation
 218                 functions. Valid version numbers are currently 0 and 1.
 219                 Version 0 sources are fairly generic, but may require a
 220                 bit more implementation, or may require a separate
 221                 thread as part of the implementation, for a complex
 222                 source. Version 1 sources are available on Mach and Windows,
 223                 and have performance advantages when the source type can
 224                 be described with this style.
 225         @field info An arbitrary pointer to client-defined data, which
 226                 can be associated with the source at creation time, and
 227                 is passed to the callbacks.
 228         @field retain The callback used to add a retain for the source on
 229                 the info pointer for the life of the source, and may be
 230                 used for temporary references the source needs to take.
 231                 This callback returns the actual info pointer to store in
 232                 the source, almost always just the pointer passed as the
 233                 parameter.
 234         @field release The callback used to remove a retain previously
 235                 added for the source on the info pointer.
 236         @field copyDescription The callback used to create a descriptive
 237                 string representation of the info pointer (or the data
 238                 pointed to by the info pointer) for debugging purposes.
 239                 This is used by the CFCopyDescription() function.
 240         @field equal The callback used to compare the info pointers of
 241                 two sources, to determine equality of sources.
 242         @field hash The callback used to compute a hash code for the info
 243                 pointer for the source. The source uses this hash code
 244                 information to produce its own hash code.
 245         @field schedule For a version 0 source, this callback is called
 246                 whenever the source is added to a run loop mode. This
 247                 information is often needed to implement complex sources.
 248         @field cancel For a version 0 source, this callback is called
 249                 whenever the source is removed from a run loop mode. This
 250                 information is often needed to implement complex sources.
 251         @field getPort Defined in version 1 sources, this function returns
 252                 the Mach port or Windows HANDLE of a kernel object to
 253                 represent the source to the run loop.  This function
 254                 must return the same result every time it is called, for the
 255                 lifetime of the source, and should be quick.
 256         @field perform This callback is the workhorse of a run loop source.
 257                 It is called when the source needs to be "handled" or
 258                 processing is needed for input or conditions relating to
 259                 the source. For version 0 sources, this function is called
 260                 when the source has been marked "signaled" with the
 261                 CFRunLoopSourceSignal() function, and should do whatever
 262                 handling is required for the source. For a version 1 source
 263                 on Mach, this function is called when a Mach message arrives
 264                 on the source's Mach port, with the message, its
 265                 length, an allocator, and the source's info pointer. A
 266                 version 1 source performs whatever processing is required
 267                 on the Mach message, then can return a pointer to a Mach
 268                 message (or NULL if none) to be sent (usually this is a
 269                 "reply" message), which should be allocated with the
 270                 allocator (and will be deallocated by the run loop after
 271                 sending).  For a version 1 source on Windows the function
 272                 is called when the kernel object is in the signaled state.
 273 */
 274 typedef struct {
 275     CFIndex     version;
 276     void *      info;
 277     const void *(*retain)(const void *info);
 278     void        (*release)(const void *info);
 279     CFStringRef (*copyDescription)(const void *info);
 280     Boolean     (*equal)(const void *info1, const void *info2);
 281     CFHashCode  (*hash)(const void *info);
 282     void        (*schedule)(void *info, CFRunLoopRef rl, CFStringRef mode);
 283     void        (*cancel)(void *info, CFRunLoopRef rl, CFStringRef mode);
 284     void        (*perform)(void *info);
 285 } CFRunLoopSourceContext;
 286
 287 typedef struct {
 288     CFIndex     version;
 289     void *      info;
 290     const void *(*retain)(const void *info);
 291     void        (*release)(const void *info);
 292     CFStringRef (*copyDescription)(const void *info);
 293     Boolean     (*equal)(const void *info1, const void *info2);
 294     CFHashCode  (*hash)(const void *info);
 295 #if defined(__MACH__)
 296     mach_port_t (*getPort)(void *info);
 297     void *      (*perform)(void *msg, CFIndex size, CFAllocatorRef allocator, void *info);
 298 #else
 299     HANDLE      (*getPort)(void *info);
 300     void        (*perform)(void *info);
 301 #endif
 302 } CFRunLoopSourceContext1;
 303
 304 /*!
 305         @function CFRunLoopSourceGetTypeID
 306         Returns the type identifier of all CFRunLoopSource instances.
 307 */
 308 CF_EXPORT CFTypeID CFRunLoopSourceGetTypeID(void);
 309
 310 /*!
 311         @function CFRunLoopSourceCreate
 312         Creates a new run loop source with the given context.
 313         @param allocator The CFAllocator which should be used to allocate
 314                 memory for the array and its storage for values. If this
 315                 reference is not a valid CFAllocator, the behavior is
 316                 undefined.
 317         @param order On platforms which support it, for source versions
 318                 which support it, this parameter determines the order in
 319                 which the sources which are ready to be processed are
 320                 handled. A lower order number causes processing before
 321                 higher order number sources. It is inadvisable to depend
 322                 on the order number for any architectural or design aspect
 323                 of code. In the absence of any reason to do otherwise,
 324                 zero should be used.
 325         @param context A pointer to the context structure for the source.
 326 */
 327 CF_EXPORT CFRunLoopSourceRef CFRunLoopSourceCreate(CFAllocatorRef allocator, CFIndex order, CFRunLoopSourceContext *context);
 328
 329 /*!
 330         @function CFRunLoopSourceGetOrder
 331         Returns the ordering parameter of the run loop source.
 332         @param source The run loop source for which the order number
 333                 should be returned.
 334 */
 335 CF_EXPORT CFIndex CFRunLoopSourceGetOrder(CFRunLoopSourceRef source);
 336
 337 /*!
 338         @function CFRunLoopSourceInvalidate
 339         Invalidates the run loop source. The run loop source is never
 340         performed again after it becomes invalid, and will automatically
 341         be removed from any run loops and modes which contain it. The
 342         source is not destroyed by this operation, however -- the memory
 343         is still valid; only the release of all references on the source
 344         through the reference counting system can do that. But note, that
 345         if the only retains on the source were held by run loops, those
 346         retains may all be released by the time this function returns,
 347         and the source may actually be destroyed through that process.
 348         @param source The run loop source which should be invalidated.
 349 */
 350 CF_EXPORT void CFRunLoopSourceInvalidate(CFRunLoopSourceRef source);
 351
 352 /*!
 353         @function CFRunLoopSourceIsValid
 354         Reports whether or not the source is valid.
 355         @param source The run loop source for which the validity should
 356                 be returned.
 357 */
 358 CF_EXPORT Boolean CFRunLoopSourceIsValid(CFRunLoopSourceRef source);
 359
 360 /*!
 361         @function CFRunLoopSourceGetContext
 362         Fills the memory pointed to by the context parameter with the
 363         context structure of the source.
 364         @param source The run loop source for which the context structure
 365                 should be returned.
 366         @param context A pointer to a context structure to be filled.
 367 */
 368 CF_EXPORT void CFRunLoopSourceGetContext(CFRunLoopSourceRef source, CFRunLoopSourceContext *context);
 369
 370 /*!
 371         @function CFRunLoopSourceSignal
 372         Marks the source as signalled, ready for handling by the run loop.
 373         Has no effect on version 1 sources, which are automatically
 374         handled when Mach messages for them come in.
 375         @param source The run loop source which should be signalled.
 376 */
 377 CF_EXPORT void CFRunLoopSourceSignal(CFRunLoopSourceRef source);
 378
 379 typedef struct {
 380     CFIndex     version;
 381     void *      info;
 382     const void *(*retain)(const void *info);
 383     void        (*release)(const void *info);
 384     CFStringRef (*copyDescription)(const void *info);
 385 } CFRunLoopObserverContext;
 386
 387 typedef void (*CFRunLoopObserverCallBack)(CFRunLoopObserverRef observer, CFRunLoopActivity activity, void *info);
 388
 389 /*!
 390         @function CFRunLoopObserverGetTypeID
 391         Returns the type identifier of all CFRunLoopObserver instances.
 392 */
 393 CF_EXPORT CFTypeID CFRunLoopObserverGetTypeID(void);
 394
 395 CF_EXPORT CFRunLoopObserverRef CFRunLoopObserverCreate(CFAllocatorRef allocator, CFOptionFlags activities, Boolean repeats, CFIndex order, CFRunLoopObserverCallBack callout, CFRunLoopObserverContext *context);
 396
 397 CF_EXPORT CFOptionFlags CFRunLoopObserverGetActivities(CFRunLoopObserverRef observer);
 398 CF_EXPORT Boolean CFRunLoopObserverDoesRepeat(CFRunLoopObserverRef observer);
 399 CF_EXPORT CFIndex CFRunLoopObserverGetOrder(CFRunLoopObserverRef observer);
 400 CF_EXPORT void CFRunLoopObserverInvalidate(CFRunLoopObserverRef observer);
 401 CF_EXPORT Boolean CFRunLoopObserverIsValid(CFRunLoopObserverRef observer);
 402 CF_EXPORT void CFRunLoopObserverGetContext(CFRunLoopObserverRef observer, CFRunLoopObserverContext *context);
 403
 404 typedef struct {
 405     CFIndex     version;
 406     void *      info;
 407     const void *(*retain)(const void *info);
 408     void        (*release)(const void *info);
 409     CFStringRef (*copyDescription)(const void *info);
 410 } CFRunLoopTimerContext;
 411
 412 typedef void (*CFRunLoopTimerCallBack)(CFRunLoopTimerRef timer, void *info);
 413
 414 /*!
 415         @function CFRunLoopTimerGetTypeID
 416         Returns the type identifier of all CFRunLoopTimer instances.
 417 */
 418 CF_EXPORT CFTypeID CFRunLoopTimerGetTypeID(void);
 419
 420 CF_EXPORT CFRunLoopTimerRef CFRunLoopTimerCreate(CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, CFRunLoopTimerCallBack callout, CFRunLoopTimerContext *context);
 421 CF_EXPORT CFAbsoluteTime CFRunLoopTimerGetNextFireDate(CFRunLoopTimerRef timer);
 422 CF_EXPORT void CFRunLoopTimerSetNextFireDate(CFRunLoopTimerRef timer, CFAbsoluteTime fireDate);
 423 CF_EXPORT CFTimeInterval CFRunLoopTimerGetInterval(CFRunLoopTimerRef timer);
 424 CF_EXPORT Boolean CFRunLoopTimerDoesRepeat(CFRunLoopTimerRef timer);
 425 CF_EXPORT CFIndex CFRunLoopTimerGetOrder(CFRunLoopTimerRef timer);
 426 CF_EXPORT void CFRunLoopTimerInvalidate(CFRunLoopTimerRef timer);
 427 CF_EXPORT Boolean CFRunLoopTimerIsValid(CFRunLoopTimerRef timer);
 428 CF_EXPORT void CFRunLoopTimerGetContext(CFRunLoopTimerRef timer, CFRunLoopTimerContext *context);
 429
 430 #if defined(__cplusplus)
 431 }
 432 #endif
 433
 434 #endif /* ! __COREFOUNDATION_CFRUNLOOP__ */
 435