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
 29DISPATCH_ASSUME_NONNULL_BEGIN
 30DISPATCH_ASSUME_ABI_SINGLE_BEGIN
 31
 32/*!
 33 * @typedef dispatch_semaphore_t
 34 *
 35 * @abstract
 36 * A counting semaphore.
 37 */
 38DISPATCH_DECL_SWIFT(dispatch_semaphore, DispatchSemaphore);
 39
 40__BEGIN_DECLS
 41
 42/*!
 43 * @function dispatch_semaphore_create
 44 *
 45 * @abstract
 46 * Creates new counting semaphore with an initial value.
 47 *
 48 * @discussion
 49 * Passing zero for the value is useful for when two threads need to reconcile
 50 * the completion of a particular event. Passing a value greater than zero is
 51 * useful for managing a finite pool of resources, where the pool size is equal
 52 * to the value.
 53 *
 54 * @param value
 55 * The starting value for the semaphore. Passing a value less than zero will
 56 * cause NULL to be returned.
 57 *
 58 * @result
 59 * The newly created semaphore, or NULL on failure.
 60 */
 61API_AVAILABLE(macos(10.6), ios(4.0))
 62DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 63DISPATCH_NOTHROW
 64DISPATCH_SWIFT_NAME(DispatchSemaphore.init(value:))
 65dispatch_semaphore_t
 66dispatch_semaphore_create(intptr_t value);
 67
 68/*!
 69 * @function dispatch_semaphore_wait
 70 *
 71 * @abstract
 72 * Wait (decrement) for a semaphore.
 73 *
 74 * @discussion
 75 * Decrement the counting semaphore. If the resulting value is less than zero,
 76 * this function waits for a signal to occur before returning. If the timeout is
 77 * reached without a signal being received, the semaphore is re-incremented
 78 * before the function returns.
 79 *
 80 * @param dsema
 81 * The semaphore. The result of passing NULL in this parameter is undefined.
 82 *
 83 * @param timeout
 84 * When to timeout (see dispatch_time). As a convenience, there are the
 85 * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
 86 *
 87 * @result
 88 * Returns zero on success, or non-zero if the timeout occurred.
 89 */
 90API_AVAILABLE(macos(10.6), ios(4.0))
 91DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 92DISPATCH_REFINED_FOR_SWIFT
 93intptr_t
 94dispatch_semaphore_wait(dispatch_semaphore_t dsema, dispatch_time_t timeout);
 95
 96/*!
 97 * @function dispatch_semaphore_signal
 98 *
 99 * @abstract
100 * Signal (increment) a semaphore.
101 *
102 * @discussion
103 * Increment the counting semaphore. If the previous value was less than zero,
104 * this function wakes a waiting thread before returning.
105 *
106 * @param dsema The counting semaphore.
107 * The result of passing NULL in this parameter is undefined.
108 *
109 * @result
110 * This function returns non-zero if a thread is woken. Otherwise, zero is
111 * returned.
112 */
113API_AVAILABLE(macos(10.6), ios(4.0))
114DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
115DISPATCH_REFINED_FOR_SWIFT
116intptr_t
117dispatch_semaphore_signal(dispatch_semaphore_t dsema);
118
119__END_DECLS
120
121DISPATCH_ASSUME_ABI_SINGLE_END
122DISPATCH_ASSUME_NONNULL_END
123
124#endif /* __DISPATCH_SEMAPHORE__ */