cdb0a6f191bc5fd93d2826db3df060c41fe4d56c
[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 typedef struct semaphore_t semaphore_t;
25
26 /**
27 * A semaphore is basically an integer whose value is never allowed to be
28 * lower than 0. Two operations can be performed on it: increment the
29 * value by one, and decrement the value by one. If the value is currently
30 * zero, then the decrement operation will blcok until the value becomes
31 * greater than zero.
32 */
33 struct semaphore_t {
34
35 /**
36 * Decrease the value by one, if it is greater than zero. Otherwise the
37 * current thread is blocked and it waits until the value increases.
38 */
39 void (*wait)(semaphore_t *this);
40
41 /**
42 * Decrease the value by one, if it is greater than zero. Otherwise the
43 * current thread is blocked and it waits until the value increases, or the
44 * call times out.
45 *
46 * @param timeout timeout im ms
47 * @return TRUE if timed out, FALSE otherwise
48 */
49 bool (*timed_wait)(semaphore_t *this, u_int timeout);
50
51 /**
52 * Decrease the value by one, if it is greater than zero. Otherwise the
53 * current thread is blocked and it waits until the value increases, or the
54 * call times out.
55 *
56 * The passed timeval should be calculated based on the time_monotonic()
57 * function.
58 *
59 * @param tv absolute time until timeout
60 * @return TRUE if timed out, FALSE otherwise
61 */
62 bool (*timed_wait_abs)(semaphore_t *this, timeval_t tv);
63
64 /**
65 * Increase the value by one. If the value becomes greater than zero, then
66 * another thread waiting will be woken up.
67 */
68 void (*post)(semaphore_t *this);
69
70 /**
71 * Destroy a semaphore and free its resources.
72 */
73 void (*destroy)(semaphore_t *this);
74 };
75
76 /**
77 * Create a semaphore instance.
78 *
79 * @param value initial value (typically 0)
80 * @return semaphore instance
81 */
82 semaphore_t *semaphore_create(u_int value);
83
84 #endif /** THREADING_SEMAPHORE_H_ @} */
85