dispatch/semaphore.h

   1 /*
   2  * Copyright (c) 2008-2013 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 #ifndef __DISPATCH_SEMAPHORE__
  22 #define __DISPATCH_SEMAPHORE__
  23
  24 #ifndef __DISPATCH_INDIRECT__
  25 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
  26 #include <dispatch/base.h> // for HeaderDoc
  27 #endif
  28
  29 DISPATCH_ASSUME_NONNULL_BEGIN
  30
  31 /*!
  32  * @typedef dispatch_semaphore_t
  33  *
  34  * @abstract
  35  * A counting semaphore.
  36  */
  37 DISPATCH_DECL(dispatch_semaphore);
  38
  39 __BEGIN_DECLS
  40
  41 /*!
  42  * @function dispatch_semaphore_create
  43  *
  44  * @abstract
  45  * Creates new counting semaphore with an initial value.
  46  *
  47  * @discussion
  48  * Passing zero for the value is useful for when two threads need to reconcile
  49  * the completion of a particular event. Passing a value greater than zero is
  50  * useful for managing a finite pool of resources, where the pool size is equal
  51  * to the value.
  52  *
  53  * @param value
  54  * The starting value for the semaphore. Passing a value less than zero will
  55  * cause NULL to be returned.
  56  *
  57  * @result
  58  * The newly created semaphore, or NULL on failure.
  59  */
  60 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  61 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
  62 DISPATCH_NOTHROW
  63 dispatch_semaphore_t
  64 dispatch_semaphore_create(long value);
  65
  66 /*!
  67  * @function dispatch_semaphore_wait
  68  *
  69  * @abstract
  70  * Wait (decrement) for a semaphore.
  71  *
  72  * @discussion
  73  * Decrement the counting semaphore. If the resulting value is less than zero,
  74  * this function waits for a signal to occur before returning.
  75  *
  76  * @param dsema
  77  * The semaphore. The result of passing NULL in this parameter is undefined.
  78  *
  79  * @param timeout
  80  * When to timeout (see dispatch_time). As a convenience, there are the
  81  * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
  82  *
  83  * @result
  84  * Returns zero on success, or non-zero if the timeout occurred.
  85  */
  86 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  87 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  88 long
  89 dispatch_semaphore_wait(dispatch_semaphore_t dsema, dispatch_time_t timeout);
  90
  91 /*!
  92  * @function dispatch_semaphore_signal
  93  *
  94  * @abstract
  95  * Signal (increment) a semaphore.
  96  *
  97  * @discussion
  98  * Increment the counting semaphore. If the previous value was less than zero,
  99  * this function wakes a waiting thread before returning.
 100  *
 101  * @param dsema The counting semaphore.
 102  * The result of passing NULL in this parameter is undefined.
 103  *
 104  * @result
 105  * This function returns non-zero if a thread is woken. Otherwise, zero is
 106  * returned.
 107  */
 108 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 109 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 110 long
 111 dispatch_semaphore_signal(dispatch_semaphore_t dsema);
 112
 113 __END_DECLS
 114
 115 DISPATCH_ASSUME_NONNULL_END
 116
 117 #endif /* __DISPATCH_SEMAPHORE__ */