libdispatch-339.92.1.tar.gz

[apple/libdispatch.git] / dispatch / queue.h

diff --git a/dispatch/queue.h b/dispatch/queue.h
index d7677713690a84ccdd93d6a7cfd3e625b7a3268a..9090676d8338ca65833bfb1799e7fe36d03a05cc 100644 (file)
--- a/dispatch/queue.h
+++ b/dispatch/queue.h
@@ -1,5 +1,5 @@
 /*
 /*

- * Copyright (c) 2008-2011 Apple Inc. All rights reserved.
+ * Copyright (c) 2008-2012 Apple Inc. All rights reserved.

  *
  * @APPLE_APACHE_LICENSE_HEADER_START@
  *
  *
  * @APPLE_APACHE_LICENSE_HEADER_START@
  *


@@ -272,7 +272,7 @@ dispatch_sync_f(dispatch_queue_t queue,
  */
 #ifdef __BLOCKS__
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  */
 #ifdef __BLOCKS__
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)

-DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NOTHROW

 void
 dispatch_apply(size_t iterations, dispatch_queue_t queue,
                void (^block)(size_t));
 void
 dispatch_apply(size_t iterations, dispatch_queue_t queue,
                void (^block)(size_t));


@@ -305,7 +305,7 @@ dispatch_apply(size_t iterations, dispatch_queue_t queue,
  * The result of passing NULL in this parameter is undefined.
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  * The result of passing NULL in this parameter is undefined.
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)

-DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
+DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_NOTHROW

 void
 dispatch_apply_f(size_t iterations, dispatch_queue_t queue,
        void *context,
 void
 dispatch_apply_f(size_t iterations, dispatch_queue_t queue,
        void *context,


@@ -330,10 +330,17 @@ dispatch_apply_f(size_t iterations, dispatch_queue_t queue,
  * from deadlock if that queue is not the one returned by
  * dispatch_get_current_queue().
  *
  * from deadlock if that queue is not the one returned by
  * dispatch_get_current_queue().
  *

+ * When dispatch_get_current_queue() is called on the main thread, it may
+ * or may not return the same value as dispatch_get_main_queue(). Comparing
+ * the two is not a valid way to test whether code is executing on the
+ * main thread.
+ *
+ * This function is deprecated and will be removed in a future release.
+ *

  * @result
  * Returns the current queue.
  */
  * @result
  * Returns the current queue.
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6,__MAC_10_9,__IPHONE_4_0,__IPHONE_6_0)

 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 dispatch_queue_t
 dispatch_get_current_queue(void);
 DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 dispatch_queue_t
 dispatch_get_current_queue(void);


@@ -355,7 +362,8 @@ dispatch_get_current_queue(void);
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 DISPATCH_EXPORT struct dispatch_queue_s _dispatch_main_q;
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 DISPATCH_EXPORT struct dispatch_queue_s _dispatch_main_q;

-#define dispatch_get_main_queue() (&_dispatch_main_q)
+#define dispatch_get_main_queue() \
+               DISPATCH_GLOBAL_OBJECT(dispatch_queue_t, _dispatch_main_q)

 
 /*!
  * @typedef dispatch_queue_priority_t
 
 /*!
  * @typedef dispatch_queue_priority_t


@@ -430,7 +438,9 @@ dispatch_get_global_queue(dispatch_queue_priority_t priority,
  * @discussion A dispatch queue that may invoke blocks concurrently and supports
  * barrier blocks submitted with the dispatch barrier API.
  */
  * @discussion A dispatch queue that may invoke blocks concurrently and supports
  * barrier blocks submitted with the dispatch barrier API.
  */

-#define DISPATCH_QUEUE_CONCURRENT (&_dispatch_queue_attr_concurrent)
+#define DISPATCH_QUEUE_CONCURRENT \
+               DISPATCH_GLOBAL_OBJECT(dispatch_queue_attr_t, \
+               _dispatch_queue_attr_concurrent)

 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
 DISPATCH_EXPORT
 struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent;
 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
 DISPATCH_EXPORT
 struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent;


@@ -470,26 +480,36 @@ struct dispatch_queue_attr_s _dispatch_queue_attr_concurrent;
  * The newly created dispatch queue.
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  * The newly created dispatch queue.
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)

-DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
+DISPATCH_NOTHROW

 dispatch_queue_t
 dispatch_queue_create(const char *label, dispatch_queue_attr_t attr);
 
 dispatch_queue_t
 dispatch_queue_create(const char *label, dispatch_queue_attr_t attr);
 

+/*!
+ * @const DISPATCH_CURRENT_QUEUE_LABEL
+ * @discussion Constant to pass to the dispatch_queue_get_label() function to
+ * retrieve the label of the current queue.
+ */
+#define DISPATCH_CURRENT_QUEUE_LABEL NULL
+

 /*!
  * @function dispatch_queue_get_label
  *
  * @abstract
 /*!
  * @function dispatch_queue_get_label
  *
  * @abstract

- * Returns the label of the queue that was specified when the
- * queue was created.
+ * Returns the label of the given queue, as specified when the queue was
+ * created, or the empty string if a NULL label was specified.
+ *
+ * Passing DISPATCH_CURRENT_QUEUE_LABEL will return the label of the current
+ * queue.

  *
  * @param queue
  *
  * @param queue

- * The result of passing NULL in this parameter is undefined.
+ * The queue to query, or DISPATCH_CURRENT_QUEUE_LABEL.

  *
  * @result
  *
  * @result

- * The label of the queue. The result may be NULL.
+ * The label of the queue.

  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  */
 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)

-DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT
-DISPATCH_NOTHROW
+DISPATCH_EXPORT DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW

 const char *
 dispatch_queue_get_label(dispatch_queue_t queue);
 
 const char *
 dispatch_queue_get_label(dispatch_queue_t queue);
 


@@ -525,7 +545,10 @@ dispatch_queue_get_label(dispatch_queue_t queue);
  * cancellation handler blocks will be submitted.
  *
  * A dispatch I/O channel's target queue specifies where where its I/O
  * cancellation handler blocks will be submitted.
  *
  * A dispatch I/O channel's target queue specifies where where its I/O

- * operations are executed.
+ * operations are executed. If the channel's target queue's priority is set to
+ * DISPATCH_QUEUE_PRIORITY_BACKGROUND, then the I/O operations performed by
+ * dispatch_io_read() or dispatch_io_write() on that queue will be
+ * throttled when there is I/O contention.

  *
  * For all other dispatch object types, the only function of the target queue
  * is to determine where an object's finalizer function is invoked.
  *
  * For all other dispatch object types, the only function of the target queue
  * is to determine where an object's finalizer function is invoked.