1/******************************************************************************
2 *
3 *  Copyright (C) 2014 Google, Inc.
4 *
5 *  Licensed under the Apache License, Version 2.0 (the "License");
6 *  you may not use this file except in compliance with the License.
7 *  You may obtain a copy of the License at:
8 *
9 *  http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 *
17 ******************************************************************************/
18
19#pragma once
20
21#include <stdbool.h>
22
23struct semaphore_t;
24typedef struct semaphore_t semaphore_t;
25
26// Creates a new semaphore with an initial value of |value|.
27// Returns NULL on failure. The returned object must be released
28// with |semaphore_free|.
29semaphore_t *semaphore_new(unsigned int value);
30
31// Frees a semaphore allocated with |semaphore_new|. |semaphore| may
32// be NULL.
33void semaphore_free(semaphore_t *semaphore);
34
35// Decrements the value of |semaphore|. If it is 0, this call blocks until
36// it becomes non-zero. |semaphore| may not be NULL.
37void semaphore_wait(semaphore_t *semaphore);
38
39// Tries to decrement the value of |semaphore|. Returns true if the value was
40// decremented, false if the value was 0. This function never blocks. |semaphore|
41// may not be NULL.
42bool semaphore_try_wait(semaphore_t *semaphore);
43
44// Increments the value of |semaphore|. |semaphore| may not be NULL.
45void semaphore_post(semaphore_t *semaphore);
46
47// Returns a file descriptor representing this semaphore. The caller may
48// only perform one operation on the file descriptor: select(2). If |select|
49// indicates the fd is readable, the caller may call |semaphore_wait|
50// without blocking. If select indicates the fd is writable, the caller may
51// call |semaphore_post| without blocking. Note that there may be a race
52// condition between calling |select| and |semaphore_wait| or |semaphore_post|
53// which results in blocking behaviour.
54//
55// The caller must not close the returned file descriptor. |semaphore| may not
56// be NULL.
57int semaphore_get_fd(const semaphore_t *semaphore);
58