semaphore: similar to thread_create(), semaphore_create() is used by Mach
[strongswan.git] / src / libstrongswan / threading / semaphore.h
1 /*
2 * Copyright (C) 2011 Tobias Brunner
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup semaphore semaphore
18 * @{ @ingroup threading
19 */
20
21 #ifndef THREADING_SEMAPHORE_H_
22 #define THREADING_SEMAPHORE_H_
23
24 #ifdef __APPLE__
25 /* Mach uses a semaphore_create() call, use a different name for ours */
26 #define semaphore_create(x) strongswan_semaphore_create(x)
27 #endif /* __APPLE__ */
28
29 typedef struct semaphore_t semaphore_t;
30
31 /**
32 * A semaphore is basically an integer whose value is never allowed to be
33 * lower than 0. Two operations can be performed on it: increment the
34 * value by one, and decrement the value by one. If the value is currently
35 * zero, then the decrement operation will blcok until the value becomes
36 * greater than zero.
37 */
38 struct semaphore_t {
39
40 /**
41 * Decrease the value by one, if it is greater than zero. Otherwise the
42 * current thread is blocked and it waits until the value increases.
43 */
44 void (*wait)(semaphore_t *this);
45
46 /**
47 * Decrease the value by one, if it is greater than zero. Otherwise the
48 * current thread is blocked and it waits until the value increases, or the
49 * call times out.
50 *
51 * @param timeout timeout im ms
52 * @return TRUE if timed out, FALSE otherwise
53 */
54 bool (*timed_wait)(semaphore_t *this, u_int timeout);
55
56 /**
57 * Decrease the value by one, if it is greater than zero. Otherwise the
58 * current thread is blocked and it waits until the value increases, or the
59 * call times out.
60 *
61 * The passed timeval should be calculated based on the time_monotonic()
62 * function.
63 *
64 * @param tv absolute time until timeout
65 * @return TRUE if timed out, FALSE otherwise
66 */
67 bool (*timed_wait_abs)(semaphore_t *this, timeval_t tv);
68
69 /**
70 * Increase the value by one. If the value becomes greater than zero, then
71 * another thread waiting will be woken up.
72 */
73 void (*post)(semaphore_t *this);
74
75 /**
76 * Destroy a semaphore and free its resources.
77 */
78 void (*destroy)(semaphore_t *this);
79 };
80
81 /**
82 * Create a semaphore instance.
83 *
84 * @param value initial value (typically 0)
85 * @return semaphore instance
86 */
87 semaphore_t *semaphore_create(u_int value);
88
89 #endif /** THREADING_SEMAPHORE_H_ @} */
90