Next Page >

Hide TOC

CFRunLoopSource Reference

Derived from	CFType
Framework	CoreFoundation/CoreFoundation.h
Companion guide	Run Loops
Declared in	CFRunLoop.h

Overview

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

CFRunLoopSourceCreate

Creates a CFRunLoopSource object.

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.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

CFRunLoop.h

CFRunLoopSourceGetContext

Returns the context information for a CFRunLoopSource object.

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CFRunLoop.h

CFRunLoopSourceGetOrder

Returns the ordering parameter for a CFRunLoopSource object.

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CFRunLoop.h

CFRunLoopSourceGetTypeID

Returns the type identifier of the CFRunLoopSource opaque type.

CFTypeID CFRunLoopSourceGetTypeID (
   void
);

Return Value

The type identifier for the CFRunLoopSource opaque type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CFRunLoop.h

CFRunLoopSourceInvalidate

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

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.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

CFRunLoop.h

CFRunLoopSourceIsValid

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

Boolean CFRunLoopSourceIsValid (
   CFRunLoopSourceRef source
);

Parameters

source: The run loop source to examine.

Return Value

true if source is valid, otherwise false.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CFRunLoop.h

CFRunLoopSourceSignal

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

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.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

SimpleAudioExtraction

Declared In

CFRunLoop.h

Callbacks

CFRunLoopCancelCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   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.

CFRunLoopEqualCallBack

Callback invoked to test two CFRunLoopSource objects for equality.

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

If you name your function MyCallBack, you would declare it like this:

Boolean MyCallBack (
   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.

CFRunLoopGetPortCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

mach_port_t MyCallBack (
   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.

CFRunLoopHashCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

CFHashCode MyCallBack (
   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.

CFRunLoopMachPerformCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

void *MyCallBack (
   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.

CFRunLoopPerformCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   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.

CFRunLoopScheduleCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   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

CFRunLoopSourceContext

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

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 Mac OS X v10.0 and later.

Declared In

CFRunLoop.h

CFRunLoopSourceContext1

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

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 Mac OS X v10.0 and later.

Declared In

CFRunLoop.h