| Derived from | |
| Framework | CoreFoundation/CoreFoundation.h |
| Companion guide | Run Loops |
| Declared in | CFRunLoop.h |
A CFRunLoopTimer object represents a specialized run loop source that fires at a preset time in the future. Timers can fire either only once or repeatedly at fixed time intervals. Repeating timers can also have their next firing time manually adjusted.
A timer is not a real-time mechanism; it fires only when one of the run loop modes to which the timer has been added is running and able to check if the timer’s firing time has passed. If a timer’s firing time occurs while the run loop is in a mode that is not monitoring the timer or during a long callout, the timer does not fire until the next time the run loop checks the timer. Therefore, the actual time at which the timer fires potentially can be a significant period of time after the scheduled firing time.
A repeating timer reschedules itself based on the scheduled firing time, not the actual firing time. For example, if a timer is scheduled to fire at a particular time and every 5 seconds after that, the scheduled firing time will always fall on the original 5 second time intervals, even if the actual firing time gets delayed. If the firing time is delayed so far that it passes one or more of the scheduled firing times, the timer is fired only once for that time period; the timer is then rescheduled, after firing, for the next scheduled firing time in the future.
Each run loop timer can be registered in only one run loop at a time, although it can be added to multiple run loop modes within that run loop.
CFRunLoopTimer is “toll-free bridged” with its Cocoa Foundation counterpart, NSTimer. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSTimer * parameter, you can pass in a CFRunLoopTimerRef, and in a function where you see a CFRunLoopTimerRef parameter, you can pass in an NSTimer instance. This also applies to concrete subclasses of NSTimer. See Interchangeable Data Types for more information on toll-free bridging.
Creates a new CFRunLoopTimer object.
CFRunLoopTimerRef CFRunLoopTimerCreate ( CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, CFRunLoopTimerCallBack callout, CFRunLoopTimerContext *context );
The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
The time at which the timer should first fire. The fine precision (sub-millisecond at most) of the fire date may be adjusted slightly by the timer if there are implementation reasons to do.
The firing interval of the timer. If 0 or negative, the timer fires once and then is automatically invalidated. The fine precision (sub-millisecond at most) of the interval may be adjusted slightly by the timer if implementation reasons to do so exist.
Currently ignored. Pass 0 for future compatibility.
A priority index indicating the order in which run loop timers are processed. Run loop timers currently ignore this parameter. Pass 0.
The callback function that is called when the timer fires.
A structure holding contextual information for the run loop timer. The function copies the information out of the structure, so the memory pointed to by context does not need to persist beyond the function call. Can be NULL if the callback function does not need the context’s info pointer to keep track of state.
The new CFRunLoopTimer object. Ownership follows the Create Rule.
A timer needs to be added to a run loop mode before it will fire. To add the timer to a run loop, use CFRunLoopAddTimer. A timer can be registered to only one run loop at a time, although it can be in multiple modes within that run loop.
CFRunLoop.hReturns a Boolean value that indicates whether a CFRunLoopTimer object repeats.
Boolean CFRunLoopTimerDoesRepeat ( CFRunLoopTimerRef timer );
The run loop timer to test.
true if timer repeats, or has a periodicity; otherwise false.
CFRunLoop.hReturns the context information for a CFRunLoopTimer object.
void CFRunLoopTimerGetContext ( CFRunLoopTimerRef timer, CFRunLoopTimerContext *context );
The run loop timer to examine.
A pointer to the structure into which the context information for timer is to be copied. The information being returned is the same information passed to CFRunLoopTimerCreate when creating timer.
The context version number for run loop timers is currently 0. Before calling this function, you need to initialize the version member of context to 0.
CFRunLoop.hReturns the firing interval of a repeating CFRunLoopTimer object.
CFTimeInterval CFRunLoopTimerGetInterval ( CFRunLoopTimerRef timer );
The run loop timer to examine.
The firing interval of timer. Returns 0 if timer does not repeat.
CFRunLoop.hReturns the next firing time for a CFRunLoopTimer object.
CFAbsoluteTime CFRunLoopTimerGetNextFireDate ( CFRunLoopTimerRef timer );
The run loop timer to examine.
The next firing time for timer. This time could be a date in the past if a run loop has not been able to process the timer since the firing time arrived.
CFRunLoop.hReturns the ordering parameter for a CFRunLoopTimer object.
CFIndex CFRunLoopTimerGetOrder ( CFRunLoopTimerRef timer );
The run loop timer to examine.
The ordering parameter for timer.
The ordering parameter is currently ignored by run loop timers.
CFRunLoop.hReturns the type identifier of the CFRunLoopTimer opaque type.
CFTypeID CFRunLoopTimerGetTypeID ( void );
The type identifier for the CFRunLoopTimer opaque type.
CFRunLoop.hInvalidates a CFRunLoopTimer object, stopping it from ever firing again.
void CFRunLoopTimerInvalidate ( CFRunLoopTimerRef timer );
The run loop timer to invalidate.
Once invalidated, timer will never fire and call its callback function again. This function automatically removes timer from all run loop modes in which it had been added. The memory is not deallocated unless the run loop held the only reference to timer.
CFRunLoop.hReturns a Boolean value that indicates whether a CFRunLoopTimer object is valid and able to fire.
Boolean CFRunLoopTimerIsValid ( CFRunLoopTimerRef timer );
The run loop timer to examine.
true if timer is valid; otherwise false.
A nonrepeating timer is automatically invalidated after it fires.
CFRunLoop.hSets the next firing date for a CFRunLoopTimer object .
void CFRunLoopTimerSetNextFireDate ( CFRunLoopTimerRef timer, CFAbsoluteTime fireDate );
The run loop timer to modify.
The new firing time for timer.
Resetting a timer’s next firing time is a relatively expensive operation and should not be done if it can be avoided; letting timers autorepeat is more efficient. In some cases, however, manually-adjusted, repeating timers are useful. For example, if you have an action that will be performed multiple times in the future, but at irregular time intervals, it would be very expensive to create, add to run loop modes, and then destroy a timer for each firing event. Instead, you can create a repeating timer with an initial firing time in the distant future (or the initial firing time) and a very large repeat interval—on the order of decades or more—and add it to all the necessary run loop modes. Then, when you know when the timer should fire next, you reset the firing time with CFRunLoopTimerSetNextFireDate, perhaps from the timer’s own callback function. This technique effectively produces a reusable, asynchronous timer.
CFRunLoop.hCallback invoked when a CFRunLoopTimer object fires.
typedef void (*CFRunLoopTimerCallBack) ( CFRunLoopTimerRef timer, void *info );
If you name your function MyCallBack, you would declare it like this:
void MyCallBack ( CFRunLoopTimerRef timer, void *info );
The run loop timer that is firing.
The info member of the CFRunLoopTimerContext structure that was used when creating the run loop timer.
If timer repeats, the run loop automatically schedules the next firing time after calling this function, unless you manually update the firing time within this callback by calling CFRunLoopTimerSetNextFireDate. If timer does not repeat, the run loop invalidates timer.
You specify this callback when you create the timer with CFRunLoopTimerCreate.
CFRunLoop.hA structure that contains program-defined data and callbacks with which you can configure a CFRunLoopTimer’s behavior.
struct CFRunLoopTimerContext {
CFIndex version;
void *info;
CFAllocatorRetainCallBack retain;
CFAllocatorReleaseCallBack release;
CFAllocatorCopyDescriptionCallBack copyDescription;
};
typedef struct CFRunLoopTimerContext CFRunLoopTimerContext;
versionVersion number of the structure. Must be 0.
infoAn arbitrary pointer to program-defined data, which can be associated with the run loop timer at creation time. This pointer is passed to all the callbacks defined in the context.
retainA retain callback for your program-defined info pointer. Can be NULL.
releaseA release callback for your program-defined info pointer. Can be NULL.
copyDescriptionA copy description callback for your program-defined info pointer. Can be NULL.
CFRunLoop.hA reference to a run loop timer object.
typedef struct __CFRunLoopTimer *CFRunLoopTimerRef;
CFRunLoop.hLast updated: 2006-02-07
