CFRunLoop.h   [plain text]


/*
 * 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__ */