Mac Developer Library

Developer

thread_call.h Reference

Options
Deployment Target:

On This Page

thread_call.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Facilities for executing work asynchronously.

Included Headers

  • <mach/mach_types.h>

  • <kern/clock.h>

  • <sys/cdefs.h>

Functions

  • Allocate a thread call to execute with default (high) priority.

    Declaration

    Objective-C

    thread_call_t thread_call_allocate ( thread_call_func_t func, thread_call_param_t param0 );

    Parameters

    func

    Callback to invoke when thread call is scheduled.

    param0

    First argument ot pass to callback.

    Return Value

    Thread call which can be passed to thread_call_enter variants.

    Discussion

    Allocates a thread call that will run with properties of THREAD_CALL_PRIORITY_HIGH, binding the first parameter to the callback.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Allocate a thread call to execute with a specified priority.

    Declaration

    Objective-C

    thread_call_t thread_call_allocate_with_priority ( thread_call_func_t func, thread_call_param_t param0, thread_call_priority_t pri );

    Parameters

    func

    Callback to invoke when thread call is scheduled.

    param0

    First argument to pass to callback.

    pri

    Priority of item.

    Return Value

    Thread call which can be passed to thread_call_enter variants.

    Discussion

    Identical to thread_call_allocate, except that priority is specified by caller.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.8 and later.

  • Attempt to cancel a pending invocation of a thread call.

    Declaration

    Objective-C

    boolean_t thread_call_cancel ( thread_call_t call );

    Return Value

    TRUE if the call was successfully cancelled, FALSE otherwise.

    Discussion

    Attempt to cancel a thread call which has been scheduled for execution with a thread_call_enter* variant. If the call has not yet begun executing, the pending invocation will be cancelled and TRUE will be returned. If the work item has already begun executing, thread_call_cancel will return FALSE immediately; the callback may be about to run, currently running, or already done executing.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Attempt to cancel a pending invocation of a thread call. If unable to cancel, wait for current invocation to finish.

    Declaration

    Objective-C

    boolean_t thread_call_cancel_wait ( thread_call_t call );

    Return Value

    TRUE if the call was successfully cancelled, FALSE otherwise.

    Discussion

    Attempt to cancel a thread call which has been scheduled for execution with a thread_call_enter* variant. If the call has not yet begun executing, the pending invocation will be cancelled and TRUE will be returned. If the work item has already begun executing, thread_call_cancel_wait waits for the most recent invocation to finish. When called on a work item which has already finished, it will return FALSE immediately. Note that this routine can only be used on thread calls set up with either thread_call_allocate or thread_call_allocate_with_priority, and that invocations of the thread call after the current invocation may be in flight when thread_call_cancel_wait returns.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.8 and later.

  • Submit a thread call work item for immediate execution.

    Declaration

    Objective-C

    boolean_t thread_call_enter ( thread_call_t call );

    Parameters

    call

    The thread call to execute.

    Return Value

    TRUE if the call was already pending for either delayed or immediate execution, FALSE otherwise.

    Discussion

    If the work item is already scheduled for delayed execution, and it has not yet begun to run, that delayed invocation will be cancelled. Note that if a thread call is rescheduled from its own callback, then multiple invocations of the callback may be in flight at the same time.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Submit a thread call work item for immediate execution, with an extra parameter.

    Declaration

    Objective-C

    boolean_t thread_call_enter1 ( thread_call_t call, thread_call_param_t param1 );

    Parameters

    call

    The thread call to execute.

    param1

    Parameter to pass callback.

    Return Value

    TRUE if the call was already pending for either delayed or immediate execution, FALSE otherwise.

    Discussion

    This routine is identical to thread_call_enter(), except that the second parameter to the callback is specified.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Submit a thread call to be executed at some point in the future, with an extra parameter.

    Declaration

    Objective-C

    boolean_t thread_call_enter1_delayed ( thread_call_t call, thread_call_param_t param1, uint64_t deadline );

    Parameters

    call

    The thread call to execute.

    param1

    Second parameter to callback.

    deadline

    Time, in absolute time units, at which to execute callback.

    Return Value

    TRUE if the call was already pending for either delayed or immediate execution, FALSE otherwise.

    Discussion

    This routine is identical to thread_call_enter_delayed(), except that a second parameter to the callback is specified.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Submit a thread call to be executed at some point in the future.

    Declaration

    Objective-C

    boolean_t thread_call_enter_delayed ( thread_call_t call, uint64_t deadline );

    Parameters

    call

    The thread call to execute.

    deadline

    Time, in absolute time units, at which to execute callback.

    Return Value

    TRUE if the call was already pending for either delayed or immediate execution, FALSE otherwise.

    Discussion

    If the work item is already scheduled for delayed or immediate execution, and it has not yet begun to run, that invocation will be cancelled in favor of execution at the newly specified time. Note that if a thread call is rescheduled from its own callback, then multiple invocations of the callback may be in flight at the same time.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Release a thread call.

    Declaration

    Objective-C

    boolean_t thread_call_free ( thread_call_t call );

    Parameters

    call

    The thread call to release.

    Return Value

    TRUE if the thread call has been successfully released, else FALSE.

    Discussion

    Should only be used on thread calls allocated with thread_call_allocate or thread_call_allocate_with_priority. Once thread_call_free has been called, no other operations may be performed on a thread call. If the thread call is currently pending, thread_call_free will return FALSE and will have no effect. Calling thread_call_free from a thread call's own callback is safe; the work item is not considering "pending" at that point.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.0 and later.

  • Determine whether a thread call is pending or currently executing.

    Declaration

    Objective-C

    boolean_t thread_call_isactive ( thread_call_t call );

    Parameters

    call

    Thread call to examine.

    Return Value

    TRUE if the thread call is either scheduled for execution (immediately or at some point in the future) or is currently executing.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.8 and later.

Data Types

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    typedef enum { THREAD_CALL_PRIORITY_HIGH = 0, THREAD_CALL_PRIORITY_KERNEL = 1, THREAD_CALL_PRIORITY_USER = 2, THREAD_CALL_PRIORITY_LOW = 3 } thread_call_priority_t;

    Constants

    • THREAD_CALL_PRIORITY_HIGH

      THREAD_CALL_PRIORITY_HIGH

      Importance above everything but realtime. Thread calls allocated with this priority execute at extremely high priority, above everything but realtime threads. They are generally executed in serial. Though they may execute concurrently under some circumstances, no fan-out is implied. These work items should do very small amounts of work or risk disrupting system responsiveness.

      Available in OS X v10.8 and later.

    • THREAD_CALL_PRIORITY_KERNEL

      THREAD_CALL_PRIORITY_KERNEL

      Importance similar to that of normal kernel threads.

      Available in OS X v10.8 and later.

    • THREAD_CALL_PRIORITY_USER

      THREAD_CALL_PRIORITY_USER

      Importance similar to that of normal user threads.

      Available in OS X v10.8 and later.

    • THREAD_CALL_PRIORITY_LOW

      THREAD_CALL_PRIORITY_LOW

      Very low importance.

      Available in OS X v10.8 and later.

    Discussion

    Thread call priorities should not be assumed to have any specific numerical value; they should be interpreted as importances or roles for work items, priorities for which will be reasonably managed by the subsystem.

    Import Statement

    Objective-C

    #include <thread_call.h>;

    Availability

    Available in OS X v10.8 and later.