[libdispatch-changes] [36] trunk
source_changes at macosforge.org
source_changes at macosforge.org
Wed Sep 16 03:23:37 PDT 2009
Revision: 36
http://trac.macosforge.org/projects/libdispatch/changeset/36
Author: robert at fledge.watson.org
Date: 2009-09-16 03:23:34 -0700 (Wed, 16 Sep 2009)
Log Message:
-----------
Move public headers from src/ to dispatch/, update makefiles. This
eliminates the need for include order hacks with automake, as there's
no longer a clash between the global POSIX semaphore.h and the
libdispatch semaphore.h.
The xcode build parts will need updating for this change.
Discussed with: Kevin Van Vechten
Modified Paths:
--------------
trunk/Makefile.am
trunk/configure.ac
trunk/src/Makefile.am
trunk/src/internal.h
Added Paths:
-----------
trunk/dispatch/
trunk/dispatch/base.h
trunk/dispatch/benchmark.h
trunk/dispatch/dispatch.h
trunk/dispatch/group.h
trunk/dispatch/object.h
trunk/dispatch/once.h
trunk/dispatch/queue.h
trunk/dispatch/semaphore.h
trunk/dispatch/source.h
trunk/dispatch/time.h
Removed Paths:
-------------
trunk/src/base.h
trunk/src/benchmark.h
trunk/src/dispatch.h
trunk/src/group.h
trunk/src/object.h
trunk/src/once.h
trunk/src/queue.h
trunk/src/semaphore.h
trunk/src/source.h
trunk/src/time.h
Modified: trunk/Makefile.am
===================================================================
--- trunk/Makefile.am 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/Makefile.am 2009-09-16 10:23:34 UTC (rev 36)
@@ -2,5 +2,6 @@
#
#
-SUBDIRS= \
+SUBDIRS= \
+ dispatch \
src
Modified: trunk/configure.ac
===================================================================
--- trunk/configure.ac 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/configure.ac 2009-09-16 10:23:34 UTC (rev 36)
@@ -164,5 +164,5 @@
#
# Generate Makefiles.
#
-AC_CONFIG_FILES([Makefile src/Makefile])
+AC_CONFIG_FILES([Makefile dispatch/Makefile src/Makefile])
AC_OUTPUT
Copied: trunk/dispatch/base.h (from rev 35, trunk/src/base.h)
===================================================================
--- trunk/dispatch/base.h (rev 0)
+++ trunk/dispatch/base.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_BASE__
+#define __DISPATCH_BASE__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#endif
+
+#ifdef __cplusplus
+/*
+ * Dispatch objects are NOT C++ objects. Nevertheless, we can at least keep C++
+ * aware of type compatibility.
+ */
+typedef struct dispatch_object_s {
+private:
+ dispatch_object_s();
+ ~dispatch_object_s();
+ dispatch_object_s(const dispatch_object_s &);
+ void operator=(const dispatch_object_s &);
+} *dispatch_object_t;
+#else
+typedef union {
+ struct dispatch_object_s *_do;
+ struct dispatch_continuation_s *_dc;
+ struct dispatch_queue_s *_dq;
+ struct dispatch_queue_attr_s *_dqa;
+ struct dispatch_group_s *_dg;
+ struct dispatch_source_s *_ds;
+ struct dispatch_source_attr_s *_dsa;
+ struct dispatch_semaphore_s *_dsema;
+} dispatch_object_t __attribute__((transparent_union));
+#endif
+
+typedef void (*dispatch_function_t)(void *);
+
+#ifdef __cplusplus
+#define DISPATCH_DECL(name) typedef struct name##_s : public dispatch_object_s {} *name##_t;
+#else
+/*! @parseOnly */
+#define DISPATCH_DECL(name) typedef struct name##_s *name##_t;
+#endif
+
+#ifdef __GNUC__
+#define DISPATCH_NORETURN __attribute__((__noreturn__))
+#define DISPATCH_NOTHROW __attribute__((__nothrow__))
+#define DISPATCH_NONNULL1 __attribute__((__nonnull__(1)))
+#define DISPATCH_NONNULL2 __attribute__((__nonnull__(2)))
+#define DISPATCH_NONNULL3 __attribute__((__nonnull__(3)))
+#define DISPATCH_NONNULL4 __attribute__((__nonnull__(4)))
+#define DISPATCH_NONNULL5 __attribute__((__nonnull__(5)))
+#define DISPATCH_NONNULL6 __attribute__((__nonnull__(6)))
+#define DISPATCH_NONNULL7 __attribute__((__nonnull__(7)))
+#if __clang__
+// rdar://problem/6857843
+#define DISPATCH_NONNULL_ALL
+#else
+#define DISPATCH_NONNULL_ALL __attribute__((__nonnull__))
+#endif
+#define DISPATCH_SENTINEL __attribute__((__sentinel__))
+#define DISPATCH_PURE __attribute__((__pure__))
+#define DISPATCH_WARN_RESULT __attribute__((__warn_unused_result__))
+#define DISPATCH_MALLOC __attribute__((__malloc__))
+#else
+/*! @parseOnly */
+#define DISPATCH_NORETURN
+/*! @parseOnly */
+#define DISPATCH_NOTHROW
+/*! @parseOnly */
+#define DISPATCH_NONNULL1
+/*! @parseOnly */
+#define DISPATCH_NONNULL2
+/*! @parseOnly */
+#define DISPATCH_NONNULL3
+/*! @parseOnly */
+#define DISPATCH_NONNULL4
+/*! @parseOnly */
+#define DISPATCH_NONNULL5
+/*! @parseOnly */
+#define DISPATCH_NONNULL6
+/*! @parseOnly */
+#define DISPATCH_NONNULL7
+/*! @parseOnly */
+#define DISPATCH_NONNULL_ALL
+/*! @parseOnly */
+#define DISPATCH_SENTINEL
+/*! @parseOnly */
+#define DISPATCH_PURE
+/*! @parseOnly */
+#define DISPATCH_WARN_RESULT
+/*! @parseOnly */
+#define DISPATCH_MALLOC
+#endif
+
+#endif
Copied: trunk/dispatch/benchmark.h (from rev 35, trunk/src/benchmark.h)
===================================================================
--- trunk/dispatch/benchmark.h (rev 0)
+++ trunk/dispatch/benchmark.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+/*
+ * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
+ * which are subject to change in future releases of Mac OS X. Any applications
+ * relying on these interfaces WILL break.
+ */
+
+#ifndef __DISPATCH_BENCHMARK__
+#define __DISPATCH_BENCHMARK__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+__BEGIN_DECLS
+
+/*!
+ * @function dispatch_benchmark
+ *
+ * @abstract
+ * Count the average number of cycles a given block takes to execute.
+ *
+ * @param count
+ * The number of times to serially execute the given block.
+ *
+ * @param block
+ * The block to execute.
+ *
+ * @result
+ * The approximate number of cycles the block takes to execute.
+ *
+ * @discussion
+ * This function is for debugging and performance analysis work. For the best
+ * results, pass a high count value to dispatch_benchmark(). When benchmarking
+ * concurrent code, please compare the serial version of the code against the
+ * concurrent version, and compare the concurrent version on different classes
+ * of hardware. Please look for inflection points with various data sets and
+ * keep the following facts in mind:
+ *
+ * 1) Code bound by computational bandwidth may be inferred by proportional
+ * changes in performance as concurrency is increased.
+ * 2) Code bound by memory bandwidth may be inferred by negligible changes in
+ * performance as concurrency is increased.
+ * 3) Code bound by critical sections may be inferred by retrograde changes in
+ * performance as concurrency is increased.
+ * 3a) Intentional: locks, mutexes, and condition variables.
+ * 3b) Accidental: unrelated and frequently modified data on the same cache-line.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL2 DISPATCH_NOTHROW
+uint64_t
+dispatch_benchmark(size_t count, void (^block)(void));
+#endif
+
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL3 DISPATCH_NOTHROW
+uint64_t
+dispatch_benchmark_f(size_t count, void *ctxt, void (*func)(void *));
+
+__END_DECLS
+
+#endif
Copied: trunk/dispatch/dispatch.h (from rev 35, trunk/src/dispatch.h)
===================================================================
--- trunk/dispatch/dispatch.h (rev 0)
+++ trunk/dispatch/dispatch.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_PUBLIC__
+#define __DISPATCH_PUBLIC__
+
+#ifdef __APPLE__
+#include <Availability.h>
+#endif
+#include <sys/cdefs.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+#include <stdarg.h>
+
+#define DISPATCH_API_VERSION 20090501
+
+#ifndef __DISPATCH_BUILDING_DISPATCH__
+
+#ifndef __DISPATCH_INDIRECT__
+#define __DISPATCH_INDIRECT__
+#endif
+
+#include <dispatch/base.h>
+#include <dispatch/object.h>
+#include <dispatch/time.h>
+#include <dispatch/queue.h>
+#include <dispatch/source.h>
+#include <dispatch/group.h>
+#include <dispatch/semaphore.h>
+#include <dispatch/once.h>
+
+#undef __DISPATCH_INDIRECT__
+
+#endif /* !__DISPATCH_BUILDING_DISPATCH__ */
+
+#endif
Copied: trunk/dispatch/group.h (from rev 35, trunk/src/group.h)
===================================================================
--- trunk/dispatch/group.h (rev 0)
+++ trunk/dispatch/group.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,273 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_GROUP__
+#define __DISPATCH_GROUP__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+/*!
+ * @typedef dispatch_group_t
+ * @abstract
+ * A group of blocks submitted to queues for asynchronous invocation.
+ */
+DISPATCH_DECL(dispatch_group);
+
+__BEGIN_DECLS
+
+/*!
+ * @function dispatch_group_create
+ *
+ * @abstract
+ * Creates new group with which blocks may be associated.
+ *
+ * @discussion
+ * This function creates a new group with which blocks may be associated.
+ * The dispatch group may be used to wait for the completion of the blocks it
+ * references. The group object memory is freed with dispatch_release().
+ *
+ * @result
+ * The newly created group, or NULL on failure.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_WARN_RESULT
+dispatch_group_t
+dispatch_group_create(void);
+
+/*!
+ * @function dispatch_group_async
+ *
+ * @abstract
+ * Submits a block to a dispatch queue and associates the block with the given
+ * dispatch group.
+ *
+ * @discussion
+ * Submits a block to a dispatch queue and associates the block with the given
+ * dispatch group. The dispatch group may be used to wait for the completion
+ * of the blocks it references.
+ *
+ * @param group
+ * A dispatch group to associate with the submitted block.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param queue
+ * The dispatch queue to which the block will be submitted for asynchronous
+ * invocation.
+ *
+ * @param block
+ * The block to perform asynchronously.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL
+void
+dispatch_group_async(dispatch_group_t group,
+ dispatch_queue_t queue,
+ dispatch_block_t block);
+#endif /* __BLOCKS__ */
+
+/*!
+ * @function dispatch_group_async_f
+ *
+ * @abstract
+ * Submits a function to a dispatch queue and associates the block with the
+ * given dispatch group.
+ *
+ * @discussion
+ * See dispatch_group_async() for details.
+ *
+ * @param group
+ * A dispatch group to associate with the submitted function.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param queue
+ * The dispatch queue to which the function will be submitted for asynchronous
+ * invocation.
+ *
+ * @param context
+ * The application-defined context parameter to pass to the function.
+ *
+ * @param work
+ * The application-defined function to invoke on the target queue. The first
+ * parameter passed to this function is the context provided to
+ * dispatch_group_async_f().
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
+void
+dispatch_group_async_f(dispatch_group_t group,
+ dispatch_queue_t queue,
+ void *context,
+ dispatch_function_t work);
+
+/*!
+ * @function dispatch_group_wait
+ *
+ * @abstract
+ * Wait synchronously for the previously submitted blocks to complete;
+ * returns if the blocks have not completed within the specified timeout.
+ *
+ * @discussion
+ * This function waits for the completion of the blocks associated with the
+ * given dispatch group, and returns after all blocks have completed or when
+ * the specified timeout has elapsed. When a timeout occurs, the group is
+ * restored to its original state.
+ *
+ * This function will return immediately if there are no blocks associated
+ * with the dispatch group (i.e. the group is empty).
+ *
+ * The result of calling this function from mulitple threads simultaneously
+ * with the same dispatch group is undefined.
+ *
+ * After the successful return of this function, the dispatch group is empty.
+ * It may either be released with dispatch_release() or re-used for additional
+ * blocks. See dispatch_group_async() for more information.
+ *
+ * @param group
+ * The dispatch group to wait on.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param timeout
+ * When to timeout (see dispatch_time). As a convenience, there are the
+ * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
+ *
+ * @result
+ * Returns zero on success (all blocks associated with the group completed
+ * within the specified timeout) or non-zero on error (i.e. timed out).
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL
+long
+dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);
+
+/*!
+ * @function dispatch_group_notify
+ *
+ * @abstract
+ * Schedule a block to be submitted to a queue when a group of previously
+ * submitted blocks have completed.
+ *
+ * @discussion
+ * This function schedules a notification block to be submitted to the specified
+ * queue once all blocks associated with the dispatch group have completed.
+ *
+ * If no blocks are associated with the dispatch group (i.e. the group is empty)
+ * then the notification block will be submitted immediately.
+ *
+ * The group will be empty at the time the notification block is submitted to
+ * the target queue. The group may either be released with dispatch_release()
+ * or reused for additional operations.
+ * See dispatch_group_async() for more information.
+ *
+ * @param group
+ * The dispatch group to observe.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param queue
+ * The queue to which the supplied block will be submitted when the group
+ * completes.
+ *
+ * @param block
+ * The block to submit when the group completes.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL
+void
+dispatch_group_notify(dispatch_group_t group,
+ dispatch_queue_t queue,
+ dispatch_block_t block);
+#endif /* __BLOCKS__ */
+
+/*!
+ * @function dispatch_group_notify_f
+ *
+ * @abstract
+ * Schedule a function to be submitted to a queue when a group of previously
+ * submitted functions have completed.
+ *
+ * @discussion
+ * See dispatch_group_notify() for details.
+ *
+ * @param group
+ * The dispatch group to observe.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param context
+ * The application-defined context parameter to pass to the function.
+ *
+ * @param work
+ * The application-defined function to invoke on the target queue. The first
+ * parameter passed to this function is the context provided to
+ * dispatch_group_notify_f().
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
+void
+dispatch_group_notify_f(dispatch_group_t group,
+ dispatch_queue_t queue,
+ void *context,
+ dispatch_function_t work);
+
+/*!
+ * @function dispatch_group_enter
+ *
+ * @abstract
+ * Manually indicate a block has entered the group
+ *
+ * @discussion
+ * Calling this function indicates another block has joined the group through
+ * a means other than dispatch_group_async(). Calls to this function must be
+ * balanced with dispatch_group_leave().
+ *
+ * @param group
+ * The dispatch group to update.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW DISPATCH_NONNULL_ALL
+void
+dispatch_group_enter(dispatch_group_t group);
+
+/*!
+ * @function dispatch_group_leave
+ *
+ * @abstract
+ * Manually indicate a block in the group has completed
+ *
+ * @discussion
+ * Calling this function indicates block has completed and left the dispatch
+ * groupJ by a means other than dispatch_group_async().
+ *
+ * @param group
+ * The dispatch group to update.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW DISPATCH_NONNULL_ALL
+void
+dispatch_group_leave(dispatch_group_t group);
+
+__END_DECLS
+
+#endif
Copied: trunk/dispatch/object.h (from rev 35, trunk/src/object.h)
===================================================================
--- trunk/dispatch/object.h (rev 0)
+++ trunk/dispatch/object.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,195 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_OBJECT__
+#define __DISPATCH_OBJECT__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+__BEGIN_DECLS
+
+/*!
+ * @function dispatch_debug
+ *
+ * @abstract
+ * Programmatically log debug information about a dispatch object.
+ *
+ * @param object
+ * The object to introspect.
+ *
+ * @param message
+ * The message to log above and beyond the introspection.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL2 DISPATCH_NOTHROW __attribute__((__format__(printf,2,3)))
+void
+dispatch_debug(dispatch_object_t object, const char *message, ...);
+
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL2 DISPATCH_NOTHROW __attribute__((__format__(printf,2,0)))
+void
+dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
+
+/*!
+ * @function dispatch_retain
+ *
+ * @abstract
+ * Increment the reference count of a dispatch object.
+ *
+ * @discussion
+ * Calls to dispatch_retain() must be balanced with calls to
+ * dispatch_release().
+ *
+ * @param object
+ * The object to retain.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_retain(dispatch_object_t object);
+
+/*!
+ * @function dispatch_release
+ *
+ * @abstract
+ * Decrement the reference count of a dispatch object.
+ *
+ * @discussion
+ * A dispatch object is asynchronously deallocated once all references are
+ * released (i.e. the reference count becomes zero). The system does not
+ * guarantee that a given client is the last or only reference to a given
+ * object.
+ *
+ * @param object
+ * The object to release.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_release(dispatch_object_t object);
+
+/*!
+ * @function dispatch_get_context
+ *
+ * @abstract
+ * Returns the application defined context of the object.
+ *
+ * @param object
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * The context of the object; may be NULL.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+void *
+dispatch_get_context(dispatch_object_t object);
+
+/*!
+ * @function dispatch_set_context
+ *
+ * @abstract
+ * Associates an application defined context with the object.
+ *
+ * @param object
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param context
+ * The new client defined context for the object. This may be NULL.
+ *
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW //DISPATCH_NONNULL1
+void
+dispatch_set_context(dispatch_object_t object, void *context);
+
+/*!
+ * @function dispatch_set_finalizer_f
+ *
+ * @abstract
+ * Set the finalizer function for a dispatch object.
+ *
+ * @param
+ * The dispatch object to modify.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param
+ * The finalizer function pointer.
+ *
+ * @discussion
+ * A dispatch object's finalizer will be invoked on the object's target queue
+ * after all references to the object have been released. This finalizer may be
+ * used by the application to release any resources associated with the object,
+ * such as freeing the object's context.
+ * The context parameter passed to the finalizer function is the current
+ * context of the dispatch object at the time the finalizer call is made.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW //DISPATCH_NONNULL1
+void
+dispatch_set_finalizer_f(dispatch_object_t object,
+ dispatch_function_t finalizer);
+
+/*!
+ * @function dispatch_suspend
+ *
+ * @abstract
+ * Suspends the invocation of blocks on a dispatch object.
+ *
+ * @discussion
+ * A suspended object will not invoke any blocks associated with it. The
+ * suspension of an object will occur after any running block associated with
+ * the object completes.
+ *
+ * Calls to dispatch_suspend() must be balanced with calls
+ * to dispatch_resume().
+ *
+ * @param object
+ * The object to be suspended.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_suspend(dispatch_object_t object);
+
+/*!
+ * @function dispatch_resume
+ *
+ * @abstract
+ * Resumes the invocation of blocks on a dispatch object.
+ *
+ * @param object
+ * The object to be resumed.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_resume(dispatch_object_t object);
+
+__END_DECLS
+
+#endif
Copied: trunk/dispatch/once.h (from rev 35, trunk/src/once.h)
===================================================================
--- trunk/dispatch/once.h (rev 0)
+++ trunk/dispatch/once.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_ONCE__
+#define __DISPATCH_ONCE__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+__BEGIN_DECLS
+
+/*!
+ * @typedef dispatch_once_t
+ *
+ * @abstract
+ * A predicate for use with dispatch_once(). It must be initialized to zero.
+ * Note: static and global variables default to zero.
+ */
+typedef long dispatch_once_t;
+
+/*!
+ * @function dispatch_once
+ *
+ * @abstract
+ * Execute a block once and only once.
+ *
+ * @param predicate
+ * A pointer to a dispatch_once_t that is used to test whether the block has
+ * completed or not.
+ *
+ * @param block
+ * The block to execute once.
+ *
+ * @discussion
+ * Always call dispatch_once() before using or testing any variables that are
+ * initialized by the block.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_once(dispatch_once_t *predicate, dispatch_block_t block);
+#ifdef __GNUC__
+#define dispatch_once(x, ...) do { if (__builtin_expect(*(x), ~0l) != ~0l) dispatch_once((x), (__VA_ARGS__)); } while (0)
+#endif
+#endif
+
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
+void
+dispatch_once_f(dispatch_once_t *predicate, void *context, void (*function)(void *));
+#ifdef __GNUC__
+#define dispatch_once_f(x, y, z) do { if (__builtin_expect(*(x), ~0l) != ~0l) dispatch_once_f((x), (y), (z)); } while (0)
+#endif
+
+__END_DECLS
+
+#endif
Copied: trunk/dispatch/queue.h (from rev 35, trunk/src/queue.h)
===================================================================
--- trunk/dispatch/queue.h (rev 0)
+++ trunk/dispatch/queue.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,568 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_QUEUE__
+#define __DISPATCH_QUEUE__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+/*!
+ * @header
+ *
+ * Dispatch is an abstract model for expressing concurrency via simple but
+ * powerful API.
+ *
+ * At the core, dispatch provides serial FIFO queues to which blocks may be
+ * submitted. Blocks submitted to these dispatch queues are invoked on a pool
+ * of threads fully managed by the system. No guarantee is made regarding
+ * which thread a block will be invoked on; however, it is guaranteed that only
+ * one block submitted to the FIFO dispatch queue will be invoked at a time.
+ *
+ * When multiple queues have blocks to be processed, the system is free to
+ * allocate additional threads to invoke the blocks concurrently. When the
+ * queues become empty, these threads are automatically released.
+ */
+
+/*!
+ * @typedef dispatch_queue_t
+ *
+ * @abstract
+ * Dispatch queues invoke blocks submitted to them serially in FIFO order. A
+ * queue will only invoke one block at a time, but independent queues may each
+ * invoke their blocks concurrently with respect to each other.
+ *
+ * @discussion
+ * Dispatch queues are lightweight objects to which blocks may be submitted.
+ * The system manages a pool of threads which process dispatch queues and
+ * invoke blocks submitted to them.
+ *
+ * Conceptually a dispatch queue may have its own thread of execution, and
+ * interaction between queues is highly asynchronous.
+ *
+ * Dispatch queues are reference counted via calls to dispatch_retain() and
+ * dispatch_release(). Pending blocks submitted to a queue also hold a
+ * reference to the queue until they have finished. Once all references to a
+ * queue have been released, the queue will be deallocated by the system.
+ */
+DISPATCH_DECL(dispatch_queue);
+
+/*!
+ * @typedef dispatch_queue_attr_t
+ *
+ * @abstract
+ * Attribute and policy extensions for dispatch queues.
+ */
+DISPATCH_DECL(dispatch_queue_attr);
+
+/*!
+ * @typedef dispatch_block_t
+ *
+ * @abstract
+ * The prototype of blocks submitted to dispatch queues, which take no
+ * arguments and have no return value.
+ *
+ * @discussion
+ * The declaration of a block allocates storage on the stack. Therefore, this
+ * is an invalid construct:
+ *
+ * dispatch_block_t block;
+ *
+ * if (x) {
+ * block = ^{ printf("true\n"); };
+ * } else {
+ * block = ^{ printf("false\n"); };
+ * }
+ * block(); // unsafe!!!
+ *
+ * What is happening behind the scenes:
+ *
+ * if (x) {
+ * struct Block __tmp_1 = ...; // setup details
+ * block = &__tmp_1;
+ * } else {
+ * struct Block __tmp_2 = ...; // setup details
+ * block = &__tmp_2;
+ * }
+ *
+ * As the example demonstrates, the address of a stack variable is escaping the
+ * scope in which it is allocated. That is a classic C bug.
+ */
+#ifdef __BLOCKS__
+typedef void (^dispatch_block_t)(void);
+#endif
+
+__BEGIN_DECLS
+
+/*!
+ * @function dispatch_async
+ *
+ * @abstract
+ * Submits a block for asynchronous execution on a dispatch queue.
+ *
+ * @discussion
+ * The dispatch_async() function is the fundamental mechanism for submitting
+ * blocks to a dispatch queue.
+ *
+ * Calls to dispatch_async() always return immediately after the block has
+ * been submitted, and never wait for the block to be invoked.
+ *
+ * The target queue determines whether the block will be invoked serially or
+ * concurrently with respect to other blocks submitted to that same queue.
+ * Serial queues are processed concurrently with with respect to each other.
+ *
+ * @param queue
+ * The target dispatch queue to which the block is submitted.
+ * The system will hold a reference on the target queue until the block
+ * has finished.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param block
+ * The block to submit to the target dispatch queue. This function performs
+ * Block_copy() and Block_release() on behalf of callers.
+ * The result of passing NULL in this parameter is undefined.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_async(dispatch_queue_t queue, dispatch_block_t block);
+#endif
+
+/*!
+ * @function dispatch_async_f
+ *
+ * @abstract
+ * Submits a function for asynchronous execution on a dispatch queue.
+ *
+ * @discussion
+ * See dispatch_async() for details.
+ *
+ * @param queue
+ * The target dispatch queue to which the function is submitted.
+ * The system will hold a reference on the target queue until the function
+ * has returned.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param context
+ * The application-defined context parameter to pass to the function.
+ *
+ * @param work
+ * The application-defined function to invoke on the target queue. The first
+ * parameter passed to this function is the context provided to
+ * dispatch_async_f().
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
+void
+dispatch_async_f(dispatch_queue_t queue,
+ void *context,
+ dispatch_function_t work);
+
+/*!
+ * @function dispatch_sync
+ *
+ * @abstract
+ * Submits a block for synchronous execution on a dispatch queue.
+ *
+ * @discussion
+ * Submits a block to a dispatch queue like dispatch_async(), however
+ * dispatch_sync() will not return until the block has finished.
+ *
+ * Calls to dispatch_sync() targeting the current queue will result
+ * in dead-lock. Use of dispatch_sync() is also subject to the same
+ * multi-party dead-lock problems that may result from the use of a mutex.
+ * Use of dispatch_async() is preferred.
+ *
+ * Unlike dispatch_async(), no retain is performed on the target queue. Because
+ * calls to this function are synchronous, the dispatch_sync() "borrows" the
+ * reference of the caller.
+ *
+ * As an optimization, dispatch_sync() invokes the block on the current
+ * thread when possible.
+ *
+ * @param queue
+ * The target dispatch queue to which the block is submitted.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param block
+ * The block to be invoked on the target dispatch queue.
+ * The result of passing NULL in this parameter is undefined.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_sync(dispatch_queue_t queue, dispatch_block_t block);
+#endif
+
+/*!
+ * @function dispatch_sync_f
+ *
+ * @abstract
+ * Submits a function for synchronous execution on a dispatch queue.
+ *
+ * @discussion
+ * See dispatch_sync() for details.
+ *
+ * @param queue
+ * The target dispatch queue to which the function is submitted.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param context
+ * The application-defined context parameter to pass to the function.
+ *
+ * @param work
+ * The application-defined function to invoke on the target queue. The first
+ * parameter passed to this function is the context provided to
+ * dispatch_sync_f().
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
+void
+dispatch_sync_f(dispatch_queue_t queue,
+ void *context,
+ dispatch_function_t work);
+
+/*!
+ * @function dispatch_apply
+ *
+ * @abstract
+ * Submits a block to a dispatch queue for multiple invocations.
+ *
+ * @discussion
+ * Submits a block to a dispatch queue for multiple invocations. This function
+ * waits for the task block to complete before returning. If the target queue
+ * is a concurrent queue returned by dispatch_get_concurrent_queue(), the block
+ * may be invoked concurrently, and it must therefore be reentrant safe.
+ *
+ * Each invocation of the block will be passed the current index of iteration.
+ *
+ * @param iterations
+ * The number of iterations to perform.
+ *
+ * @param queue
+ * The target dispatch queue to which the block is submitted.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param block
+ * The block to be invoked the specified number of iterations.
+ * The result of passing NULL in this parameter is undefined.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_apply(size_t iterations, dispatch_queue_t queue, void (^block)(size_t));
+#endif
+
+/*!
+ * @function dispatch_apply_f
+ *
+ * @abstract
+ * Submits a function to a dispatch queue for multiple invocations.
+ *
+ * @discussion
+ * See dispatch_apply() for details.
+ *
+ * @param iterations
+ * The number of iterations to perform.
+ *
+ * @param queue
+ * The target dispatch queue to which the function is submitted.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param context
+ * The application-defined context parameter to pass to the function.
+ *
+ * @param work
+ * The application-defined function to invoke on the target queue. The first
+ * parameter passed to this function is the context provided to
+ * dispatch_apply_f(). The second parameter passed to this function is the
+ * current index of iteration.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
+void
+dispatch_apply_f(size_t iterations, dispatch_queue_t queue,
+ void *context,
+ void (*work)(void *, size_t));
+
+/*!
+ * @function dispatch_get_current_queue
+ *
+ * @abstract
+ * Returns the queue on which the currently executing block is running.
+ *
+ * @discussion
+ * Returns the queue on which the currently executing block is running.
+ *
+ * When dispatch_get_current_queue() is called outside of the context of a
+ * submitted block, it will return the default concurrent queue.
+ *
+ * @result
+ * Returns the current queue.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+dispatch_queue_t
+dispatch_get_current_queue(void);
+
+/*!
+ * @function dispatch_get_main_queue
+ *
+ * @abstract
+ * Returns the default queue that is bound to the main thread.
+ *
+ * @discussion
+ * In order to invoke blocks submitted to the main queue, the application must
+ * call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the main
+ * thread.
+ *
+ * @result
+ * Returns the main queue. This queue is created automatically on behalf of
+ * the main thread before main() is called.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern struct dispatch_queue_s _dispatch_main_q;
+#define dispatch_get_main_queue() (&_dispatch_main_q)
+
+/*!
+ * @enum dispatch_queue_priority_t
+ *
+ * @constant DISPATCH_QUEUE_PRIORITY_HIGH
+ * Items dispatched to the queue will run at high priority,
+ * i.e. the queue will be scheduled for execution before
+ * any default priority or low priority queue.
+ *
+ * @constant DISPATCH_QUEUE_PRIORITY_DEFAULT
+ * Items dispatched to the queue will run at the default
+ * priority, i.e. the queue will be scheduled for execution
+ * after all high priority queues have been scheduled, but
+ * before any low priority queues have been scheduled.
+ *
+ * @constant DISPATCH_QUEUE_PRIORITY_LOW
+ * Items dispatched to the queue will run at low priority,
+ * i.e. the queue will be scheduled for execution after all
+ * default priority and high priority queues have been
+ * scheduled.
+ */
+enum {
+ DISPATCH_QUEUE_PRIORITY_HIGH = 2,
+ DISPATCH_QUEUE_PRIORITY_DEFAULT = 0,
+ DISPATCH_QUEUE_PRIORITY_LOW = -2,
+};
+
+/*!
+ * @function dispatch_get_global_queue
+ *
+ * @abstract
+ * Returns a well-known global concurrent queue of a given priority level.
+ *
+ * @discussion
+ * The well-known global concurrent queues may not be modified. Calls to
+ * dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., will
+ * have no effect when used with queues returned by this function.
+ *
+ * @param priority
+ * A priority defined in dispatch_queue_priority_t
+ *
+ * @param flags
+ * Reserved for future use. Passing any value other than zero may result in
+ * a NULL return value.
+ *
+ * @result
+ * Returns the requested global queue.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+dispatch_queue_t
+dispatch_get_global_queue(long priority, unsigned long flags);
+
+/*!
+ * @function dispatch_queue_create
+ *
+ * @abstract
+ * Creates a new dispatch queue to which blocks may be submitted.
+ *
+ * @discussion
+ * Dispatch queues invoke blocks serially in FIFO order.
+ *
+ * When the dispatch queue is no longer needed, it should be released
+ * with dispatch_release(). Note that any pending blocks submitted
+ * to a queue will hold a reference to that queue. Therefore a queue
+ * will not be deallocated until all pending blocks have finished.
+ *
+ * @param label
+ * A string label to attach to the queue.
+ * This parameter is optional and may be NULL.
+ *
+ * @param attr
+ * Unused. Pass NULL for now.
+ *
+ * @result
+ * The newly created dispatch queue.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+dispatch_queue_t
+dispatch_queue_create(const char *label, dispatch_queue_attr_t attr);
+
+/*!
+ * @function dispatch_queue_get_label
+ *
+ * @abstract
+ * Returns the label of the queue that was specified when the
+ * queue was created.
+ *
+ * @param queue
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * The label of the queue. The result may be NULL.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+const char *
+dispatch_queue_get_label(dispatch_queue_t queue);
+
+/*!
+ * @function dispatch_set_target_queue
+ *
+ * @abstract
+ * Sets the target queue for the given object.
+ *
+ * @discussion
+ * An object's target queue is responsible for processing the object.
+ *
+ * A dispatch queue's priority is inherited by its target queue. Use the
+ * dispatch_get_global_queue() function to obtain suitable target queue
+ * of the desired priority.
+ *
+ * A dispatch source's target queue specifies where its event handler and
+ * cancellation handler blocks will be submitted.
+ *
+ * The result of calling dispatch_set_target_queue() on any other type of
+ * dispatch object is undefined.
+ *
+ * @param object
+ * The object to modify.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param queue
+ * The new target queue for the object. The queue is retained, and the
+ * previous one, if any, is released.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_set_target_queue(dispatch_object_t object, dispatch_queue_t queue);
+
+/*!
+ * @function dispatch_main
+ *
+ * @abstract
+ * Execute blocks submitted to the main queue.
+ *
+ * @discussion
+ * This function "parks" the main thread and waits for blocks to be submitted
+ * to the main queue. This function never returns.
+ *
+ * Applications that call NSApplicationMain() or CFRunLoopRun() on the
+ * main thread do not need to call dispatch_main().
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW DISPATCH_NORETURN
+void
+dispatch_main(void);
+
+/*!
+ * @function dispatch_after
+ *
+ * @abstract
+ * Schedule a block for execution on a given queue at a specified time.
+ *
+ * @discussion
+ * Passing DISPATCH_TIME_NOW as the "when" parameter is supported, but not as
+ * optimal as calling dispatch_async() instead. Passing DISPATCH_TIME_FOREVER
+ * is undefined.
+ *
+ * @param when
+ * A temporal milestone returned by dispatch_time() or dispatch_walltime().
+ *
+ * @param queue
+ * A queue to which the given block will be submitted at the specified time.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param block
+ * The block of code to execute.
+ * The result of passing NULL in this parameter is undefined.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW
+void
+dispatch_after(dispatch_time_t when,
+ dispatch_queue_t queue,
+ dispatch_block_t block);
+#endif
+
+/*!
+ * @function dispatch_after_f
+ *
+ * @abstract
+ * Schedule a function for execution on a given queue at a specified time.
+ *
+ * @discussion
+ * See dispatch_after() for details.
+ *
+ * @param when
+ * A temporal milestone returned by dispatch_time() or dispatch_walltime().
+ *
+ * @param queue
+ * A queue to which the given function will be submitted at the specified time.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param context
+ * The application-defined context parameter to pass to the function.
+ *
+ * @param work
+ * The application-defined function to invoke on the target queue. The first
+ * parameter passed to this function is the context provided to
+ * dispatch_after_f().
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
+void
+dispatch_after_f(dispatch_time_t when,
+ dispatch_queue_t queue,
+ void *context,
+ dispatch_function_t work);
+
+__END_DECLS
+
+#endif
Copied: trunk/dispatch/semaphore.h (from rev 35, trunk/src/semaphore.h)
===================================================================
--- trunk/dispatch/semaphore.h (rev 0)
+++ trunk/dispatch/semaphore.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_SEMAPHORE__
+#define __DISPATCH_SEMAPHORE__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+/*!
+ * @typedef dispatch_semaphore_t
+ *
+ * @abstract
+ * A counting semaphore.
+ */
+DISPATCH_DECL(dispatch_semaphore);
+
+__BEGIN_DECLS
+
+/*!
+ * @function dispatch_semaphore_create
+ *
+ * @abstract
+ * Creates new counting semaphore with an initial value.
+ *
+ * @discussion
+ * Passing zero for the value is useful for when two threads need to reconcile
+ * the completion of a particular event. Passing a value greather than zero is
+ * useful for managing a finite pool of resources, where the pool size is equal
+ * to the value.
+ *
+ * @param value
+ * The starting value for the semaphore. Passing a value less than zero will
+ * cause NULL to be returned.
+ *
+ * @result
+ * The newly created semaphore, or NULL on failure.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_MALLOC DISPATCH_NOTHROW
+dispatch_semaphore_t
+dispatch_semaphore_create(long value);
+
+/*!
+ * @function dispatch_semaphore_wait
+ *
+ * @abstract
+ * Wait (decrement) for a semaphore.
+ *
+ * @discussion
+ * Decrement the counting semaphore. If the resulting value is less than zero,
+ * this function waits in FIFO order for a signal to occur before returning.
+ *
+ * @param dsema
+ * The semaphore. The result of passing NULL in this parameter is undefined.
+ *
+ * @param timeout
+ * When to timeout (see dispatch_time). As a convenience, there are the
+ * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
+ *
+ * @result
+ * Returns zero on success, or non-zero if the timeout occurred.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+long
+dispatch_semaphore_wait(dispatch_semaphore_t dsema, dispatch_time_t timeout);
+
+/*!
+ * @function dispatch_semaphore_signal
+ *
+ * @abstract
+ * Signal (increment) a semaphore.
+ *
+ * @discussion
+ * Increment the counting semaphore. If the previous value was less than zero,
+ * this function wakes a waiting thread before returning.
+ *
+ * @param dsema The counting semaphore.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * This function returns non-zero if a thread is woken. Otherwise, zero is
+ * returned.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+long
+dispatch_semaphore_signal(dispatch_semaphore_t dsema);
+
+__END_DECLS
+
+#endif /* __DISPATCH_SEMAPHORE__ */
Copied: trunk/dispatch/source.h (from rev 35, trunk/src/source.h)
===================================================================
--- trunk/dispatch/source.h (rev 0)
+++ trunk/dispatch/source.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,585 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_SOURCE__
+#define __DISPATCH_SOURCE__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+#ifdef HAVE_MACH
+#include <mach/port.h>
+#include <mach/message.h>
+#endif
+#include <sys/signal.h>
+
+/*!
+ * @header
+ * The dispatch framework provides a suite of interfaces for monitoring low-
+ * level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.)
+ * for activity and automatically submitting event handler blocks to dispatch
+ * queues when such activity occurs.
+ *
+ * This suite of interfaces is known as the Dispatch Source API.
+ */
+
+/*!
+ * @typedef dispatch_source_t
+ *
+ * @abstract
+ * Dispatch sources are used to automatically submit event handler blocks to
+ * dispatch queues in response to external events.
+ */
+DISPATCH_DECL(dispatch_source);
+
+/*!
+ * @typedef dispatch_source_type_t
+ *
+ * @abstract
+ * Constants of this type represent the class of low-level system object that
+ * is being monitored by the dispatch source. Constants of this type are
+ * passed as a parameter to dispatch_source_create() and determine how the
+ * handle argument is interpreted (i.e. as a file descriptor, mach port,
+ * signal number, process identifer, etc.), and how the mask arugment is
+ * interpreted.
+ */
+typedef const struct dispatch_source_type_s *dispatch_source_type_t;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_DATA_ADD
+ * @discussion A dispatch source that coalesces data obtained via calls to
+ * dispatch_source_merge_data(). An ADD is used to coalesce the data.
+ * The handle is unused (pass zero for now).
+ * The mask is unused (pass zero for now).
+ */
+#define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_data_add;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_DATA_OR
+ * @discussion A dispatch source that coalesces data obtained via calls to
+ * dispatch_source_merge_data(). A logical OR is used to coalesce the data.
+ * The handle is unused (pass zero for now).
+ * The mask is used to perform a logical AND with the value passed to
+ * dispatch_source_merge_data().
+ */
+#define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_data_or;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_MACH_SEND
+ * @discussion A dispatch source that monitors a Mach port for dead name
+ * notifications (send right no longer has any corresponding receive right).
+ * The handle is a Mach port with a send or send-once right (mach_port_t).
+ * The mask is a mask of desired events from dispatch_source_mach_send_flags_t.
+ */
+#define DISPATCH_SOURCE_TYPE_MACH_SEND (&_dispatch_source_type_mach_send)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_mach_send;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_MACH_RECV
+ * @discussion A dispatch source that monitors a Mach port for pending messages.
+ * The handle is a Mach port with a receive right (mach_port_t).
+ * The mask is unused (pass zero for now).
+ */
+#define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_mach_recv;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_PROC
+ * @discussion A dispatch source that monitors an external process for events
+ * defined by dispatch_source_proc_flags_t.
+ * The handle is a process identifier (pid_t).
+ * The mask is a mask of desired events from dispatch_source_proc_flags_t.
+ */
+#define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_proc;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_READ
+ * @discussion A dispatch source that monitors a file descriptor for pending
+ * bytes available to be read.
+ * The handle is a file descriptor (int).
+ * The mask is unused (pass zero for now).
+ */
+#define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_read;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_SIGNAL
+ * @discussion A dispatch source that monitors the current process for signals.
+ * The handle is a signal number (int).
+ * The mask is unused (pass zero for now).
+ */
+#define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_signal;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_TIMER
+ * @discussion A dispatch source that submits the event handler block based
+ * on a timer.
+ * The handle is unused (pass zero for now).
+ * The mask is unused (pass zero for now).
+ */
+#define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_timer;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_VNODE
+ * @discussion A dispatch source that monitors a file descriptor for events
+ * defined by dispatch_source_vnode_flags_t.
+ * The handle is a file descriptor (int).
+ * The mask is a mask of desired events from dispatch_source_vnode_flags_t.
+ */
+#define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_vnode;
+
+/*!
+ * @const DISPATCH_SOURCE_TYPE_WRITE
+ * @discussion A dispatch source that monitors a file descriptor for available
+ * buffer space to write bytes.
+ * The handle is a file descriptor (int).
+ * The mask is unused (pass zero for now).
+ */
+#define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write)
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+extern const struct dispatch_source_type_s _dispatch_source_type_write;
+
+/*!
+ * @enum dispatch_source_mach_send_flags_t
+ *
+ * @constant DISPATCH_MACH_SEND_DEAD
+ * The receive right corresponding to the given send right was destroyed.
+ */
+enum {
+ DISPATCH_MACH_SEND_DEAD = 0x1,
+};
+
+/*!
+ * @enum dispatch_source_proc_flags_t
+ *
+ * @constant DISPATCH_PROC_EXIT
+ * The process has exited (perhaps cleanly, perhaps not).
+ *
+ * @constant DISPATCH_PROC_FORK
+ * The process has created one or more child processes.
+ *
+ * @constant DISPATCH_PROC_EXEC
+ * The process has become another executable image via
+ * exec*() or posix_spawn*().
+ *
+ * @constant DISPATCH_PROC_SIGNAL
+ * A Unix signal was delivered to the process.
+ */
+enum {
+ DISPATCH_PROC_EXIT = 0x80000000,
+ DISPATCH_PROC_FORK = 0x40000000,
+ DISPATCH_PROC_EXEC = 0x20000000,
+ DISPATCH_PROC_SIGNAL = 0x08000000,
+};
+
+/*!
+ * @enum dispatch_source_vnode_flags_t
+ *
+ * @constant DISPATCH_VNODE_DELETE
+ * The filesystem object was deleted from the namespace.
+ *
+ * @constant DISPATCH_VNODE_WRITE
+ * The filesystem object data changed.
+ *
+ * @constant DISPATCH_VNODE_EXTEND
+ * The filesystem object changed in size.
+ *
+ * @constant DISPATCH_VNODE_ATTRIB
+ * The filesystem object metadata changed.
+ *
+ * @constant DISPATCH_VNODE_LINK
+ * The filesystem object link count changed.
+ *
+ * @constant DISPATCH_VNODE_RENAME
+ * The filesystem object was renamed in the namespace.
+ *
+ * @constant DISPATCH_VNODE_REVOKE
+ * The filesystem object was revoked.
+ */
+enum {
+ DISPATCH_VNODE_DELETE = 0x1,
+ DISPATCH_VNODE_WRITE = 0x2,
+ DISPATCH_VNODE_EXTEND = 0x4,
+ DISPATCH_VNODE_ATTRIB = 0x8,
+ DISPATCH_VNODE_LINK = 0x10,
+ DISPATCH_VNODE_RENAME = 0x20,
+ DISPATCH_VNODE_REVOKE = 0x40,
+};
+
+__BEGIN_DECLS
+
+/*!
+ * @function dispatch_source_create
+ *
+ * @abstract
+ * Creates a new dispatch source to monitor low-level system objects and auto-
+ * matically submit a handler block to a dispatch queue in response to events.
+ *
+ * @discussion
+ * Dispatch sources are not reentrant. Any events received while the dispatch
+ * source is suspended or while the event handler block is currently executing
+ * will be coalesced and delivered after the dispatch source is resumed or the
+ * event handler block has returned.
+ *
+ * Dispatch sources are created in a suspended state. After creating the
+ * source and setting any desired attributes (i.e. the handler, context, etc.),
+ * a call must be made to dispatch_resume() in order to begin event delivery.
+ *
+ * @param type
+ * Declares the type of the dispatch source. Must be one of the defined
+ * dispatch_source_type_t constants.
+ * @param handle
+ * The underlying system handle to monitor. The interpretation of this argument
+ * is determined by the constant provided in the type parameter.
+ * @param mask
+ * A mask of flags specifying which events are desired. The interpretation of
+ * this argument is determined by the constant provided in the type parameter.
+ * @param queue
+ * The dispatch queue to which the event handler block will be submited.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_MALLOC DISPATCH_NOTHROW
+dispatch_source_t
+dispatch_source_create(dispatch_source_type_t type,
+ uintptr_t handle,
+ unsigned long mask,
+ dispatch_queue_t queue);
+
+/*!
+ * @function dispatch_source_set_event_handler
+ *
+ * @abstract
+ * Sets the event handler block for the given dispatch source.
+ *
+ * @param source
+ * The dispatch source to modify.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param handler
+ * The event handler block to submit to the source's target queue.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_source_set_event_handler(dispatch_source_t source,
+ dispatch_block_t handler);
+#endif /* __BLOCKS__ */
+
+/*!
+ * @function dispatch_source_set_event_handler_f
+ *
+ * @abstract
+ * Sets the event handler function for the given dispatch source.
+ *
+ * @param source
+ * The dispatch source to modify.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param handler
+ * The event handler function to submit to the source's target queue.
+ * The context parameter passed to the event handler function is the current
+ * context of the dispatch source at the time the handler call is made.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_source_set_event_handler_f(dispatch_source_t source,
+ dispatch_function_t handler);
+
+/*!
+ * @function dispatch_source_set_cancel_handler
+ *
+ * @abstract
+ * Sets the cancellation handler block for the given dispatch source.
+ *
+ * @discussion
+ * The cancellation handler (if specified) will be submitted to the source's
+ * target queue in response to a call to dispatch_source_cancel() once the
+ * system has released all references to the source's underlying handle and
+ * the source's event handler block has returned.
+ *
+ * IMPORTANT:
+ * A cancellation handler is required for file descriptor and mach port based
+ * sources in order to safely close the descriptor or destroy the port. Closing
+ * the descriptor or port before the cancellation handler may result in a race
+ * condition. If a new descriptor is allocated with the same value as the
+ * recently closed descriptor while the source's event handler is still running,
+ * the event handler may read/write data to the wrong descriptor.
+ *
+ * @param source
+ * The dispatch source to modify.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param handler
+ * The cancellation handler block to submit to the source's target queue.
+ */
+#ifdef __BLOCKS__
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_source_set_cancel_handler(dispatch_source_t source,
+ dispatch_block_t cancel_handler);
+#endif /* __BLOCKS__ */
+
+/*!
+ * @function dispatch_source_set_cancel_handler_f
+ *
+ * @abstract
+ * Sets the cancellation handler function for the given dispatch source.
+ *
+ * @discussion
+ * See dispatch_source_set_cancel_handler() for more details.
+ *
+ * @param source
+ * The dispatch source to modify.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param handler
+ * The cancellation handler function to submit to the source's target queue.
+ * The context parameter passed to the event handler function is the current
+ * context of the dispatch source at the time the handler call is made.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL1 DISPATCH_NOTHROW
+void
+dispatch_source_set_cancel_handler_f(dispatch_source_t source,
+ dispatch_function_t cancel_handler);
+
+/*!
+ * @function dispatch_source_cancel
+ *
+ * @abstract
+ * Asynchronously cancel the dispatch source, preventing any further invocation
+ * of its event handler block.
+ *
+ * @discussion
+ * Cancellation prevents any further invocation of the event handler block for
+ * the specified dispatch source, but does not interrupt an event handler
+ * block that is already in progress.
+ *
+ * The cancellation handler is submitted to the source's target queue once the
+ * the source's event handler has finished, indicating it is now safe to close
+ * the source's handle (i.e. file descriptor or mach port).
+ *
+ * See dispatch_source_set_cancel_handler() for more information.
+ *
+ * @param source
+ * The dispatch source to be canceled.
+ * The result of passing NULL in this parameter is undefined.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_source_cancel(dispatch_source_t source);
+
+/*!
+ * @function dispatch_source_testcancel
+ *
+ * @abstract
+ * Tests whether the given dispatch source has been canceled.
+ *
+ * @param source
+ * The dispatch source to be tested.
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * Non-zero if canceled and zero if not canceled.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+long
+dispatch_source_testcancel(dispatch_source_t source);
+
+/*!
+ * @function dispatch_source_get_handle
+ *
+ * @abstract
+ * Returns the underlying system handle associated with this dispatch source.
+ *
+ * @param source
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * The return value should be interpreted according to the type of the dispatch
+ * source, and may be one of the following handles:
+ *
+ * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a
+ * DISPATCH_SOURCE_TYPE_DATA_OR: n/a
+ * DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t)
+ * DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t)
+ * DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t)
+ * DISPATCH_SOURCE_TYPE_READ: file descriptor (int)
+ * DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int)
+ * DISPATCH_SOURCE_TYPE_TIMER: n/a
+ * DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int)
+ * DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int)
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
+uintptr_t
+dispatch_source_get_handle(dispatch_source_t source);
+
+/*!
+ * @function dispatch_source_get_mask
+ *
+ * @abstract
+ * Returns the mask of events monitored by the dispatch source.
+ *
+ * @param source
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * The return value should be interpreted according to the type of the dispatch
+ * source, and may be one of the following flag sets:
+ *
+ * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a
+ * DISPATCH_SOURCE_TYPE_DATA_OR: n/a
+ * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t
+ * DISPATCH_SOURCE_TYPE_MACH_RECV: n/a
+ * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t
+ * DISPATCH_SOURCE_TYPE_READ: n/a
+ * DISPATCH_SOURCE_TYPE_SIGNAL: n/a
+ * DISPATCH_SOURCE_TYPE_TIMER: n/a
+ * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t
+ * DISPATCH_SOURCE_TYPE_WRITE: n/a
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
+unsigned long
+dispatch_source_get_mask(dispatch_source_t source);
+
+/*!
+ * @function dispatch_source_get_data
+ *
+ * @abstract
+ * Returns pending data for the dispatch source.
+ *
+ * @discussion
+ * This function is intended to be called from within the event handler block.
+ * The result of calling this function outside of the event handler callback is
+ * undefined.
+ *
+ * @param source
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @result
+ * The return value should be interpreted according to the type of the dispatch
+ * source, and may be one of the following:
+ *
+ * DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data
+ * DISPATCH_SOURCE_TYPE_DATA_OR: application defined data
+ * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t
+ * DISPATCH_SOURCE_TYPE_MACH_RECV: n/a
+ * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t
+ * DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read
+ * DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since
+ * the last handler invocation
+ * DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired
+ * since the last handler invocation
+ * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t
+ * DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
+unsigned long
+dispatch_source_get_data(dispatch_source_t source);
+
+/*!
+ * @function dispatch_source_merge_data
+ *
+ * @abstract
+ * Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or
+ * DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its
+ * target queue.
+ *
+ * @param source
+ * The result of passing NULL in this parameter is undefined.
+ *
+ * @param value
+ * The value to coalesce with the pending data using a logical OR or an ADD
+ * as specified by the dispatch source type. A value of zero has no effect
+ * and will not result in the submission of the event handler block.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_source_merge_data(dispatch_source_t source, unsigned long value);
+
+/*!
+ * @function dispatch_source_set_timer
+ *
+ * @abstract
+ * Sets a start time, interval, and leeway value for a timer source.
+ *
+ * @discussion
+ * Calling this function has no effect if the timer source has already been
+ * canceled.
+ *
+ * The start time argument also determines which clock will be used for the
+ * timer. If the start time is DISPATCH_TIME_NOW or created with
+ * dispatch_time() then the timer is based on mach_absolute_time(). Otherwise,
+ * if the start time of the timer is created with dispatch_walltime() then the
+ * timer is based on gettimeofday(3).
+ *
+ * @param start
+ * The start time of the timer. See dispatch_time() and dispatch_walltime()
+ * for more information.
+ *
+ * @param interval
+ * The nanosecond interval for the timer.
+ *
+ * @param leeway
+ * A hint given to the system by the application for the amount of leeway, in
+ * nanoseconds, that the system may defer the timer in order to align with other
+ * system activity for improved system performance or power consumption. (For
+ * example, an application might perform a periodic task every 5 minutes, with
+ * a leeway of up to 30 seconds.) Note that some latency is to be expected for
+ * all timers even when a leeway value of zero is specified.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
+void
+dispatch_source_set_timer(dispatch_source_t source,
+ dispatch_time_t start,
+ uint64_t interval,
+ uint64_t leeway);
+
+__END_DECLS
+
+#endif
Copied: trunk/dispatch/time.h (from rev 35, trunk/src/time.h)
===================================================================
--- trunk/dispatch/time.h (rev 0)
+++ trunk/dispatch/time.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_START@
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @APPLE_APACHE_LICENSE_HEADER_END@
+ */
+
+#ifndef __DISPATCH_TIME__
+#define __DISPATCH_TIME__
+
+#ifndef __DISPATCH_INDIRECT__
+#error "Please #include <dispatch/dispatch.h> instead of this file directly."
+#include <dispatch/base.h> // for HeaderDoc
+#endif
+
+#include <stdint.h>
+
+__BEGIN_DECLS
+
+struct timespec;
+
+// 6368156
+#ifdef NSEC_PER_SEC
+#undef NSEC_PER_SEC
+#endif
+#ifdef USEC_PER_SEC
+#undef USEC_PER_SEC
+#endif
+#ifdef NSEC_PER_USEC
+#undef NSEC_PER_USEC
+#endif
+#define NSEC_PER_SEC 1000000000ull
+#define USEC_PER_SEC 1000000ull
+#define NSEC_PER_USEC 1000ull
+
+/*!
+ * @typedef dispatch_time_t
+ *
+ * @abstract
+ * An somewhat abstract representation of time; where zero means "now" and
+ * DISPATCH_TIME_FOREVER means "infinity" and every value in between is an
+ * opaque encoding.
+ */
+typedef uint64_t dispatch_time_t;
+
+#define DISPATCH_TIME_NOW 0
+#define DISPATCH_TIME_FOREVER (~0ull)
+
+/*!
+ * @function dispatch_time
+ *
+ * @abstract
+ * Create dispatch_time_t relative to the default clock or modify an existing
+ * dispatch_time_t.
+ *
+ * @discussion
+ * On Mac OS X the default clock is based on mach_absolute_time().
+ *
+ * @param when
+ * An optional dispatch_time_t to add nanoseconds to. If zero is passed, then
+ * dispatch_time() will use the result of mach_absolute_time().
+ *
+ * @param delta
+ * Nanoseconds to add.
+ *
+ * @result
+ * A new dispatch_time_t.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW
+dispatch_time_t
+dispatch_time(dispatch_time_t when, int64_t delta);
+
+/*!
+ * @function dispatch_walltime
+ *
+ * @abstract
+ * Create a dispatch_time_t using the wall clock.
+ *
+ * @discussion
+ * On Mac OS X the wall clock is based on gettimeofday(3).
+ *
+ * @param when
+ * A struct timespect to add time to. If NULL is passed, then
+ * dispatch_walltime() will use the result of gettimeofday(3).
+ *
+ * @param delta
+ * Nanoseconds to add.
+ *
+ * @result
+ * A new dispatch_time_t.
+ */
+__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
+DISPATCH_NOTHROW
+dispatch_time_t
+dispatch_walltime(const struct timespec *when, int64_t delta);
+
+__END_DECLS
+
+#endif
Modified: trunk/src/Makefile.am
===================================================================
--- trunk/src/Makefile.am 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/Makefile.am 2009-09-16 10:23:34 UTC (rev 36)
@@ -16,7 +16,8 @@
time.c
libdispatch_la_CFLAGS=-Wall -Werror
-INCLUDES=@APPLE_LIBC_SOURCE_PATH@ @APPLE_XNU_SOURCE_PATH@
+INCLUDES=-I$(top_builddir) -I$(top_srcdir) \
+ @APPLE_LIBC_SOURCE_PATH@ @APPLE_XNU_SOURCE_PATH@
#
# This will need some refinement: gcc requires a minimum of -march=i486 on
@@ -48,11 +49,3 @@
$(MIG) -user /dev/null -header protocol.h -server protocolServer.c \
-sheader protocolServer.h protocol.defs
endif
-
-#
-# This hack is needed because the default include line from automake will add
-# -I. to compiler commands. That leads to the local semaphore.h overriding
-# the one in /usr/local on systems using POSIX semaphores. We can remove
-# this hack once header files are moved to their own directory.
-#
-DEFAULT_INCLUDES = @am__isrc@ -I.. -I$(top_builddir)/config
Deleted: trunk/src/base.h
===================================================================
--- trunk/src/base.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/base.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,113 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_BASE__
-#define __DISPATCH_BASE__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#endif
-
-#ifdef __cplusplus
-/*
- * Dispatch objects are NOT C++ objects. Nevertheless, we can at least keep C++
- * aware of type compatibility.
- */
-typedef struct dispatch_object_s {
-private:
- dispatch_object_s();
- ~dispatch_object_s();
- dispatch_object_s(const dispatch_object_s &);
- void operator=(const dispatch_object_s &);
-} *dispatch_object_t;
-#else
-typedef union {
- struct dispatch_object_s *_do;
- struct dispatch_continuation_s *_dc;
- struct dispatch_queue_s *_dq;
- struct dispatch_queue_attr_s *_dqa;
- struct dispatch_group_s *_dg;
- struct dispatch_source_s *_ds;
- struct dispatch_source_attr_s *_dsa;
- struct dispatch_semaphore_s *_dsema;
-} dispatch_object_t __attribute__((transparent_union));
-#endif
-
-typedef void (*dispatch_function_t)(void *);
-
-#ifdef __cplusplus
-#define DISPATCH_DECL(name) typedef struct name##_s : public dispatch_object_s {} *name##_t;
-#else
-/*! @parseOnly */
-#define DISPATCH_DECL(name) typedef struct name##_s *name##_t;
-#endif
-
-#ifdef __GNUC__
-#define DISPATCH_NORETURN __attribute__((__noreturn__))
-#define DISPATCH_NOTHROW __attribute__((__nothrow__))
-#define DISPATCH_NONNULL1 __attribute__((__nonnull__(1)))
-#define DISPATCH_NONNULL2 __attribute__((__nonnull__(2)))
-#define DISPATCH_NONNULL3 __attribute__((__nonnull__(3)))
-#define DISPATCH_NONNULL4 __attribute__((__nonnull__(4)))
-#define DISPATCH_NONNULL5 __attribute__((__nonnull__(5)))
-#define DISPATCH_NONNULL6 __attribute__((__nonnull__(6)))
-#define DISPATCH_NONNULL7 __attribute__((__nonnull__(7)))
-#if __clang__
-// rdar://problem/6857843
-#define DISPATCH_NONNULL_ALL
-#else
-#define DISPATCH_NONNULL_ALL __attribute__((__nonnull__))
-#endif
-#define DISPATCH_SENTINEL __attribute__((__sentinel__))
-#define DISPATCH_PURE __attribute__((__pure__))
-#define DISPATCH_WARN_RESULT __attribute__((__warn_unused_result__))
-#define DISPATCH_MALLOC __attribute__((__malloc__))
-#else
-/*! @parseOnly */
-#define DISPATCH_NORETURN
-/*! @parseOnly */
-#define DISPATCH_NOTHROW
-/*! @parseOnly */
-#define DISPATCH_NONNULL1
-/*! @parseOnly */
-#define DISPATCH_NONNULL2
-/*! @parseOnly */
-#define DISPATCH_NONNULL3
-/*! @parseOnly */
-#define DISPATCH_NONNULL4
-/*! @parseOnly */
-#define DISPATCH_NONNULL5
-/*! @parseOnly */
-#define DISPATCH_NONNULL6
-/*! @parseOnly */
-#define DISPATCH_NONNULL7
-/*! @parseOnly */
-#define DISPATCH_NONNULL_ALL
-/*! @parseOnly */
-#define DISPATCH_SENTINEL
-/*! @parseOnly */
-#define DISPATCH_PURE
-/*! @parseOnly */
-#define DISPATCH_WARN_RESULT
-/*! @parseOnly */
-#define DISPATCH_MALLOC
-#endif
-
-#endif
Deleted: trunk/src/benchmark.h
===================================================================
--- trunk/src/benchmark.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/benchmark.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,83 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-/*
- * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
- * which are subject to change in future releases of Mac OS X. Any applications
- * relying on these interfaces WILL break.
- */
-
-#ifndef __DISPATCH_BENCHMARK__
-#define __DISPATCH_BENCHMARK__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-__BEGIN_DECLS
-
-/*!
- * @function dispatch_benchmark
- *
- * @abstract
- * Count the average number of cycles a given block takes to execute.
- *
- * @param count
- * The number of times to serially execute the given block.
- *
- * @param block
- * The block to execute.
- *
- * @result
- * The approximate number of cycles the block takes to execute.
- *
- * @discussion
- * This function is for debugging and performance analysis work. For the best
- * results, pass a high count value to dispatch_benchmark(). When benchmarking
- * concurrent code, please compare the serial version of the code against the
- * concurrent version, and compare the concurrent version on different classes
- * of hardware. Please look for inflection points with various data sets and
- * keep the following facts in mind:
- *
- * 1) Code bound by computational bandwidth may be inferred by proportional
- * changes in performance as concurrency is increased.
- * 2) Code bound by memory bandwidth may be inferred by negligible changes in
- * performance as concurrency is increased.
- * 3) Code bound by critical sections may be inferred by retrograde changes in
- * performance as concurrency is increased.
- * 3a) Intentional: locks, mutexes, and condition variables.
- * 3b) Accidental: unrelated and frequently modified data on the same cache-line.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL2 DISPATCH_NOTHROW
-uint64_t
-dispatch_benchmark(size_t count, void (^block)(void));
-#endif
-
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL3 DISPATCH_NOTHROW
-uint64_t
-dispatch_benchmark_f(size_t count, void *ctxt, void (*func)(void *));
-
-__END_DECLS
-
-#endif
Deleted: trunk/src/dispatch.h
===================================================================
--- trunk/src/dispatch.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/dispatch.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,54 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_PUBLIC__
-#define __DISPATCH_PUBLIC__
-
-#ifdef __APPLE__
-#include <Availability.h>
-#endif
-#include <sys/cdefs.h>
-#include <stddef.h>
-#include <stdint.h>
-#include <stdbool.h>
-#include <stdarg.h>
-
-#define DISPATCH_API_VERSION 20090501
-
-#ifndef __DISPATCH_BUILDING_DISPATCH__
-
-#ifndef __DISPATCH_INDIRECT__
-#define __DISPATCH_INDIRECT__
-#endif
-
-#include <dispatch/base.h>
-#include <dispatch/object.h>
-#include <dispatch/time.h>
-#include <dispatch/queue.h>
-#include <dispatch/source.h>
-#include <dispatch/group.h>
-#include <dispatch/semaphore.h>
-#include <dispatch/once.h>
-
-#undef __DISPATCH_INDIRECT__
-
-#endif /* !__DISPATCH_BUILDING_DISPATCH__ */
-
-#endif
Deleted: trunk/src/group.h
===================================================================
--- trunk/src/group.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/group.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,273 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_GROUP__
-#define __DISPATCH_GROUP__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-/*!
- * @typedef dispatch_group_t
- * @abstract
- * A group of blocks submitted to queues for asynchronous invocation.
- */
-DISPATCH_DECL(dispatch_group);
-
-__BEGIN_DECLS
-
-/*!
- * @function dispatch_group_create
- *
- * @abstract
- * Creates new group with which blocks may be associated.
- *
- * @discussion
- * This function creates a new group with which blocks may be associated.
- * The dispatch group may be used to wait for the completion of the blocks it
- * references. The group object memory is freed with dispatch_release().
- *
- * @result
- * The newly created group, or NULL on failure.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_WARN_RESULT
-dispatch_group_t
-dispatch_group_create(void);
-
-/*!
- * @function dispatch_group_async
- *
- * @abstract
- * Submits a block to a dispatch queue and associates the block with the given
- * dispatch group.
- *
- * @discussion
- * Submits a block to a dispatch queue and associates the block with the given
- * dispatch group. The dispatch group may be used to wait for the completion
- * of the blocks it references.
- *
- * @param group
- * A dispatch group to associate with the submitted block.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param queue
- * The dispatch queue to which the block will be submitted for asynchronous
- * invocation.
- *
- * @param block
- * The block to perform asynchronously.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL
-void
-dispatch_group_async(dispatch_group_t group,
- dispatch_queue_t queue,
- dispatch_block_t block);
-#endif /* __BLOCKS__ */
-
-/*!
- * @function dispatch_group_async_f
- *
- * @abstract
- * Submits a function to a dispatch queue and associates the block with the
- * given dispatch group.
- *
- * @discussion
- * See dispatch_group_async() for details.
- *
- * @param group
- * A dispatch group to associate with the submitted function.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param queue
- * The dispatch queue to which the function will be submitted for asynchronous
- * invocation.
- *
- * @param context
- * The application-defined context parameter to pass to the function.
- *
- * @param work
- * The application-defined function to invoke on the target queue. The first
- * parameter passed to this function is the context provided to
- * dispatch_group_async_f().
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
-void
-dispatch_group_async_f(dispatch_group_t group,
- dispatch_queue_t queue,
- void *context,
- dispatch_function_t work);
-
-/*!
- * @function dispatch_group_wait
- *
- * @abstract
- * Wait synchronously for the previously submitted blocks to complete;
- * returns if the blocks have not completed within the specified timeout.
- *
- * @discussion
- * This function waits for the completion of the blocks associated with the
- * given dispatch group, and returns after all blocks have completed or when
- * the specified timeout has elapsed. When a timeout occurs, the group is
- * restored to its original state.
- *
- * This function will return immediately if there are no blocks associated
- * with the dispatch group (i.e. the group is empty).
- *
- * The result of calling this function from mulitple threads simultaneously
- * with the same dispatch group is undefined.
- *
- * After the successful return of this function, the dispatch group is empty.
- * It may either be released with dispatch_release() or re-used for additional
- * blocks. See dispatch_group_async() for more information.
- *
- * @param group
- * The dispatch group to wait on.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param timeout
- * When to timeout (see dispatch_time). As a convenience, there are the
- * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
- *
- * @result
- * Returns zero on success (all blocks associated with the group completed
- * within the specified timeout) or non-zero on error (i.e. timed out).
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL
-long
-dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);
-
-/*!
- * @function dispatch_group_notify
- *
- * @abstract
- * Schedule a block to be submitted to a queue when a group of previously
- * submitted blocks have completed.
- *
- * @discussion
- * This function schedules a notification block to be submitted to the specified
- * queue once all blocks associated with the dispatch group have completed.
- *
- * If no blocks are associated with the dispatch group (i.e. the group is empty)
- * then the notification block will be submitted immediately.
- *
- * The group will be empty at the time the notification block is submitted to
- * the target queue. The group may either be released with dispatch_release()
- * or reused for additional operations.
- * See dispatch_group_async() for more information.
- *
- * @param group
- * The dispatch group to observe.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param queue
- * The queue to which the supplied block will be submitted when the group
- * completes.
- *
- * @param block
- * The block to submit when the group completes.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL
-void
-dispatch_group_notify(dispatch_group_t group,
- dispatch_queue_t queue,
- dispatch_block_t block);
-#endif /* __BLOCKS__ */
-
-/*!
- * @function dispatch_group_notify_f
- *
- * @abstract
- * Schedule a function to be submitted to a queue when a group of previously
- * submitted functions have completed.
- *
- * @discussion
- * See dispatch_group_notify() for details.
- *
- * @param group
- * The dispatch group to observe.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param context
- * The application-defined context parameter to pass to the function.
- *
- * @param work
- * The application-defined function to invoke on the target queue. The first
- * parameter passed to this function is the context provided to
- * dispatch_group_notify_f().
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
-void
-dispatch_group_notify_f(dispatch_group_t group,
- dispatch_queue_t queue,
- void *context,
- dispatch_function_t work);
-
-/*!
- * @function dispatch_group_enter
- *
- * @abstract
- * Manually indicate a block has entered the group
- *
- * @discussion
- * Calling this function indicates another block has joined the group through
- * a means other than dispatch_group_async(). Calls to this function must be
- * balanced with dispatch_group_leave().
- *
- * @param group
- * The dispatch group to update.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW DISPATCH_NONNULL_ALL
-void
-dispatch_group_enter(dispatch_group_t group);
-
-/*!
- * @function dispatch_group_leave
- *
- * @abstract
- * Manually indicate a block in the group has completed
- *
- * @discussion
- * Calling this function indicates block has completed and left the dispatch
- * groupJ by a means other than dispatch_group_async().
- *
- * @param group
- * The dispatch group to update.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW DISPATCH_NONNULL_ALL
-void
-dispatch_group_leave(dispatch_group_t group);
-
-__END_DECLS
-
-#endif
Modified: trunk/src/internal.h
===================================================================
--- trunk/src/internal.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/internal.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -45,16 +45,16 @@
#include <compat/private_extern.h>
#endif
-#include "dispatch.h"
-#include "base.h"
-#include "time.h"
-#include "queue.h"
-#include "object.h"
-#include "source.h"
-#include "group.h"
-#include "semaphore.h"
-#include "once.h"
-#include "benchmark.h"
+#include <dispatch/dispatch.h>
+#include <dispatch/base.h>
+#include <dispatch/time.h>
+#include <dispatch/queue.h>
+#include <dispatch/object.h>
+#include <dispatch/source.h>
+#include <dispatch/group.h>
+#include <dispatch/semaphore.h>
+#include <dispatch/once.h>
+#include <dispatch/benchmark.h>
/* private.h uses #include_next and must be included last to avoid picking
* up installed headers. */
Deleted: trunk/src/object.h
===================================================================
--- trunk/src/object.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/object.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,195 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_OBJECT__
-#define __DISPATCH_OBJECT__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-__BEGIN_DECLS
-
-/*!
- * @function dispatch_debug
- *
- * @abstract
- * Programmatically log debug information about a dispatch object.
- *
- * @param object
- * The object to introspect.
- *
- * @param message
- * The message to log above and beyond the introspection.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL2 DISPATCH_NOTHROW __attribute__((__format__(printf,2,3)))
-void
-dispatch_debug(dispatch_object_t object, const char *message, ...);
-
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL2 DISPATCH_NOTHROW __attribute__((__format__(printf,2,0)))
-void
-dispatch_debugv(dispatch_object_t object, const char *message, va_list ap);
-
-/*!
- * @function dispatch_retain
- *
- * @abstract
- * Increment the reference count of a dispatch object.
- *
- * @discussion
- * Calls to dispatch_retain() must be balanced with calls to
- * dispatch_release().
- *
- * @param object
- * The object to retain.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_retain(dispatch_object_t object);
-
-/*!
- * @function dispatch_release
- *
- * @abstract
- * Decrement the reference count of a dispatch object.
- *
- * @discussion
- * A dispatch object is asynchronously deallocated once all references are
- * released (i.e. the reference count becomes zero). The system does not
- * guarantee that a given client is the last or only reference to a given
- * object.
- *
- * @param object
- * The object to release.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_release(dispatch_object_t object);
-
-/*!
- * @function dispatch_get_context
- *
- * @abstract
- * Returns the application defined context of the object.
- *
- * @param object
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * The context of the object; may be NULL.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
-void *
-dispatch_get_context(dispatch_object_t object);
-
-/*!
- * @function dispatch_set_context
- *
- * @abstract
- * Associates an application defined context with the object.
- *
- * @param object
- * The result of passing NULL in this parameter is undefined.
- *
- * @param context
- * The new client defined context for the object. This may be NULL.
- *
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW //DISPATCH_NONNULL1
-void
-dispatch_set_context(dispatch_object_t object, void *context);
-
-/*!
- * @function dispatch_set_finalizer_f
- *
- * @abstract
- * Set the finalizer function for a dispatch object.
- *
- * @param
- * The dispatch object to modify.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param
- * The finalizer function pointer.
- *
- * @discussion
- * A dispatch object's finalizer will be invoked on the object's target queue
- * after all references to the object have been released. This finalizer may be
- * used by the application to release any resources associated with the object,
- * such as freeing the object's context.
- * The context parameter passed to the finalizer function is the current
- * context of the dispatch object at the time the finalizer call is made.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW //DISPATCH_NONNULL1
-void
-dispatch_set_finalizer_f(dispatch_object_t object,
- dispatch_function_t finalizer);
-
-/*!
- * @function dispatch_suspend
- *
- * @abstract
- * Suspends the invocation of blocks on a dispatch object.
- *
- * @discussion
- * A suspended object will not invoke any blocks associated with it. The
- * suspension of an object will occur after any running block associated with
- * the object completes.
- *
- * Calls to dispatch_suspend() must be balanced with calls
- * to dispatch_resume().
- *
- * @param object
- * The object to be suspended.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_suspend(dispatch_object_t object);
-
-/*!
- * @function dispatch_resume
- *
- * @abstract
- * Resumes the invocation of blocks on a dispatch object.
- *
- * @param object
- * The object to be resumed.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_resume(dispatch_object_t object);
-
-__END_DECLS
-
-#endif
Deleted: trunk/src/once.h
===================================================================
--- trunk/src/once.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/once.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,77 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_ONCE__
-#define __DISPATCH_ONCE__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-__BEGIN_DECLS
-
-/*!
- * @typedef dispatch_once_t
- *
- * @abstract
- * A predicate for use with dispatch_once(). It must be initialized to zero.
- * Note: static and global variables default to zero.
- */
-typedef long dispatch_once_t;
-
-/*!
- * @function dispatch_once
- *
- * @abstract
- * Execute a block once and only once.
- *
- * @param predicate
- * A pointer to a dispatch_once_t that is used to test whether the block has
- * completed or not.
- *
- * @param block
- * The block to execute once.
- *
- * @discussion
- * Always call dispatch_once() before using or testing any variables that are
- * initialized by the block.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_once(dispatch_once_t *predicate, dispatch_block_t block);
-#ifdef __GNUC__
-#define dispatch_once(x, ...) do { if (__builtin_expect(*(x), ~0l) != ~0l) dispatch_once((x), (__VA_ARGS__)); } while (0)
-#endif
-#endif
-
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
-void
-dispatch_once_f(dispatch_once_t *predicate, void *context, void (*function)(void *));
-#ifdef __GNUC__
-#define dispatch_once_f(x, y, z) do { if (__builtin_expect(*(x), ~0l) != ~0l) dispatch_once_f((x), (y), (z)); } while (0)
-#endif
-
-__END_DECLS
-
-#endif
Deleted: trunk/src/queue.h
===================================================================
--- trunk/src/queue.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/queue.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,568 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_QUEUE__
-#define __DISPATCH_QUEUE__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-/*!
- * @header
- *
- * Dispatch is an abstract model for expressing concurrency via simple but
- * powerful API.
- *
- * At the core, dispatch provides serial FIFO queues to which blocks may be
- * submitted. Blocks submitted to these dispatch queues are invoked on a pool
- * of threads fully managed by the system. No guarantee is made regarding
- * which thread a block will be invoked on; however, it is guaranteed that only
- * one block submitted to the FIFO dispatch queue will be invoked at a time.
- *
- * When multiple queues have blocks to be processed, the system is free to
- * allocate additional threads to invoke the blocks concurrently. When the
- * queues become empty, these threads are automatically released.
- */
-
-/*!
- * @typedef dispatch_queue_t
- *
- * @abstract
- * Dispatch queues invoke blocks submitted to them serially in FIFO order. A
- * queue will only invoke one block at a time, but independent queues may each
- * invoke their blocks concurrently with respect to each other.
- *
- * @discussion
- * Dispatch queues are lightweight objects to which blocks may be submitted.
- * The system manages a pool of threads which process dispatch queues and
- * invoke blocks submitted to them.
- *
- * Conceptually a dispatch queue may have its own thread of execution, and
- * interaction between queues is highly asynchronous.
- *
- * Dispatch queues are reference counted via calls to dispatch_retain() and
- * dispatch_release(). Pending blocks submitted to a queue also hold a
- * reference to the queue until they have finished. Once all references to a
- * queue have been released, the queue will be deallocated by the system.
- */
-DISPATCH_DECL(dispatch_queue);
-
-/*!
- * @typedef dispatch_queue_attr_t
- *
- * @abstract
- * Attribute and policy extensions for dispatch queues.
- */
-DISPATCH_DECL(dispatch_queue_attr);
-
-/*!
- * @typedef dispatch_block_t
- *
- * @abstract
- * The prototype of blocks submitted to dispatch queues, which take no
- * arguments and have no return value.
- *
- * @discussion
- * The declaration of a block allocates storage on the stack. Therefore, this
- * is an invalid construct:
- *
- * dispatch_block_t block;
- *
- * if (x) {
- * block = ^{ printf("true\n"); };
- * } else {
- * block = ^{ printf("false\n"); };
- * }
- * block(); // unsafe!!!
- *
- * What is happening behind the scenes:
- *
- * if (x) {
- * struct Block __tmp_1 = ...; // setup details
- * block = &__tmp_1;
- * } else {
- * struct Block __tmp_2 = ...; // setup details
- * block = &__tmp_2;
- * }
- *
- * As the example demonstrates, the address of a stack variable is escaping the
- * scope in which it is allocated. That is a classic C bug.
- */
-#ifdef __BLOCKS__
-typedef void (^dispatch_block_t)(void);
-#endif
-
-__BEGIN_DECLS
-
-/*!
- * @function dispatch_async
- *
- * @abstract
- * Submits a block for asynchronous execution on a dispatch queue.
- *
- * @discussion
- * The dispatch_async() function is the fundamental mechanism for submitting
- * blocks to a dispatch queue.
- *
- * Calls to dispatch_async() always return immediately after the block has
- * been submitted, and never wait for the block to be invoked.
- *
- * The target queue determines whether the block will be invoked serially or
- * concurrently with respect to other blocks submitted to that same queue.
- * Serial queues are processed concurrently with with respect to each other.
- *
- * @param queue
- * The target dispatch queue to which the block is submitted.
- * The system will hold a reference on the target queue until the block
- * has finished.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param block
- * The block to submit to the target dispatch queue. This function performs
- * Block_copy() and Block_release() on behalf of callers.
- * The result of passing NULL in this parameter is undefined.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_async(dispatch_queue_t queue, dispatch_block_t block);
-#endif
-
-/*!
- * @function dispatch_async_f
- *
- * @abstract
- * Submits a function for asynchronous execution on a dispatch queue.
- *
- * @discussion
- * See dispatch_async() for details.
- *
- * @param queue
- * The target dispatch queue to which the function is submitted.
- * The system will hold a reference on the target queue until the function
- * has returned.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param context
- * The application-defined context parameter to pass to the function.
- *
- * @param work
- * The application-defined function to invoke on the target queue. The first
- * parameter passed to this function is the context provided to
- * dispatch_async_f().
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
-void
-dispatch_async_f(dispatch_queue_t queue,
- void *context,
- dispatch_function_t work);
-
-/*!
- * @function dispatch_sync
- *
- * @abstract
- * Submits a block for synchronous execution on a dispatch queue.
- *
- * @discussion
- * Submits a block to a dispatch queue like dispatch_async(), however
- * dispatch_sync() will not return until the block has finished.
- *
- * Calls to dispatch_sync() targeting the current queue will result
- * in dead-lock. Use of dispatch_sync() is also subject to the same
- * multi-party dead-lock problems that may result from the use of a mutex.
- * Use of dispatch_async() is preferred.
- *
- * Unlike dispatch_async(), no retain is performed on the target queue. Because
- * calls to this function are synchronous, the dispatch_sync() "borrows" the
- * reference of the caller.
- *
- * As an optimization, dispatch_sync() invokes the block on the current
- * thread when possible.
- *
- * @param queue
- * The target dispatch queue to which the block is submitted.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param block
- * The block to be invoked on the target dispatch queue.
- * The result of passing NULL in this parameter is undefined.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_sync(dispatch_queue_t queue, dispatch_block_t block);
-#endif
-
-/*!
- * @function dispatch_sync_f
- *
- * @abstract
- * Submits a function for synchronous execution on a dispatch queue.
- *
- * @discussion
- * See dispatch_sync() for details.
- *
- * @param queue
- * The target dispatch queue to which the function is submitted.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param context
- * The application-defined context parameter to pass to the function.
- *
- * @param work
- * The application-defined function to invoke on the target queue. The first
- * parameter passed to this function is the context provided to
- * dispatch_sync_f().
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
-void
-dispatch_sync_f(dispatch_queue_t queue,
- void *context,
- dispatch_function_t work);
-
-/*!
- * @function dispatch_apply
- *
- * @abstract
- * Submits a block to a dispatch queue for multiple invocations.
- *
- * @discussion
- * Submits a block to a dispatch queue for multiple invocations. This function
- * waits for the task block to complete before returning. If the target queue
- * is a concurrent queue returned by dispatch_get_concurrent_queue(), the block
- * may be invoked concurrently, and it must therefore be reentrant safe.
- *
- * Each invocation of the block will be passed the current index of iteration.
- *
- * @param iterations
- * The number of iterations to perform.
- *
- * @param queue
- * The target dispatch queue to which the block is submitted.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param block
- * The block to be invoked the specified number of iterations.
- * The result of passing NULL in this parameter is undefined.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_apply(size_t iterations, dispatch_queue_t queue, void (^block)(size_t));
-#endif
-
-/*!
- * @function dispatch_apply_f
- *
- * @abstract
- * Submits a function to a dispatch queue for multiple invocations.
- *
- * @discussion
- * See dispatch_apply() for details.
- *
- * @param iterations
- * The number of iterations to perform.
- *
- * @param queue
- * The target dispatch queue to which the function is submitted.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param context
- * The application-defined context parameter to pass to the function.
- *
- * @param work
- * The application-defined function to invoke on the target queue. The first
- * parameter passed to this function is the context provided to
- * dispatch_apply_f(). The second parameter passed to this function is the
- * current index of iteration.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
-void
-dispatch_apply_f(size_t iterations, dispatch_queue_t queue,
- void *context,
- void (*work)(void *, size_t));
-
-/*!
- * @function dispatch_get_current_queue
- *
- * @abstract
- * Returns the queue on which the currently executing block is running.
- *
- * @discussion
- * Returns the queue on which the currently executing block is running.
- *
- * When dispatch_get_current_queue() is called outside of the context of a
- * submitted block, it will return the default concurrent queue.
- *
- * @result
- * Returns the current queue.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
-dispatch_queue_t
-dispatch_get_current_queue(void);
-
-/*!
- * @function dispatch_get_main_queue
- *
- * @abstract
- * Returns the default queue that is bound to the main thread.
- *
- * @discussion
- * In order to invoke blocks submitted to the main queue, the application must
- * call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the main
- * thread.
- *
- * @result
- * Returns the main queue. This queue is created automatically on behalf of
- * the main thread before main() is called.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern struct dispatch_queue_s _dispatch_main_q;
-#define dispatch_get_main_queue() (&_dispatch_main_q)
-
-/*!
- * @enum dispatch_queue_priority_t
- *
- * @constant DISPATCH_QUEUE_PRIORITY_HIGH
- * Items dispatched to the queue will run at high priority,
- * i.e. the queue will be scheduled for execution before
- * any default priority or low priority queue.
- *
- * @constant DISPATCH_QUEUE_PRIORITY_DEFAULT
- * Items dispatched to the queue will run at the default
- * priority, i.e. the queue will be scheduled for execution
- * after all high priority queues have been scheduled, but
- * before any low priority queues have been scheduled.
- *
- * @constant DISPATCH_QUEUE_PRIORITY_LOW
- * Items dispatched to the queue will run at low priority,
- * i.e. the queue will be scheduled for execution after all
- * default priority and high priority queues have been
- * scheduled.
- */
-enum {
- DISPATCH_QUEUE_PRIORITY_HIGH = 2,
- DISPATCH_QUEUE_PRIORITY_DEFAULT = 0,
- DISPATCH_QUEUE_PRIORITY_LOW = -2,
-};
-
-/*!
- * @function dispatch_get_global_queue
- *
- * @abstract
- * Returns a well-known global concurrent queue of a given priority level.
- *
- * @discussion
- * The well-known global concurrent queues may not be modified. Calls to
- * dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., will
- * have no effect when used with queues returned by this function.
- *
- * @param priority
- * A priority defined in dispatch_queue_priority_t
- *
- * @param flags
- * Reserved for future use. Passing any value other than zero may result in
- * a NULL return value.
- *
- * @result
- * Returns the requested global queue.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
-dispatch_queue_t
-dispatch_get_global_queue(long priority, unsigned long flags);
-
-/*!
- * @function dispatch_queue_create
- *
- * @abstract
- * Creates a new dispatch queue to which blocks may be submitted.
- *
- * @discussion
- * Dispatch queues invoke blocks serially in FIFO order.
- *
- * When the dispatch queue is no longer needed, it should be released
- * with dispatch_release(). Note that any pending blocks submitted
- * to a queue will hold a reference to that queue. Therefore a queue
- * will not be deallocated until all pending blocks have finished.
- *
- * @param label
- * A string label to attach to the queue.
- * This parameter is optional and may be NULL.
- *
- * @param attr
- * Unused. Pass NULL for now.
- *
- * @result
- * The newly created dispatch queue.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW
-dispatch_queue_t
-dispatch_queue_create(const char *label, dispatch_queue_attr_t attr);
-
-/*!
- * @function dispatch_queue_get_label
- *
- * @abstract
- * Returns the label of the queue that was specified when the
- * queue was created.
- *
- * @param queue
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * The label of the queue. The result may be NULL.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW
-const char *
-dispatch_queue_get_label(dispatch_queue_t queue);
-
-/*!
- * @function dispatch_set_target_queue
- *
- * @abstract
- * Sets the target queue for the given object.
- *
- * @discussion
- * An object's target queue is responsible for processing the object.
- *
- * A dispatch queue's priority is inherited by its target queue. Use the
- * dispatch_get_global_queue() function to obtain suitable target queue
- * of the desired priority.
- *
- * A dispatch source's target queue specifies where its event handler and
- * cancellation handler blocks will be submitted.
- *
- * The result of calling dispatch_set_target_queue() on any other type of
- * dispatch object is undefined.
- *
- * @param object
- * The object to modify.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param queue
- * The new target queue for the object. The queue is retained, and the
- * previous one, if any, is released.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_set_target_queue(dispatch_object_t object, dispatch_queue_t queue);
-
-/*!
- * @function dispatch_main
- *
- * @abstract
- * Execute blocks submitted to the main queue.
- *
- * @discussion
- * This function "parks" the main thread and waits for blocks to be submitted
- * to the main queue. This function never returns.
- *
- * Applications that call NSApplicationMain() or CFRunLoopRun() on the
- * main thread do not need to call dispatch_main().
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW DISPATCH_NORETURN
-void
-dispatch_main(void);
-
-/*!
- * @function dispatch_after
- *
- * @abstract
- * Schedule a block for execution on a given queue at a specified time.
- *
- * @discussion
- * Passing DISPATCH_TIME_NOW as the "when" parameter is supported, but not as
- * optimal as calling dispatch_async() instead. Passing DISPATCH_TIME_FOREVER
- * is undefined.
- *
- * @param when
- * A temporal milestone returned by dispatch_time() or dispatch_walltime().
- *
- * @param queue
- * A queue to which the given block will be submitted at the specified time.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param block
- * The block of code to execute.
- * The result of passing NULL in this parameter is undefined.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW
-void
-dispatch_after(dispatch_time_t when,
- dispatch_queue_t queue,
- dispatch_block_t block);
-#endif
-
-/*!
- * @function dispatch_after_f
- *
- * @abstract
- * Schedule a function for execution on a given queue at a specified time.
- *
- * @discussion
- * See dispatch_after() for details.
- *
- * @param when
- * A temporal milestone returned by dispatch_time() or dispatch_walltime().
- *
- * @param queue
- * A queue to which the given function will be submitted at the specified time.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param context
- * The application-defined context parameter to pass to the function.
- *
- * @param work
- * The application-defined function to invoke on the target queue. The first
- * parameter passed to this function is the context provided to
- * dispatch_after_f().
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW
-void
-dispatch_after_f(dispatch_time_t when,
- dispatch_queue_t queue,
- void *context,
- dispatch_function_t work);
-
-__END_DECLS
-
-#endif
Deleted: trunk/src/semaphore.h
===================================================================
--- trunk/src/semaphore.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/semaphore.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,112 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_SEMAPHORE__
-#define __DISPATCH_SEMAPHORE__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-/*!
- * @typedef dispatch_semaphore_t
- *
- * @abstract
- * A counting semaphore.
- */
-DISPATCH_DECL(dispatch_semaphore);
-
-__BEGIN_DECLS
-
-/*!
- * @function dispatch_semaphore_create
- *
- * @abstract
- * Creates new counting semaphore with an initial value.
- *
- * @discussion
- * Passing zero for the value is useful for when two threads need to reconcile
- * the completion of a particular event. Passing a value greather than zero is
- * useful for managing a finite pool of resources, where the pool size is equal
- * to the value.
- *
- * @param value
- * The starting value for the semaphore. Passing a value less than zero will
- * cause NULL to be returned.
- *
- * @result
- * The newly created semaphore, or NULL on failure.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_MALLOC DISPATCH_NOTHROW
-dispatch_semaphore_t
-dispatch_semaphore_create(long value);
-
-/*!
- * @function dispatch_semaphore_wait
- *
- * @abstract
- * Wait (decrement) for a semaphore.
- *
- * @discussion
- * Decrement the counting semaphore. If the resulting value is less than zero,
- * this function waits in FIFO order for a signal to occur before returning.
- *
- * @param dsema
- * The semaphore. The result of passing NULL in this parameter is undefined.
- *
- * @param timeout
- * When to timeout (see dispatch_time). As a convenience, there are the
- * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
- *
- * @result
- * Returns zero on success, or non-zero if the timeout occurred.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-long
-dispatch_semaphore_wait(dispatch_semaphore_t dsema, dispatch_time_t timeout);
-
-/*!
- * @function dispatch_semaphore_signal
- *
- * @abstract
- * Signal (increment) a semaphore.
- *
- * @discussion
- * Increment the counting semaphore. If the previous value was less than zero,
- * this function wakes a waiting thread before returning.
- *
- * @param dsema The counting semaphore.
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * This function returns non-zero if a thread is woken. Otherwise, zero is
- * returned.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-long
-dispatch_semaphore_signal(dispatch_semaphore_t dsema);
-
-__END_DECLS
-
-#endif /* __DISPATCH_SEMAPHORE__ */
Deleted: trunk/src/source.h
===================================================================
--- trunk/src/source.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/source.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,585 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_SOURCE__
-#define __DISPATCH_SOURCE__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-#ifdef HAVE_MACH
-#include <mach/port.h>
-#include <mach/message.h>
-#endif
-#include <sys/signal.h>
-
-/*!
- * @header
- * The dispatch framework provides a suite of interfaces for monitoring low-
- * level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.)
- * for activity and automatically submitting event handler blocks to dispatch
- * queues when such activity occurs.
- *
- * This suite of interfaces is known as the Dispatch Source API.
- */
-
-/*!
- * @typedef dispatch_source_t
- *
- * @abstract
- * Dispatch sources are used to automatically submit event handler blocks to
- * dispatch queues in response to external events.
- */
-DISPATCH_DECL(dispatch_source);
-
-/*!
- * @typedef dispatch_source_type_t
- *
- * @abstract
- * Constants of this type represent the class of low-level system object that
- * is being monitored by the dispatch source. Constants of this type are
- * passed as a parameter to dispatch_source_create() and determine how the
- * handle argument is interpreted (i.e. as a file descriptor, mach port,
- * signal number, process identifer, etc.), and how the mask arugment is
- * interpreted.
- */
-typedef const struct dispatch_source_type_s *dispatch_source_type_t;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_DATA_ADD
- * @discussion A dispatch source that coalesces data obtained via calls to
- * dispatch_source_merge_data(). An ADD is used to coalesce the data.
- * The handle is unused (pass zero for now).
- * The mask is unused (pass zero for now).
- */
-#define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_data_add;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_DATA_OR
- * @discussion A dispatch source that coalesces data obtained via calls to
- * dispatch_source_merge_data(). A logical OR is used to coalesce the data.
- * The handle is unused (pass zero for now).
- * The mask is used to perform a logical AND with the value passed to
- * dispatch_source_merge_data().
- */
-#define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_data_or;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_MACH_SEND
- * @discussion A dispatch source that monitors a Mach port for dead name
- * notifications (send right no longer has any corresponding receive right).
- * The handle is a Mach port with a send or send-once right (mach_port_t).
- * The mask is a mask of desired events from dispatch_source_mach_send_flags_t.
- */
-#define DISPATCH_SOURCE_TYPE_MACH_SEND (&_dispatch_source_type_mach_send)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_mach_send;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_MACH_RECV
- * @discussion A dispatch source that monitors a Mach port for pending messages.
- * The handle is a Mach port with a receive right (mach_port_t).
- * The mask is unused (pass zero for now).
- */
-#define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_mach_recv;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_PROC
- * @discussion A dispatch source that monitors an external process for events
- * defined by dispatch_source_proc_flags_t.
- * The handle is a process identifier (pid_t).
- * The mask is a mask of desired events from dispatch_source_proc_flags_t.
- */
-#define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_proc;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_READ
- * @discussion A dispatch source that monitors a file descriptor for pending
- * bytes available to be read.
- * The handle is a file descriptor (int).
- * The mask is unused (pass zero for now).
- */
-#define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_read;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_SIGNAL
- * @discussion A dispatch source that monitors the current process for signals.
- * The handle is a signal number (int).
- * The mask is unused (pass zero for now).
- */
-#define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_signal;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_TIMER
- * @discussion A dispatch source that submits the event handler block based
- * on a timer.
- * The handle is unused (pass zero for now).
- * The mask is unused (pass zero for now).
- */
-#define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_timer;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_VNODE
- * @discussion A dispatch source that monitors a file descriptor for events
- * defined by dispatch_source_vnode_flags_t.
- * The handle is a file descriptor (int).
- * The mask is a mask of desired events from dispatch_source_vnode_flags_t.
- */
-#define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_vnode;
-
-/*!
- * @const DISPATCH_SOURCE_TYPE_WRITE
- * @discussion A dispatch source that monitors a file descriptor for available
- * buffer space to write bytes.
- * The handle is a file descriptor (int).
- * The mask is unused (pass zero for now).
- */
-#define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-extern const struct dispatch_source_type_s _dispatch_source_type_write;
-
-/*!
- * @enum dispatch_source_mach_send_flags_t
- *
- * @constant DISPATCH_MACH_SEND_DEAD
- * The receive right corresponding to the given send right was destroyed.
- */
-enum {
- DISPATCH_MACH_SEND_DEAD = 0x1,
-};
-
-/*!
- * @enum dispatch_source_proc_flags_t
- *
- * @constant DISPATCH_PROC_EXIT
- * The process has exited (perhaps cleanly, perhaps not).
- *
- * @constant DISPATCH_PROC_FORK
- * The process has created one or more child processes.
- *
- * @constant DISPATCH_PROC_EXEC
- * The process has become another executable image via
- * exec*() or posix_spawn*().
- *
- * @constant DISPATCH_PROC_SIGNAL
- * A Unix signal was delivered to the process.
- */
-enum {
- DISPATCH_PROC_EXIT = 0x80000000,
- DISPATCH_PROC_FORK = 0x40000000,
- DISPATCH_PROC_EXEC = 0x20000000,
- DISPATCH_PROC_SIGNAL = 0x08000000,
-};
-
-/*!
- * @enum dispatch_source_vnode_flags_t
- *
- * @constant DISPATCH_VNODE_DELETE
- * The filesystem object was deleted from the namespace.
- *
- * @constant DISPATCH_VNODE_WRITE
- * The filesystem object data changed.
- *
- * @constant DISPATCH_VNODE_EXTEND
- * The filesystem object changed in size.
- *
- * @constant DISPATCH_VNODE_ATTRIB
- * The filesystem object metadata changed.
- *
- * @constant DISPATCH_VNODE_LINK
- * The filesystem object link count changed.
- *
- * @constant DISPATCH_VNODE_RENAME
- * The filesystem object was renamed in the namespace.
- *
- * @constant DISPATCH_VNODE_REVOKE
- * The filesystem object was revoked.
- */
-enum {
- DISPATCH_VNODE_DELETE = 0x1,
- DISPATCH_VNODE_WRITE = 0x2,
- DISPATCH_VNODE_EXTEND = 0x4,
- DISPATCH_VNODE_ATTRIB = 0x8,
- DISPATCH_VNODE_LINK = 0x10,
- DISPATCH_VNODE_RENAME = 0x20,
- DISPATCH_VNODE_REVOKE = 0x40,
-};
-
-__BEGIN_DECLS
-
-/*!
- * @function dispatch_source_create
- *
- * @abstract
- * Creates a new dispatch source to monitor low-level system objects and auto-
- * matically submit a handler block to a dispatch queue in response to events.
- *
- * @discussion
- * Dispatch sources are not reentrant. Any events received while the dispatch
- * source is suspended or while the event handler block is currently executing
- * will be coalesced and delivered after the dispatch source is resumed or the
- * event handler block has returned.
- *
- * Dispatch sources are created in a suspended state. After creating the
- * source and setting any desired attributes (i.e. the handler, context, etc.),
- * a call must be made to dispatch_resume() in order to begin event delivery.
- *
- * @param type
- * Declares the type of the dispatch source. Must be one of the defined
- * dispatch_source_type_t constants.
- * @param handle
- * The underlying system handle to monitor. The interpretation of this argument
- * is determined by the constant provided in the type parameter.
- * @param mask
- * A mask of flags specifying which events are desired. The interpretation of
- * this argument is determined by the constant provided in the type parameter.
- * @param queue
- * The dispatch queue to which the event handler block will be submited.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_MALLOC DISPATCH_NOTHROW
-dispatch_source_t
-dispatch_source_create(dispatch_source_type_t type,
- uintptr_t handle,
- unsigned long mask,
- dispatch_queue_t queue);
-
-/*!
- * @function dispatch_source_set_event_handler
- *
- * @abstract
- * Sets the event handler block for the given dispatch source.
- *
- * @param source
- * The dispatch source to modify.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param handler
- * The event handler block to submit to the source's target queue.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NOTHROW
-void
-dispatch_source_set_event_handler(dispatch_source_t source,
- dispatch_block_t handler);
-#endif /* __BLOCKS__ */
-
-/*!
- * @function dispatch_source_set_event_handler_f
- *
- * @abstract
- * Sets the event handler function for the given dispatch source.
- *
- * @param source
- * The dispatch source to modify.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param handler
- * The event handler function to submit to the source's target queue.
- * The context parameter passed to the event handler function is the current
- * context of the dispatch source at the time the handler call is made.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NOTHROW
-void
-dispatch_source_set_event_handler_f(dispatch_source_t source,
- dispatch_function_t handler);
-
-/*!
- * @function dispatch_source_set_cancel_handler
- *
- * @abstract
- * Sets the cancellation handler block for the given dispatch source.
- *
- * @discussion
- * The cancellation handler (if specified) will be submitted to the source's
- * target queue in response to a call to dispatch_source_cancel() once the
- * system has released all references to the source's underlying handle and
- * the source's event handler block has returned.
- *
- * IMPORTANT:
- * A cancellation handler is required for file descriptor and mach port based
- * sources in order to safely close the descriptor or destroy the port. Closing
- * the descriptor or port before the cancellation handler may result in a race
- * condition. If a new descriptor is allocated with the same value as the
- * recently closed descriptor while the source's event handler is still running,
- * the event handler may read/write data to the wrong descriptor.
- *
- * @param source
- * The dispatch source to modify.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param handler
- * The cancellation handler block to submit to the source's target queue.
- */
-#ifdef __BLOCKS__
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NOTHROW
-void
-dispatch_source_set_cancel_handler(dispatch_source_t source,
- dispatch_block_t cancel_handler);
-#endif /* __BLOCKS__ */
-
-/*!
- * @function dispatch_source_set_cancel_handler_f
- *
- * @abstract
- * Sets the cancellation handler function for the given dispatch source.
- *
- * @discussion
- * See dispatch_source_set_cancel_handler() for more details.
- *
- * @param source
- * The dispatch source to modify.
- * The result of passing NULL in this parameter is undefined.
- *
- * @param handler
- * The cancellation handler function to submit to the source's target queue.
- * The context parameter passed to the event handler function is the current
- * context of the dispatch source at the time the handler call is made.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL1 DISPATCH_NOTHROW
-void
-dispatch_source_set_cancel_handler_f(dispatch_source_t source,
- dispatch_function_t cancel_handler);
-
-/*!
- * @function dispatch_source_cancel
- *
- * @abstract
- * Asynchronously cancel the dispatch source, preventing any further invocation
- * of its event handler block.
- *
- * @discussion
- * Cancellation prevents any further invocation of the event handler block for
- * the specified dispatch source, but does not interrupt an event handler
- * block that is already in progress.
- *
- * The cancellation handler is submitted to the source's target queue once the
- * the source's event handler has finished, indicating it is now safe to close
- * the source's handle (i.e. file descriptor or mach port).
- *
- * See dispatch_source_set_cancel_handler() for more information.
- *
- * @param source
- * The dispatch source to be canceled.
- * The result of passing NULL in this parameter is undefined.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_source_cancel(dispatch_source_t source);
-
-/*!
- * @function dispatch_source_testcancel
- *
- * @abstract
- * Tests whether the given dispatch source has been canceled.
- *
- * @param source
- * The dispatch source to be tested.
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * Non-zero if canceled and zero if not canceled.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-long
-dispatch_source_testcancel(dispatch_source_t source);
-
-/*!
- * @function dispatch_source_get_handle
- *
- * @abstract
- * Returns the underlying system handle associated with this dispatch source.
- *
- * @param source
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * The return value should be interpreted according to the type of the dispatch
- * source, and may be one of the following handles:
- *
- * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a
- * DISPATCH_SOURCE_TYPE_DATA_OR: n/a
- * DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t)
- * DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t)
- * DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t)
- * DISPATCH_SOURCE_TYPE_READ: file descriptor (int)
- * DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int)
- * DISPATCH_SOURCE_TYPE_TIMER: n/a
- * DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int)
- * DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int)
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
-uintptr_t
-dispatch_source_get_handle(dispatch_source_t source);
-
-/*!
- * @function dispatch_source_get_mask
- *
- * @abstract
- * Returns the mask of events monitored by the dispatch source.
- *
- * @param source
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * The return value should be interpreted according to the type of the dispatch
- * source, and may be one of the following flag sets:
- *
- * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a
- * DISPATCH_SOURCE_TYPE_DATA_OR: n/a
- * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t
- * DISPATCH_SOURCE_TYPE_MACH_RECV: n/a
- * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t
- * DISPATCH_SOURCE_TYPE_READ: n/a
- * DISPATCH_SOURCE_TYPE_SIGNAL: n/a
- * DISPATCH_SOURCE_TYPE_TIMER: n/a
- * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t
- * DISPATCH_SOURCE_TYPE_WRITE: n/a
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
-unsigned long
-dispatch_source_get_mask(dispatch_source_t source);
-
-/*!
- * @function dispatch_source_get_data
- *
- * @abstract
- * Returns pending data for the dispatch source.
- *
- * @discussion
- * This function is intended to be called from within the event handler block.
- * The result of calling this function outside of the event handler callback is
- * undefined.
- *
- * @param source
- * The result of passing NULL in this parameter is undefined.
- *
- * @result
- * The return value should be interpreted according to the type of the dispatch
- * source, and may be one of the following:
- *
- * DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data
- * DISPATCH_SOURCE_TYPE_DATA_OR: application defined data
- * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t
- * DISPATCH_SOURCE_TYPE_MACH_RECV: n/a
- * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t
- * DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read
- * DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since
- * the last handler invocation
- * DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired
- * since the last handler invocation
- * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t
- * DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
-unsigned long
-dispatch_source_get_data(dispatch_source_t source);
-
-/*!
- * @function dispatch_source_merge_data
- *
- * @abstract
- * Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or
- * DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its
- * target queue.
- *
- * @param source
- * The result of passing NULL in this parameter is undefined.
- *
- * @param value
- * The value to coalesce with the pending data using a logical OR or an ADD
- * as specified by the dispatch source type. A value of zero has no effect
- * and will not result in the submission of the event handler block.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_source_merge_data(dispatch_source_t source, unsigned long value);
-
-/*!
- * @function dispatch_source_set_timer
- *
- * @abstract
- * Sets a start time, interval, and leeway value for a timer source.
- *
- * @discussion
- * Calling this function has no effect if the timer source has already been
- * canceled.
- *
- * The start time argument also determines which clock will be used for the
- * timer. If the start time is DISPATCH_TIME_NOW or created with
- * dispatch_time() then the timer is based on mach_absolute_time(). Otherwise,
- * if the start time of the timer is created with dispatch_walltime() then the
- * timer is based on gettimeofday(3).
- *
- * @param start
- * The start time of the timer. See dispatch_time() and dispatch_walltime()
- * for more information.
- *
- * @param interval
- * The nanosecond interval for the timer.
- *
- * @param leeway
- * A hint given to the system by the application for the amount of leeway, in
- * nanoseconds, that the system may defer the timer in order to align with other
- * system activity for improved system performance or power consumption. (For
- * example, an application might perform a periodic task every 5 minutes, with
- * a leeway of up to 30 seconds.) Note that some latency is to be expected for
- * all timers even when a leeway value of zero is specified.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
-void
-dispatch_source_set_timer(dispatch_source_t source,
- dispatch_time_t start,
- uint64_t interval,
- uint64_t leeway);
-
-__END_DECLS
-
-#endif
Deleted: trunk/src/time.h
===================================================================
--- trunk/src/time.h 2009-09-15 22:57:30 UTC (rev 35)
+++ trunk/src/time.h 2009-09-16 10:23:34 UTC (rev 36)
@@ -1,113 +0,0 @@
-/*
- * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
- *
- * @APPLE_APACHE_LICENSE_HEADER_START@
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * @APPLE_APACHE_LICENSE_HEADER_END@
- */
-
-#ifndef __DISPATCH_TIME__
-#define __DISPATCH_TIME__
-
-#ifndef __DISPATCH_INDIRECT__
-#error "Please #include <dispatch/dispatch.h> instead of this file directly."
-#include <dispatch/base.h> // for HeaderDoc
-#endif
-
-#include <stdint.h>
-
-__BEGIN_DECLS
-
-struct timespec;
-
-// 6368156
-#ifdef NSEC_PER_SEC
-#undef NSEC_PER_SEC
-#endif
-#ifdef USEC_PER_SEC
-#undef USEC_PER_SEC
-#endif
-#ifdef NSEC_PER_USEC
-#undef NSEC_PER_USEC
-#endif
-#define NSEC_PER_SEC 1000000000ull
-#define USEC_PER_SEC 1000000ull
-#define NSEC_PER_USEC 1000ull
-
-/*!
- * @typedef dispatch_time_t
- *
- * @abstract
- * An somewhat abstract representation of time; where zero means "now" and
- * DISPATCH_TIME_FOREVER means "infinity" and every value in between is an
- * opaque encoding.
- */
-typedef uint64_t dispatch_time_t;
-
-#define DISPATCH_TIME_NOW 0
-#define DISPATCH_TIME_FOREVER (~0ull)
-
-/*!
- * @function dispatch_time
- *
- * @abstract
- * Create dispatch_time_t relative to the default clock or modify an existing
- * dispatch_time_t.
- *
- * @discussion
- * On Mac OS X the default clock is based on mach_absolute_time().
- *
- * @param when
- * An optional dispatch_time_t to add nanoseconds to. If zero is passed, then
- * dispatch_time() will use the result of mach_absolute_time().
- *
- * @param delta
- * Nanoseconds to add.
- *
- * @result
- * A new dispatch_time_t.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW
-dispatch_time_t
-dispatch_time(dispatch_time_t when, int64_t delta);
-
-/*!
- * @function dispatch_walltime
- *
- * @abstract
- * Create a dispatch_time_t using the wall clock.
- *
- * @discussion
- * On Mac OS X the wall clock is based on gettimeofday(3).
- *
- * @param when
- * A struct timespect to add time to. If NULL is passed, then
- * dispatch_walltime() will use the result of gettimeofday(3).
- *
- * @param delta
- * Nanoseconds to add.
- *
- * @result
- * A new dispatch_time_t.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
-DISPATCH_NOTHROW
-dispatch_time_t
-dispatch_walltime(const struct timespec *when, int64_t delta);
-
-__END_DECLS
-
-#endif
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/libdispatch-changes/attachments/20090916/0fddaae5/attachment-0001.html>
More information about the libdispatch-changes
mailing list