thread_call.h Reference

Declared in
thread_call.h

Overview

Facilities for executing work asynchronously.

Included Headers

  • <mach/mach_types.h>

  • <kern/clock.h>

  • <sys/cdefs.h>

Functions

See the Overview section above for header-level documentation.

thread_call_allocate

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_allocate_with_priority

Allocate a thread call to execute with a specified priority.

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

Availability
  • Available in OS X v10.8 and later.
Declared In
thread_call.h

thread_call_cancel

Attempt to cancel a pending invocation of a thread call.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_cancel_wait

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
thread_call.h

thread_call_enter

Submit a thread call work item for immediate execution.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_enter1

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_enter1_delayed

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_enter_delayed

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_free

Release a thread call.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
thread_call.h

thread_call_isactive

Determine whether a thread call is pending or currently executing.

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
thread_call.h

Data Types

See the Overview section above for header-level documentation.

thread_call_priority_t

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

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.

Declared in thread_call.h.

THREAD_CALL_PRIORITY_KERNEL

Importance similar to that of normal kernel threads.

Available in OS X v10.8 and later.

Declared in thread_call.h.

THREAD_CALL_PRIORITY_USER

Importance similar to that of normal user threads.

Available in OS X v10.8 and later.

Declared in thread_call.h.

THREAD_CALL_PRIORITY_LOW

Very low importance.

Available in OS X v10.8 and later.

Declared in thread_call.h.

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
thread_call.h