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 
23 struct semaphore_t;
24 typedef 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|.
29 semaphore_t *semaphore_new(unsigned int value);
30 
31 // Frees a semaphore allocated with |semaphore_new|. |semaphore| may
32 // be NULL.
33 void 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.
37 void 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.
42 bool semaphore_try_wait(semaphore_t *semaphore);
43 
44 // Increments the value of |semaphore|. |semaphore| may not be NULL.
45 void 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.
57 int semaphore_get_fd(const semaphore_t *semaphore);
58