iOS Developer Library

Developer

CoreFoundation Framework Reference CFRunLoopSource Reference

Options
Deployment Target:

On This Page
Language:

CFRunLoopSource Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreFoundation

Objective-C

@import CoreFoundation;

A CFRunLoopSource object is an abstraction of an input source that can be put into a run loop. Input sources typically generate asynchronous events, such as messages arriving on a network port or actions performed by the user.

An input source type normally defines an API for creating and operating on objects of the type, as if it were a separate entity from the run loop, then provides a function to create a CFRunLoopSource for an object. The run loop source can then be registered with the run loop and act as an intermediary between the run loop and the actual input source type object. Examples of input sources include CFMachPort, CFMessagePort, and CFSocket.

There are two categories of sources. Version 0 sources, so named because the version field of their context structure is 0, are managed manually by the application. When a source is ready to fire, some part of the application, perhaps code on a separate thread waiting for an event, must call CFRunLoopSourceSignal to tell the run loop that the source is ready to fire. The run loop source for CFSocket is currently implemented as a version 0 source.

Version 1 sources are managed by the run loop and kernel. These sources use Mach ports to signal when the sources are ready to fire. A source is automatically signaled by the kernel when a message arrives on the source’s Mach port. The contents of the message are given to the source to process when the source is fired. The run loop sources for CFMachPort and CFMessagePort are currently implemented as version 1 sources.

When creating your own custom run loop source, you can choose which version works best for you.

A run loop source can be registered in multiple run loops and run loop modes at the same time. When the source is signaled, whichever run loop that happens to detect the signal first will fire the source. Adding a source to multiple threads’ run loops can be used to manage a pool of “worker” threads that is processing discrete sets of data, such as client-server messages over a network or entries in a job queue filled by a “manager” thread. As messages arrive or jobs get added to the queue, the source gets signaled and a random thread receives and processes the request.

