RunLoop.subproj/CFRunLoop.h

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