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@
  *
@@ -272,7 +272,7 @@ dispatch_sync_f(dispatch_queue_t queue,
  */
 #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));
@@ -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)
-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,
@@ -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().
  *
+ * 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.
  */
-__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);
@@ -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;
-#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
@@ -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.
  */
-#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;
@@ -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)
-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);
 
+/*!
+ * @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
- * 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
- * The result of passing NULL in this parameter is undefined.
+ * The queue to query, or DISPATCH_CURRENT_QUEUE_LABEL.
  *
  * @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)
-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);
 
@@ -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
- * 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.