Functions

  • Creates a CFRunLoopSource object.

    Declaration

    Swift

    func CFRunLoopSourceCreate(_ allocator: CFAllocator!, _ order: CFIndex, _ context: UnsafeMutablePointer<CFRunLoopSourceContext>) -> CFRunLoopSource!

    Objective-C

    CFRunLoopSourceRef CFRunLoopSourceCreate ( CFAllocatorRef allocator, CFIndex order, CFRunLoopSourceContext *context );

    Parameters

    allocator

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

    order

    A priority index indicating the order in which run loop sources are processed. When multiple run loop sources are firing in a single pass through the run loop, the sources are processed in increasing order of this parameter. If the run loop is set to process only one source per loop, only the highest priority source, the one with the lowest order value, is processed. This value is ignored for version 1 sources. Pass 0 unless there is a reason to do otherwise.

    context

    A structure holding contextual information for the run loop source. 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.

    Return Value

    The new CFRunLoopSource object. You are responsible for releasing this object.

    Discussion

    The run loop source is not automatically added to a run loop. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the context information for a CFRunLoopSource object.

    Declaration

    Swift

    func CFRunLoopSourceGetContext(_ source: CFRunLoopSource!, _ context: UnsafeMutablePointer<CFRunLoopSourceContext>)

    Objective-C

    void CFRunLoopSourceGetContext ( CFRunLoopSourceRef source, CFRunLoopSourceContext *context );

    Parameters

    source

    The run loop source to examine.

    context

    A pointer to the structure into which the context information for source is to be copied. The information being returned is the same information passed to CFRunLoopSourceCreate when creating source.

    Discussion

    Run loop sources come in two versions with different-sized context structures. context must point to the correct version of the structure for source. Before calling this function, you need to initialize the version member of context with the version number (either 0 or 1) of source.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the ordering parameter for a CFRunLoopSource object.

    Declaration

    Swift

    func CFRunLoopSourceGetOrder(_ source: CFRunLoopSource!) -> CFIndex

    Objective-C

    CFIndex CFRunLoopSourceGetOrder ( CFRunLoopSourceRef source );

    Parameters

    source

    The run loop source to examine.

    Return Value

    The ordering parameter for source, which the run loop uses (for version 0 sources only) to determine the order in which sources are processed when multiple sources are firing.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the type identifier of the CFRunLoopSource opaque type.

    Declaration

    Swift

    func CFRunLoopSourceGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFRunLoopSourceGetTypeID ( void );

    Return Value

    The type identifier for the CFRunLoopSource opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFRunLoopSourceInvalidate(_ source: CFRunLoopSource!)

    Objective-C

    void CFRunLoopSourceInvalidate ( CFRunLoopSourceRef source );

    Parameters

    source

    The run loop source to invalidate.

    Discussion

    Once invalidated, source will never fire and call its perform callback function again. This function automatically removes source from all the run loop modes in which it was registered. If source is a version 0 source, this function calls its cancel callback function as it is removed from each run loop mode. The memory for source is not deallocated unless the run loop held the only reference to source.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFRunLoopSourceIsValid(_ source: CFRunLoopSource!) -> Boolean

    Objective-C

    Boolean CFRunLoopSourceIsValid ( CFRunLoopSourceRef source );

    Parameters

    source

    The run loop source to examine.

    Return Value

    true if source is valid, otherwise false.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Signals a CFRunLoopSource object, marking it as ready to fire.

    Declaration

    Swift

    func CFRunLoopSourceSignal(_ source: CFRunLoopSource!)

    Objective-C

    void CFRunLoopSourceSignal ( CFRunLoopSourceRef source );

    Parameters

    source

    The run loop source to signal.

    Discussion

    This function has no effect on version 1 sources, which are automatically handled when Mach messages arrive for them. After signaling a version 0 source, you need to call CFRunLoopWakeUp on one of the run loops in which the source is registered to get the source handled immediately.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Callbacks

  • Callback invoked when a version 0 CFRunLoopSource object is removed from a run loop mode.

    Declaration

    Objective-C

    typedef void (*CFRunLoopCancelCallBack) ( void *info, CFRunLoopRef rl, CFStringRef mode );

    Parameters

    info

    The info member of the CFRunLoopSourceContext structure that was used when creating the run loop source.

    rl

    The run loop from which the run loop source is being removed.

    mode

    The run loop mode from which the run loop source is being removed.

    Discussion

    You specify this callback in the CFRunLoopSourceContext structure when creating the run loop source.

  • Callback invoked to test two CFRunLoopSource objects for equality.

    Declaration

    Objective-C

    typedef Boolean (*CFRunLoopEqualCallBack) ( const void *info1, const void *info2 );

    Parameters

    info1

    The info member of the CFRunLoopSourceContext or CFRunLoopSourceContext1 structure that was used when creating the first run loop source to test.

    info2

    The info member of the CFRunLoopSourceContext or CFRunLoopSourceContext1 structure that was used when creating the second run loop source to test.

    Return Value

    true if info1 and info2 should be considered equal; otherwise false.

    Discussion

    You specify this callback in the CFRunLoopSourceContext or CFRunLoopSourceContext1 structure when creating the run loop source.

  • Callback invoked to obtain the native Mach port represented by a version 1 CFRunLoopSource object.

    Declaration

    Objective-C

    typedef mach_port_t (*CFRunLoopGetPortCallBack) ( void *info );

    Parameters

    info

    The info member of the CFRunLoopSourceContext1 structure that was used when creating the run loop source.

    Return Value

    The native Mach port for the run loop source.

    Discussion

    This callback is called whenever the run loop needs a source’s Mach port, which can happen in each iteration of the run loop’s loop. Because of the frequency with which the run loop may call this callback, make the function as efficient as possible.

    A version 1 run loop source must have a one-to-one relationship between itself and its Mach port. Each source must have only one Mach port associated with it and each Mach port must represent only one source.

    You specify this callback in the CFRunLoopSourceContext1 structure when creating the run loop source.

  • Callback invoked to compute a hash code for the info pointer of a CFRunLoopSource object.

    Declaration

    Objective-C

    typedef CFHashCode (*CFRunLoopHashCallBack) ( const void *info );

    Parameters

    info

    The info member of the CFRunLoopSourceContext or CFRunLoopSourceContext1 structure that was used when creating the run loop source.

    Return Value

    A hash code value for info.

    Discussion

    If a hash callback is not provided for a source, the info pointer is used.

    You specify this callback in the CFRunLoopSourceContext or CFRunLoopSourceContext1 structure when creating the run loop source.

  • Callback invoked to process and optionally reply to a message received on a version 1 CFRunLoopSource object (Mach port-based sources).

    Declaration

    Objective-C

    typedef void *(*CFRunLoopMachPerformCallBack) ( void *msg, CFIndex size, CFAllocatorRef allocator, void *info );

    Parameters

    msg

    The Mach message received on the Mach port. The pointer is to a mach_msg_header_t structure. A version 0 format trailer (mach_msg_format_0_trailer_t) is at the end of the Mach message.

    size

    Size of the Mach message in msg, excluding the message trailer.

    allocator

    The allocator object that should be used to allocate a reply message.

    info

    The info member of the CFRunLoopSourceContext1 structure that was used when creating the run loop source.

    Return Value

    An optional Mach message to be sent in response to the received message. The message must be allocated using allocator. Return NULL if you want an empty reply returned to the sender.

    Discussion

    You only need to provide this callback if you create your own version 1 run loop source. CFMachPort and CFMessagePort run loop sources already implement this callback to forward the received message to the CFMachPort’s or CFMessagePort’s own callback function, which you do need to implement.

    You specify this callback in the CFRunLoopSourceContext1 structure when creating the run loop source.

  • Callback invoked when a message is received on a version 0 CFRunLoopSource object.

    Declaration

    Objective-C

    typedef void (*CFRunLoopPerformCallBack) ( void *info );

    Parameters

    info

    The info member of the CFRunLoopSourceContext structure that was used when creating the run loop source.

    Discussion

    You only need to provide this callback if you create your own version 0 run loop source. CFSocket run loop sources already implement this callback to forward the received message to the CFSocket’s own callback function, which you do need to implement.

    You specify this callback in the CFRunLoopSourceContext structure when creating the run loop source.

  • Callback invoked when a version 0 CFRunLoopSource object is added to a run loop mode.

    Declaration

    Objective-C

    typedef void (*CFRunLoopScheduleCallBack) ( void *info, CFRunLoopRef rl, CFStringRef mode );

    Parameters

    info

    The info member of the CFRunLoopSourceContext structure that was used when creating the run loop source.

    rl

    The run loop in which the source is being scheduled.

    mode

    The run loop mode in which the source is being scheduled.

    Discussion

    You specify this callback in the CFRunLoopSourceContext structure when creating the run loop source.

