manpagez: man pages & more
man dispatch_queue_create(3)
Home | html | info | man
dispatch_queue_create(3) BSD Library Functions Manual dispatch_queue_create(3)


     dispatch_queue_create, dispatch_queue_get_label,
     dispatch_get_current_queue, dispatch_get_global_queue,
     dispatch_get_main_queue, dispatch_main, dispatch_set_target_queue --
     where blocks are scheduled for execution


     #include <dispatch/dispatch.h>

     dispatch_queue_create(const char *label, dispatch_queue_attr_t attr);

     const char *
     dispatch_queue_get_label(dispatch_queue_t queue);

     dispatch_get_global_queue(long priority, unsigned long flags);



     dispatch_set_target_queue(dispatch_object_t object,
         dispatch_queue_t target);


     Queues are the fundamental mechanism for scheduling blocks for execution
     within the dispatch(3) framework.

     All blocks submitted to dispatch queues are dequeued in FIFO order.
     Queues created with the DISPATCH_QUEUE_SERIAL attribute wait for the pre-
     viously dequeued block to complete before dequeuing the next block. A
     queue with this FIFO completion behavior is usually simply described as a
     serial queue are guaranteed to be visible to subsequent blocks dispatched
     to the same queue. Queues are not bound to any specific thread of execu-
     tion and blocks submitted to independent queues may execute concurrently.

     Queues created with the DISPATCH_QUEUE_CONCURRENT attribute may execute
     dequeued blocks concurrently and support barrier blocks submitted with
     the dispatch barrier API.


     Queues are created with the dispatch_queue_create() function. Queues,
     like all dispatch objects, are reference counted and newly created queues
     have a reference count of one.

     The optional label argument is used to describe the purpose of the queue
     and is useful during debugging and performance analysis. If a label is
     provided, it is copied.  By convention, clients should pass a reverse DNS
     style label. For example:

           my_queue = dispatch_queue_create("com.example.subsystem.taskXYZ", NULL);

     The attr argument specifies the type of queue to create and must be

     The dispatch_queue_get_label() function returns the label provided when
     the given queue was created (or an empty C string if no label was pro-
     vided at creation).  Passing the constant DISPATCH_CURRENT_QUEUE_LABEL to
     dispatch_queue_get_label() returns the label of the current queue.


     Queues may be temporarily suspended and resumed with the functions
     dispatch_suspend() and dispatch_resume() respectively. Suspension is
     checked prior to block execution and is not preemptive.


     The dispatch framework provides a default serial queue for the applica-
     tion to use. This queue is accessed via the dispatch_get_main_queue()

     Programs must call dispatch_main() at the end of main() in order to
     process blocks submitted to the main queue. (See the COMPATIBILITY sec-
     tion for exceptions.) The dispatch_main() function never returns.


     Unlike the main queue or queues allocated with dispatch_queue_create(),
     the global concurrent queues schedule blocks as soon as threads become
     provided, representing the following priority bands:

     The priority of a global concurrent queue controls the scheduling prior-
     ity of the threads created by the system to invoke the blocks submitted
     execution after all global queues with higher priority have been sched-
     uled. Additionally, items on the background priority global queue will
     execute on threads with background state as described in setpriority(2)
     (i.e. disk I/O is throttled and the thread's scheduling priority is set
     to lowest value).

     Use the dispatch_get_global_queue() function to obtain the global queue
     of given priority. The flags argument is reserved for future use and must


     The dispatch_set_target_queue() function updates the target queue of the
     processing the object.

     existing block executions (non-preemptive).

     The default target queue of all dispatch objects created by the applica-
     tion is the default priority global concurrent queue. To reset an
     object's target queue to the default, pass the
     DISPATCH_TARGET_QUEUE_DEFAULT constant to dispatch_set_target_queue().

     order to change the priority of a queue created with
     dispatch_queue_create(), use the dispatch_get_global_queue() function to
     obtain a target queue of the desired priority.

     Blocks submitted to a serial queue whose target queue is another serial
     queue will not be invoked concurrently with blocks submitted to the tar-
     get queue or to any other queue with that same target queue.

     The target queue of a dispatch source specifies where its event handler
     and cancellation handler blocks will be submitted. See
     dispatch_source_create(3) for more information about dispatch sources.

     global queue where its I/O operations are executed. See
     dispatch_io_create(3) for more information about dispatch I/O channels.

     queue is to determine where an object's finalizer function is invoked.

     first argument of dispatch_set_target_queue() is undefined.

     Directly or indirectly setting the target queue of a dispatch queue to
     itself is undefined.


     The following functions are deprecated and will be removed in a future

     dispatch_queue_t dispatch_get_current_queue(void);

     dispatch_get_current_queue() always returns a valid queue. When called
     returned. If this function is called from the main thread before
     dispatch_main() is called, then the result of dispatch_get_main_queue()

     The use of dispatch_get_current_queue() is strongly discouraged except
     for debugging and logging purposes. Code must not make any assumptions
     policies that may surprise code that tries to schedule work with the
     or filesystem configuration. This function is deprecated and will be
     removed in a future release.


     The result of dispatch_get_main_queue() may or may not equal the result
     of dispatch_get_current_queue() when called on the main thread. Comparing
     POSIX programs may use pthread_main_np(3).

     dispatch_get_current_queue() may return a queue owned by a different sub-
     system which has already had all external references to it released.
     While such a queue will continue to exist until all blocks submitted to
     it have completed, attempting to retain it is forbidden and will trigger
     an assertion. If Objective-C Automatic Reference Counting is enabled, any
     use of the object returned by dispatch_get_current_queue() will cause
     retain calls to be automatically generated, so the use of
     dispatch_get_current_queue() for any reason in code built with ARC is
     particularly strongly discouraged.


     Cocoa applications need not call dispatch_main().  Blocks submitted to
     application's main NSRunLoop or CFRunLoop.  However, blocks submitted to
     the main queue in applications using dispatch_main() are not guaranteed
     to execute on the main thread.

     catch exceptions generated by higher level languages such as Objective-C
     or C++.  Applications MUST catch all exceptions before returning from a
     block submitted to a dispatch queue; otherwise the process will be termi-
     nated with an uncaught exception.

     The dispatch framework manages the relationship between dispatch queues
     and threads of execution. As a result, applications MUST NOT delete or
     mutate objects that they did not create. The following interfaces MUST
     NOT be called by blocks submitted to a dispatch queue:

           o   pthread_cancel()

           o   pthread_detach()

           o   pthread_join()

           o   pthread_kill()

           o   pthread_exit()

     Applications MAY call the following interfaces from a block submitted to
     state before returning:

           o   pthread_setcancelstate()

           o   pthread_setcanceltype()

           o   pthread_setschedparam()

           o   pthread_sigmask()

           o   pthread_setugid_np()

           o   pthread_chdir()

           o   pthread_fchdir()

     Applications MUST NOT rely on the following interfaces returning pre-
     dictable results between invocations of blocks submitted to a dispatch

           o   pthread_self()

           o   pthread_getschedparam()

           o   pthread_get_stacksize_np()

           o   pthread_get_stackaddr_np()

           o   pthread_mach_thread_np()

           o   pthread_from_mach_thread_np()

     While the result of pthread_self() may change between invocations of
     block. Because the underlying thread may change beteween block invoca-
     pthread_setspecific() and pthread_getspecific() is well defined within a
     assumptions about when the destructor passed to pthread_key_create() is

     The following example code correctly handles per-thread return values:

           __block int r;
           __block int e;
           dispatch_sync(queue, ^{
                   r = kill(1, 0);
                   e = errno;
           printf("kill(1,0) returned %d and errno %d0, r, e);

     Note that in the above example errno is a per-thread variable and must be
     need to be copied is the use of getpwnam() instead of getpwnam_r().

     As an optimization, dispatch_sync() invokes the block on the current


     dispatch(3), dispatch_async(3), dispatch_object(3),

Darwin                            May 1, 2008                           Darwin

Mac OS X 10.9.1 - Generated Tue Jan 7 18:19:39 CST 2014
© 2000-2021
Individual documents may contain additional copyright information.