afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
191 lines
6.1 KiB
Groff
191 lines
6.1 KiB
Groff
.\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
|
|
.Dd March 1, 2012
|
|
.Dt dispatch_object 3
|
|
.Os Darwin
|
|
.Sh NAME
|
|
.Nm dispatch_object
|
|
.Nd General manipulation of dispatch objects
|
|
.Sh SYNOPSIS
|
|
.Fd #include <dispatch/dispatch.h>
|
|
.Ft void
|
|
.Fo dispatch_retain
|
|
.Fa "dispatch_object_t object"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_release
|
|
.Fa "dispatch_object_t object"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_suspend
|
|
.Fa "dispatch_object_t object"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_resume
|
|
.Fa "dispatch_object_t object"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_activate
|
|
.Fa "dispatch_object_t object"
|
|
.Fc
|
|
.Ft "void *"
|
|
.Fo dispatch_get_context
|
|
.Fa "dispatch_object_t object"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_set_context
|
|
.Fa "dispatch_object_t object"
|
|
.Fa "void *context"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_set_finalizer_f
|
|
.Fa "dispatch_object_t object"
|
|
.Fa "dispatch_function_t finalizer"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
Dispatch objects share functions for coordinating memory management, suspension,
|
|
cancellation and context pointers.
|
|
.Sh MEMORY MANAGEMENT
|
|
Objects returned by creation functions in the dispatch framework may be
|
|
uniformly retained and released with the functions
|
|
.Fn dispatch_retain
|
|
and
|
|
.Fn dispatch_release
|
|
respectively.
|
|
.Pp
|
|
The dispatch framework does not guarantee that any given client has the last or
|
|
only reference to a given object. Objects may be retained internally by the
|
|
system.
|
|
.Ss INTEGRATION WITH OBJECTIVE-C
|
|
.Bd -filled -offset indent
|
|
When building with an Objective-C or Objective-C++ compiler, dispatch objects
|
|
are declared as Objective-C types. This results in the following differences
|
|
compared to building as plain C/C++:
|
|
.Bl -dash
|
|
.It
|
|
if Objective-C Automated Reference Counting is enabled, dispatch objects are
|
|
memory managed by the Objective-C runtime and explicit calls to the
|
|
.Fn dispatch_retain
|
|
and
|
|
.Fn dispatch_release
|
|
functions will produce build errors.
|
|
.Pp
|
|
.Em Note :
|
|
when ARC is enabled, care needs to be taken with dispatch API returning an
|
|
interior pointer that is only valid as long as an associated object has not
|
|
been released. If that object is held in a variable with automatic storage, it
|
|
may need to be annotated with the
|
|
.Li objc_precise_lifetime
|
|
attribute, or stored in a
|
|
.Li __strong
|
|
instance variable instead, to ensure that the object is not prematurely
|
|
released. The functions returning interior pointers are
|
|
.Xr dispatch_data_create_map 3
|
|
and
|
|
.Xr dispatch_data_apply 3 .
|
|
.It
|
|
the Blocks runtime automatically retains and releases dispatch objects captured
|
|
by blocks upon
|
|
.Fn Block_copy
|
|
and
|
|
.Fn Block_release ,
|
|
e.g.\& as performed during asynchronous execution of a block via
|
|
.Xr dispatch_async 3 .
|
|
.Pp
|
|
.Em Note :
|
|
retain cycles may be encountered if dispatch source objects are captured by
|
|
their handler blocks; these cycles can be broken by declaring the captured
|
|
object
|
|
.Li __weak
|
|
or by calling
|
|
.Xr dispatch_source_cancel 3
|
|
to cause its handler blocks to be released explicitly.
|
|
.It
|
|
dispatch objects can be added directly to Cocoa collections, and their
|
|
lifetime is tracked by the Objective-C static analyzer.
|
|
.El
|
|
.Pp
|
|
Integration of dispatch objects with Objective-C requires targeting Mac\ OS\ X
|
|
10.8 or later, and is disabled when building for the legacy Objective-C runtime.
|
|
It can also be disabled manually by using compiler options to define the
|
|
.Dv OS_OBJECT_USE_OBJC
|
|
preprocessor macro to
|
|
.Li 0 .
|
|
.Ed
|
|
.Pp
|
|
.Em Important :
|
|
When building with a plain C/C++ compiler or when integration with Objective-C
|
|
is disabled, dispatch objects are
|
|
.Em not
|
|
automatically retained and released when captured by a block. Therefore, when a
|
|
dispatch object is captured by a block that will be executed asynchronously,
|
|
the object must be manually retained and released:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
dispatch_retain(object);
|
|
dispatch_async(queue, ^{
|
|
do_something_with_object(object);
|
|
dispatch_release(object);
|
|
});
|
|
.Ed
|
|
.Sh ACTIVATION
|
|
Dispatch objects such as queues and sources may be created in an inactive
|
|
state. Objects in this state must be activated before any blocks
|
|
associated with them will be invoked. Calling
|
|
.Fn dispatch_activate
|
|
on an active object has no effect.
|
|
.Pp
|
|
Changing attributes such as the target queue or a source handler is no longer permitted
|
|
once the object has been activated (see
|
|
.Xr dispatch_set_target_queue 3 ,
|
|
.Xr dispatch_source_set_event_handler 3 ).
|
|
.Sh SUSPENSION
|
|
The invocation of blocks on dispatch queues or dispatch sources may be suspended
|
|
or resumed with the functions
|
|
.Fn dispatch_suspend
|
|
and
|
|
.Fn dispatch_resume
|
|
respectively. Other dispatch objects do not support suspension.
|
|
.Pp
|
|
The dispatch framework always checks the suspension status before executing a
|
|
block, but such changes never affect a block during execution (non-preemptive).
|
|
Therefore the suspension of an object is asynchronous, unless it is performed
|
|
from the context of the target queue for the given object.
|
|
The result of suspending or resuming an object that is not a dispatch queue or
|
|
a dispatch source is undefined.
|
|
.Pp
|
|
.Em Important :
|
|
suspension applies to all aspects of the dispatch object life cycle, including
|
|
the finalizer function and cancellation handler. Suspending an object causes it
|
|
to be retained and resuming an object causes it to be released. Therefore it is
|
|
important to balance calls to
|
|
.Fn dispatch_suspend
|
|
and
|
|
.Fn dispatch_resume
|
|
such that the dispatch object is fully resumed when the last reference is
|
|
released. The result of releasing all references to a dispatch object while in
|
|
an inactive or suspended state is undefined.
|
|
.Sh CONTEXT POINTERS
|
|
Dispatch objects support supplemental context pointers. The value of the
|
|
context pointer may be retrieved and updated with
|
|
.Fn dispatch_get_context
|
|
and
|
|
.Fn dispatch_set_context
|
|
respectively.
|
|
The
|
|
.Fn dispatch_set_finalizer_f
|
|
specifies an optional per-object finalizer function that is invoked
|
|
asynchronously if the context pointer is not NULL when the last
|
|
reference to the object is released.
|
|
This gives the
|
|
application an opportunity to free the context data associated with the object.
|
|
The finalizer will be run on the object's target queue.
|
|
.Sh SEE ALSO
|
|
.Xr dispatch 3 ,
|
|
.Xr dispatch_async 3 ,
|
|
.Xr dispatch_group_create 3 ,
|
|
.Xr dispatch_queue_create 3 ,
|
|
.Xr dispatch_semaphore_create 3 ,
|
|
.Xr dispatch_set_target_queue 3 ,
|
|
.Xr dispatch_source_cancel 3 ,
|
|
.Xr dispatch_source_create 3
|