Mac Developer Library

Developer

CoreFoundation Framework Reference CFRunLoopTimer Reference

Options
Deployment Target:

On This Page
Language:

CFRunLoopTimer Reference

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 Toll-Free Bridged Types for more information on toll-free bridging.

Functions

  • Creates a new CFRunLoopTimer object with a block-based handler.

    Declaration

    Swift

    func CFRunLoopTimerCreateWithHandler(_ allocator: CFAllocator!, _ fireDate: CFAbsoluteTime, _ interval: CFTimeInterval, _ flags: CFOptionFlags, _ order: CFIndex, _ block: ((CFRunLoopTimer!) -> Void)!) -> CFRunLoopTimer!

    Objective-C

    CFRunLoopTimerRef CFRunLoopTimerCreateWithHandler ( CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, void (^block)( CFRunLoopTimerRef timer) );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    fireDate

    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 so.

    interval

    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.

    flags

    Currently ignored. Pass 0 for future compatibility.

    order

    A priority index indicating the order in which run loop timers are processed. Run loop timers currently ignore this parameter. Pass 0.

    block

    The block invoked when the timer fires. The block takes one argument:

    timer

    The run loop timer that is firing.

    Return Value

    The new CFRunLoopTimer object. Ownership follows the Create Rule described in Ownership Policy.

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.7 and later.

  • Creates a new CFRunLoopTimer object with a function callback.

    Declaration

    Swift

    func CFRunLoopTimerCreate(_ allocator: CFAllocator!, _ fireDate: CFAbsoluteTime, _ interval: CFTimeInterval, _ flags: CFOptionFlags, _ order: CFIndex, _ callout: CFRunLoopTimerCallBack, _ context: UnsafeMutablePointer<CFRunLoopTimerContext>) -> CFRunLoopTimer!

    Objective-C

    CFRunLoopTimerRef CFRunLoopTimerCreate ( CFAllocatorRef allocator, CFAbsoluteTime fireDate, CFTimeInterval interval, CFOptionFlags flags, CFIndex order, CFRunLoopTimerCallBack callout, CFRunLoopTimerContext *context );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    fireDate

    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 so.

    interval

    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.

    flags

    Currently ignored. Pass 0 for future compatibility.

    order

    A priority index indicating the order in which run loop timers are processed. Run loop timers currently ignore this parameter. Pass 0.

    callout

    The callback function that is called when the timer fires.

    context

    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.

    Return Value

    The new CFRunLoopTimer object. Ownership follows the Create Rule.

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a CFRunLoopTimer object repeats.

    Declaration

    Swift

    func CFRunLoopTimerDoesRepeat(_ timer: CFRunLoopTimer!) -> Boolean

    Objective-C

    Boolean CFRunLoopTimerDoesRepeat ( CFRunLoopTimerRef timer );

    Parameters

    timer

    The run loop timer to test.

    Return Value

    true if timer repeats, or has a periodicity; otherwise false.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the context information for a CFRunLoopTimer object.

    Declaration

    Swift

    func CFRunLoopTimerGetContext(_ timer: CFRunLoopTimer!, _ context: UnsafeMutablePointer<CFRunLoopTimerContext>)

    Objective-C

    void CFRunLoopTimerGetContext ( CFRunLoopTimerRef timer, CFRunLoopTimerContext *context );

    Parameters

    timer

    The run loop timer to examine.

    context

    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.

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the firing interval of a repeating CFRunLoopTimer object.

    Declaration

    Swift

    func CFRunLoopTimerGetInterval(_ timer: CFRunLoopTimer!) -> CFTimeInterval

    Objective-C

    CFTimeInterval CFRunLoopTimerGetInterval ( CFRunLoopTimerRef timer );

    Parameters

    timer

    The run loop timer to examine.

    Return Value

    The firing interval of timer. Returns 0 if timer does not repeat.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the next firing time for a CFRunLoopTimer object.

    Declaration

    Swift

    func CFRunLoopTimerGetNextFireDate(_ timer: CFRunLoopTimer!) -> CFAbsoluteTime

    Objective-C

    CFAbsoluteTime CFRunLoopTimerGetNextFireDate ( CFRunLoopTimerRef timer );

    Parameters

    timer

    The run loop timer to examine.

    Return Value

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the ordering parameter for a CFRunLoopTimer object.

    Declaration

    Swift

    func CFRunLoopTimerGetOrder(_ timer: CFRunLoopTimer!) -> CFIndex

    Objective-C

    CFIndex CFRunLoopTimerGetOrder ( CFRunLoopTimerRef timer );

    Parameters

    timer

    The run loop timer to examine.

    Return Value

    The ordering parameter for timer.

    Discussion

    The ordering parameter is currently ignored by run loop timers.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the type identifier of the CFRunLoopTimer opaque type.

    Declaration

    Swift

    func CFRunLoopTimerGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFRunLoopTimerGetTypeID ( void );

    Return Value

    The type identifier for the CFRunLoopTimer opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Invalidates a CFRunLoopTimer object, stopping it from ever firing again.

    Declaration

    Swift

    func CFRunLoopTimerInvalidate(_ timer: CFRunLoopTimer!)

    Objective-C

    void CFRunLoopTimerInvalidate ( CFRunLoopTimerRef timer );

    Parameters

    timer

    The run loop timer to invalidate.

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a CFRunLoopTimer object is valid and able to fire.

    Declaration

    Swift

    func CFRunLoopTimerIsValid(_ timer: CFRunLoopTimer!) -> Boolean

    Objective-C

    Boolean CFRunLoopTimerIsValid ( CFRunLoopTimerRef timer );

    Parameters

    timer

    The run loop timer to examine.

    Return Value

    true if timer is valid; otherwise false.

    Discussion

    A non-repeating timer is automatically invalidated after it fires.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the next firing date for a CFRunLoopTimer object .

    Declaration

    Swift

    func CFRunLoopTimerSetNextFireDate(_ timer: CFRunLoopTimer!, _ fireDate: CFAbsoluteTime)

    Objective-C

    void CFRunLoopTimerSetNextFireDate ( CFRunLoopTimerRef timer, CFAbsoluteTime fireDate );

    Parameters

    timer

    The run loop timer to modify.

    fireDate

    The new firing time for timer.

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Callbacks

  • Callback invoked when a CFRunLoopTimer object fires.

    Declaration

    Swift

    typealias CFRunLoopTimerCallBack = CFunctionPointer<((CFRunLoopTimer!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CFRunLoopTimerCallBack) ( CFRunLoopTimerRef timer, void *info );

    Parameters

    timer

    The run loop timer that is firing.

    info

    The info member of the CFRunLoopTimerContext structure that was used when creating the run loop timer.

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • A structure that contains program-defined data and callbacks with which you can configure a CFRunLoopTimer’s behavior.

    Declaration

    Swift

    struct CFRunLoopTimerContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)> var release: CFunctionPointer<((UnsafePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)> }

    Objective-C

    struct CFRunLoopTimerContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; }; typedef struct CFRunLoopTimerContext CFRunLoopTimerContext;

    Fields

    version

    Version number of the structure. Must be 0.

    info

    An 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.

    retain

    A retain callback for your program-defined info pointer. Can be NULL.

    release

    A release callback for your program-defined info pointer. Can be NULL.

    copyDescription

    A copy description callback for your program-defined info pointer. Can be NULL.

    Availability

    Available in OS X v10.0 and later.

  • A reference to a run loop timer object.

    Declaration

    Swift

    typealias CFRunLoopTimerRef = CFRunLoopTimer

    Objective-C

    typedef struct __CFRunLoopTimer *CFRunLoopTimerRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.