Data Types

Miscellaneous

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

    Declaration

    Swift

    struct CFRunLoopSourceContext { 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>!)> var equal: CFunctionPointer<((UnsafePointer<Void>, UnsafePointer<Void>) -> Boolean)> var hash: CFunctionPointer<((UnsafePointer<Void>) -> CFHashCode)> var schedule: CFunctionPointer<((UnsafeMutablePointer<Void>, CFRunLoop!, CFString!) -> Void)> var cancel: CFunctionPointer<((UnsafeMutablePointer<Void>, CFRunLoop!, CFString!) -> Void)> var perform: CFunctionPointer<((UnsafeMutablePointer<Void>) -> Void)> init() init(version version: CFIndex, info info: UnsafeMutablePointer<Void>, retain retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)>, release release: CFunctionPointer<((UnsafePointer<Void>) -> Void)>, copyDescription copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)>, equal equal: CFunctionPointer<((UnsafePointer<Void>, UnsafePointer<Void>) -> Boolean)>, hash hash: CFunctionPointer<((UnsafePointer<Void>) -> CFHashCode)>, schedule schedule: CFunctionPointer<((UnsafeMutablePointer<Void>, CFRunLoop!, CFString!) -> Void)>, cancel cancel: CFunctionPointer<((UnsafeMutablePointer<Void>, CFRunLoop!, CFString!) -> Void)>, perform perform: CFunctionPointer<((UnsafeMutablePointer<Void>) -> Void)>) }

    Objective-C

    struct CFRunLoopSourceContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; CFRunLoopEqualCallBack equal; CFRunLoopHashCallBack hash; CFRunLoopScheduleCallBack schedule; CFRunLoopCancelCallBack cancel; CFRunLoopPerformCallBack perform; }; typedef struct CFRunLoopSourceContext CFRunLoopSourceContext;

    Fields

    version

    Version number of the structure. Must be 0.

    info

    An arbitrary pointer to program-defined data, which can be associated with the CFRunLoopSource 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.

    equal

    An equality test callback for your program-defined info pointer. Can be NULL.

    hash

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

    schedule

    A scheduling callback for the run loop source. This callback is called when the source is added to a run loop mode. Can be NULL.

    cancel

    A cancel callback for the run loop source. This callback is called when the source is removed from a run loop mode. Can be NULL.

    perform

    A perform callback for the run loop source. This callback is called when the source has fired.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    struct CFRunLoopSourceContext1 { 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>!)> var equal: CFunctionPointer<((UnsafePointer<Void>, UnsafePointer<Void>) -> Boolean)> var hash: CFunctionPointer<((UnsafePointer<Void>) -> CFHashCode)> var getPort: CFunctionPointer<((UnsafeMutablePointer<Void>) -> mach_port_t)> var perform: CFunctionPointer<((UnsafeMutablePointer<Void>, CFIndex, CFAllocator!, UnsafeMutablePointer<Void>) -> UnsafeMutablePointer<Void>)> init() init(version version: CFIndex, info info: UnsafeMutablePointer<Void>, retain retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)>, release release: CFunctionPointer<((UnsafePointer<Void>) -> Void)>, copyDescription copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)>, equal equal: CFunctionPointer<((UnsafePointer<Void>, UnsafePointer<Void>) -> Boolean)>, hash hash: CFunctionPointer<((UnsafePointer<Void>) -> CFHashCode)>, getPort getPort: CFunctionPointer<((UnsafeMutablePointer<Void>) -> mach_port_t)>, perform perform: CFunctionPointer<((UnsafeMutablePointer<Void>, CFIndex, CFAllocator!, UnsafeMutablePointer<Void>) -> UnsafeMutablePointer<Void>)>) }

    Objective-C

    struct CFRunLoopSourceContext1 { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; CFRunLoopEqualCallBack equal; CFRunLoopHashCallBack hash; CFRunLoopGetPortCallBack getPort; CFRunLoopMachPerformCallBack perform; }; typedef struct CFRunLoopSourceContext1 CFRunLoopSourceContext1;

    Fields

    version

    Version number of the structure. Must be 1.

    info

    An arbitrary pointer to program-defined data, which can be associated with the run loop source 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.

    equal

    An equality test callback for your program-defined info pointer. Can be NULL.

    hash

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

    getPort

    A callback to retrieve the native Mach port represented by the source. This callback is called when the source is either added to or removed from a run loop mode.

    perform

    A perform callback for the run loop source. This callback is called when the source has fired.

    Availability

    Available in iOS 2.0 and later.

  • A reference to a run loop source object.

    Declaration

    Swift

    typealias CFRunLoopSourceRef = CFRunLoopSource

    Objective-C

    typedef struct __CFRunLoopSource *CFRunLoopSourceRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.