/*
* Copyright (c) 2005 Apple Computer, Inc. All rights reserved.
*
* @APPLE_LICENSE_HEADER_START@
*
* 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-2005, 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
#include
#include
#include
#if defined(__MACH__)
#include
#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 Windows,
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 or Windows HANDLE of a kernel object to
represent the source to the run loop. This function
must return the same result 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
on Mach, this function is called when a Mach message arrives
on the source's Mach port, with the 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). For a version 1 source on Windows the function
is called when the kernel object is in the signaled state.
*/
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;
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);
#if defined(__MACH__)
mach_port_t (*getPort)(void *info);
void * (*perform)(void *msg, CFIndex size, CFAllocatorRef allocator, void *info);
#else
HANDLE (*getPort)(void *info);
void (*perform)(void *info);
#endif
} CFRunLoopSourceContext1;
/*!
@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__ */