/* * Copyright (c) 2003 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved. * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* CFRunLoop.h Copyright (c) 1998-2003, Apple, Inc. All rights reserved. */ /*! @header CFRunLoop CFRunLoops monitor sources of input to a task and dispatch control when sources become ready for processing. Examples of input sources might include user input devices, network connections, periodic or time-delayed events, and asynchronous callbacks. Input sources are registered with a run loop, and when a run loop is "run", callback functions associated with each source are called when the sources have some activity. There is one run loop per thread. Each run loop has different sets of input sources, called modes, which are named with strings. A run loop is run -- in a named mode -- to have it monitor the sources that have been registered in that mode, and the run loop blocks there until something happens. Examples of modes include the default mode, which a process would normally spend most of its time in, and a modal panel mode, which might be run when a modal panel is up, to restrict the set of input sources that are allowed to "fire". This is not to the granularity of, for example, what type of user input events are interesting, however. That sort of finer-grained granularity is given by UI-level frameworks with "get next event matching mask" or similar functionality. The CFRunLoopSource type is an abstraction of input sources that can be put in a run loop. An input source type would normally define an API for creating and operating on instances of the type, as if it were a separate entity from the run loop, then provide a function to create a CFRunLoopSource for an instance. The CFRunLoopSource can then be registered with the run loop, represents the input source to the run loop, and acts as intermediary between the run loop and the actual input source type instance. Examples include CFMachPort and CFSocket. A CFRunLoopTimer is a specialization of run loop sources, a way to generate either a one-shot delayed action, or a recurrent action. While being run, a run loop goes through a cycle of activities. Input sources are checked, timers which need firing are fired, and then the run loop blocks, waiting for something to happen (or in the case of timers, waiting for it to be time for something to happen). When something does happen, the run loop wakes up, processes the activity (usually by calling a callback function for an input source), checks other sources, fires timers, and goes back to sleep. And so on. CFRunLoopObservers can be used to do processing at special points in this cycle. */ #if !defined(__COREFOUNDATION_CFRUNLOOP__) #define __COREFOUNDATION_CFRUNLOOP__ 1 #include <CoreFoundation/CFBase.h> #include <CoreFoundation/CFArray.h> #include <CoreFoundation/CFDate.h> #include <CoreFoundation/CFString.h> #if defined(__MACH__) #include <mach/port.h> #endif #if defined(__cplusplus) extern "C" { #endif /*! @typedef CFRunLoopRef This is the type of a reference to a run loop. */ typedef struct __CFRunLoop * CFRunLoopRef; /*! @typedef CFRunLoopSourceRef This is the type of a reference to general run loop input sources. */ typedef struct __CFRunLoopSource * CFRunLoopSourceRef; /*! @typedef CFRunLoopObserverRef This is the type of a reference to a run loop observer. */ typedef struct __CFRunLoopObserver * CFRunLoopObserverRef; /*! @typedef CFRunLoopTimerRef This is the type of a reference to a run loop timer. */ typedef struct __CFRunLoopTimer * CFRunLoopTimerRef; /* Reasons for CFRunLoopRunInMode() to Return */ enum { kCFRunLoopRunFinished = 1, kCFRunLoopRunStopped = 2, kCFRunLoopRunTimedOut = 3, kCFRunLoopRunHandledSource = 4 }; /* Run Loop Observer Activities */ typedef enum { kCFRunLoopEntry = (1 << 0), kCFRunLoopBeforeTimers = (1 << 1), kCFRunLoopBeforeSources = (1 << 2), kCFRunLoopBeforeWaiting = (1 << 5), kCFRunLoopAfterWaiting = (1 << 6), kCFRunLoopExit = (1 << 7), kCFRunLoopAllActivities = 0x0FFFFFFFU } CFRunLoopActivity; CF_EXPORT const CFStringRef kCFRunLoopDefaultMode; CF_EXPORT const CFStringRef kCFRunLoopCommonModes; /*! @function CFRunLoopGetTypeID Returns the type identifier of all CFRunLoop instances. */ CF_EXPORT CFTypeID CFRunLoopGetTypeID(void); /*! @function CFRunLoopGetCurrent Returns the run loop for the current thread. There is exactly one run loop per thread. */ CF_EXPORT CFRunLoopRef CFRunLoopGetCurrent(void); /*! @function CFRunLoopCopyCurrentMode Returns the name of the mode in which the run loop is running. NULL is returned if the run loop is not running. @param rl The run loop for which the current mode should be reported. */ CF_EXPORT CFStringRef CFRunLoopCopyCurrentMode(CFRunLoopRef rl); /*! @function CFRunLoopCopyAllModes Returns an array of all the names of the modes known to the run loop. @param rl The run loop for which the mode list should be returned. */ CF_EXPORT CFArrayRef CFRunLoopCopyAllModes(CFRunLoopRef rl); /*! @function CFRunLoopAddCommonMode Makes the named mode a "common mode" for the run loop. The set of common modes are collectively accessed with the global constant kCFRunLoopCommonModes. Input sources previously added to the common modes are added to the new common mode. @param rl The run loop for which the mode should be made common. @param mode The name of the mode to mark as a common mode. */ CF_EXPORT void CFRunLoopAddCommonMode(CFRunLoopRef rl, CFStringRef mode); /*! @function CFRunLoopGetNextTimerFireDate Returns the time at which the next timer will fire. @param rl The run loop for which the next timer fire date should be reported. @param mode The name of the mode to query. */ CF_EXPORT CFAbsoluteTime CFRunLoopGetNextTimerFireDate(CFRunLoopRef rl, CFStringRef mode); CF_EXPORT void CFRunLoopRun(void); CF_EXPORT SInt32 CFRunLoopRunInMode(CFStringRef mode, CFTimeInterval seconds, Boolean returnAfterSourceHandled); CF_EXPORT Boolean CFRunLoopIsWaiting(CFRunLoopRef rl); CF_EXPORT void CFRunLoopWakeUp(CFRunLoopRef rl); CF_EXPORT void CFRunLoopStop(CFRunLoopRef rl); CF_EXPORT Boolean CFRunLoopContainsSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode); CF_EXPORT void CFRunLoopAddSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode); CF_EXPORT void CFRunLoopRemoveSource(CFRunLoopRef rl, CFRunLoopSourceRef source, CFStringRef mode); CF_EXPORT Boolean CFRunLoopContainsObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode); CF_EXPORT void CFRunLoopAddObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode); CF_EXPORT void CFRunLoopRemoveObserver(CFRunLoopRef rl, CFRunLoopObserverRef observer, CFStringRef mode); CF_EXPORT Boolean CFRunLoopContainsTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode); CF_EXPORT void CFRunLoopAddTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode); CF_EXPORT void CFRunLoopRemoveTimer(CFRunLoopRef rl, CFRunLoopTimerRef timer, CFStringRef mode); /*! @typedef CFRunLoopSourceContext Structure containing the callbacks of a CFRunLoopSource. @field version The version number of the structure type being passed in as a parameter to the CFArray creation functions. Valid version numbers are currently 0 and 1. Version 0 sources are fairly generic, but may require a bit more implementation, or may require a separate thread as part of the implementation, for a complex source. Version 1 sources are available on Mach, and have performance advantages when the source type can be described with this style. @field info An arbitrary pointer to client-defined data, which can be associated with the source at creation time, and is passed to the callbacks. @field retain The callback used to add a retain for the source on the info pointer for the life of the source, and may be used for temporary references the source needs to take. This callback returns the actual info pointer to store in the source, almost always just the pointer passed as the parameter. @field release The callback used to remove a retain previously added for the source on the info pointer. @field copyDescription The callback used to create a descriptive string representation of the info pointer (or the data pointed to by the info pointer) for debugging purposes. This is used by the CFCopyDescription() function. @field equal The callback used to compare the info pointers of two sources, to determine equality of sources. @field hash The callback used to compute a hash code for the info pointer for the source. The source uses this hash code information to produce its own hash code. @field schedule For a version 0 source, this callback is called whenever the source is added to a run loop mode. This information is often needed to implement complex sources. @field cancel For a version 0 source, this callback is called whenever the source is removed from a run loop mode. This information is often needed to implement complex sources. @field getPort Defined in version 1 sources, this function returns the Mach port to represent the source to the run loop. This function must return the same Mach port every time it is called, for the lifetime of the source, and should be quick. @field perform This callback is the workhorse of a run loop source. It is called when the source needs to be "handled" or processing is needed for input or conditions relating to the source. For version 0 sources, this function is called when the source has been marked "signaled" with the CFRunLoopSourceSignal() function, and should do whatever handling is required for the source. For a version 1 source, this function is called when a Mach message arrives on the source's Mach port, with the Mach message, its length, an allocator, and the source's info pointer. A version 1 source performs whatever processing is required on the Mach message, then can return a pointer to a Mach message (or NULL if none) to be sent (usually this is a "reply" message), which should be allocated with the allocator (and will be deallocated by the run loop after sending). */ typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); Boolean (*equal)(const void *info1, const void *info2); CFHashCode (*hash)(const void *info); void (*schedule)(void *info, CFRunLoopRef rl, CFStringRef mode); void (*cancel)(void *info, CFRunLoopRef rl, CFStringRef mode); void (*perform)(void *info); } CFRunLoopSourceContext; #if defined(__MACH__) typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); Boolean (*equal)(const void *info1, const void *info2); CFHashCode (*hash)(const void *info); mach_port_t (*getPort)(void *info); void * (*perform)(void *msg, CFIndex size, CFAllocatorRef allocator, void *info); } CFRunLoopSourceContext1; #endif /*! @function CFRunLoopSourceGetTypeID Returns the type identifier of all CFRunLoopSource instances. */ CF_EXPORT CFTypeID CFRunLoopSourceGetTypeID(void); /*! @function CFRunLoopSourceCreate Creates a new run loop source with the given context. @param allocator The CFAllocator which should be used to allocate memory for the array and its storage for values. If this reference is not a valid CFAllocator, the behavior is undefined. @param order On platforms which support it, for source versions which support it, this parameter determines the order in which the sources which are ready to be processed are handled. A lower order number causes processing before higher order number sources. It is inadvisable to depend on the order number for any architectural or design aspect of code. In the absence of any reason to do otherwise, zero should be used. @param context A pointer to the context structure for the source. */ CF_EXPORT CFRunLoopSourceRef CFRunLoopSourceCreate(CFAllocatorRef allocator, CFIndex order, CFRunLoopSourceContext *context); /*! @function CFRunLoopSourceGetOrder Returns the ordering parameter of the run loop source. @param source The run loop source for which the order number should be returned. */ CF_EXPORT CFIndex CFRunLoopSourceGetOrder(CFRunLoopSourceRef source); /*! @function CFRunLoopSourceInvalidate Invalidates the run loop source. The run loop source is never performed again after it becomes invalid, and will automatically be removed from any run loops and modes which contain it. The source is not destroyed by this operation, however -- the memory is still valid; only the release of all references on the source through the reference counting system can do that. But note, that if the only retains on the source were held by run loops, those retains may all be released by the time this function returns, and the source may actually be destroyed through that process. @param source The run loop source which should be invalidated. */ CF_EXPORT void CFRunLoopSourceInvalidate(CFRunLoopSourceRef source); /*! @function CFRunLoopSourceIsValid Reports whether or not the source is valid. @param source The run loop source for which the validity should be returned. */ CF_EXPORT Boolean CFRunLoopSourceIsValid(CFRunLoopSourceRef source); /*! @function CFRunLoopSourceGetContext Fills the memory pointed to by the context parameter with the context structure of the source. @param source The run loop source for which the context structure should be returned. @param context A pointer to a context structure to be filled. */ CF_EXPORT void CFRunLoopSourceGetContext(CFRunLoopSourceRef source, CFRunLoopSourceContext *context); /*! @function CFRunLoopSourceSignal Marks the source as signalled, ready for handling by the run loop. Has no effect on version 1 sources, which are automatically handled when Mach messages for them come in. @param source The run loop source which should be signalled. */ CF_EXPORT void CFRunLoopSourceSignal(CFRunLoopSourceRef source); typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } CFRunLoopObserverContext; typedef void (*CFRunLoopObserverCallBack)(CFRunLoopObserverRef observer, CFRunLoopActivity activity, void *info); /*! @function CFRunLoopObserverGetTypeID Returns the type identifier of all CFRunLoopObserver instances. */ CF_EXPORT CFTypeID CFRunLoopObserverGetTypeID(void); CF_EXPORT CFRunLoopObserverRef CFRunLoopObserverCreate(CFAllocatorRef allocator, CFOptionFlags activities, Boolean repeats, CFIndex order, CFRunLoopObserverCallBack callout, CFRunLoopObserverContext *context); CF_EXPORT CFOptionFlags CFRunLoopObserverGetActivities(CFRunLoopObserverRef observer); CF_EXPORT Boolean CFRunLoopObserverDoesRepeat(CFRunLoopObserverRef observer); CF_EXPORT CFIndex CFRunLoopObserverGetOrder(CFRunLoopObserverRef observer); CF_EXPORT void CFRunLoopObserverInvalidate(CFRunLoopObserverRef observer); CF_EXPORT Boolean CFRunLoopObserverIsValid(CFRunLoopObserverRef observer); CF_EXPORT void CFRunLoopObserverGetContext(CFRunLoopObserverRef observer, CFRunLoopObserverContext *context); typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } CFRunLoopTimerContext; typedef void (*CFRunLoopTimerCallBack)(CFRunLoopTimerRef timer, void *info); /*! @function CFRunLoopTimerGetTypeID Returns the type identifier of all CFRunLoopTimer instances. */ CF_EXPORT CFTypeID CFRunLoopTimerGetTypeID(void); CF_EXPORT CFRunLoopTimerRef CFRunLoopTimerCreate(CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, CFRunLoopTimerCallBack callout, CFRunLoopTimerContext *context); CF_EXPORT CFAbsoluteTime CFRunLoopTimerGetNextFireDate(CFRunLoopTimerRef timer); CF_EXPORT void CFRunLoopTimerSetNextFireDate(CFRunLoopTimerRef timer, CFAbsoluteTime fireDate); CF_EXPORT CFTimeInterval CFRunLoopTimerGetInterval(CFRunLoopTimerRef timer); CF_EXPORT Boolean CFRunLoopTimerDoesRepeat(CFRunLoopTimerRef timer); CF_EXPORT CFIndex CFRunLoopTimerGetOrder(CFRunLoopTimerRef timer); CF_EXPORT void CFRunLoopTimerInvalidate(CFRunLoopTimerRef timer); CF_EXPORT Boolean CFRunLoopTimerIsValid(CFRunLoopTimerRef timer); CF_EXPORT void CFRunLoopTimerGetContext(CFRunLoopTimerRef timer, CFRunLoopTimerContext *context); #if defined(__cplusplus) } #endif #endif /* ! __COREFOUNDATION_CFRUNLOOP__ */