1 /*===========================================================================
2 *
3 *                            PUBLIC DOMAIN NOTICE
4 *               National Center for Biotechnology Information
5 *
6 *  This software/database is a "United States Government Work" under the
7 *  terms of the United States Copyright Act.  It was written as part of
8 *  the author's official duties as a United States Government employee and
9 *  thus cannot be copyrighted.  This software/database is freely available
10 *  to the public for use. The National Library of Medicine and the U.S.
11 *  Government have not placed any restriction on its use or reproduction.
12 *
13 *  Although all reasonable efforts have been taken to ensure the accuracy
14 *  and reliability of the software and data, the NLM and the U.S.
15 *  Government do not and cannot warrant the performance or results that
16 *  may be obtained by using this software or data. The NLM and the U.S.
17 *  Government disclaim all warranties, express or implied, including
18 *  warranties of performance, merchantability or fitness for any particular
19 *  purpose.
20 *
21 *  Please cite the author in any work or product based on this material.
22 *
23 * ===========================================================================
24 *
25 */
26 
27 #ifndef _h_kproc_cond_
28 #define _h_kproc_cond_
29 
30 #ifndef _h_kproc_extern_
31 #include <kproc/extern.h>
32 #endif
33 
34 #ifndef _h_klib_defs_
35 #include <klib/defs.h>
36 #endif
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 /*--------------------------------------------------------------------------
43  * forwards
44  */
45 struct KLock;
46 struct timeout_t;
47 
48 
49 /*--------------------------------------------------------------------------
50  * KCondition
51  *  a POSIX-style condition object
52  *  ( requires an external lock object )
53  *
54  *  usage: the user first acquires an external lock. then, depending upon
55  *  the operation, will either test for a condition or establish it, where
56  *  the former involves the potential to wait for a signal and the latter
57  *  to generate a signal using the external lock for blocking.
58  */
59 typedef struct KCondition KCondition;
60 
61 
62 /* Make
63  *  create a condition
64  */
65 KPROC_EXTERN rc_t CC KConditionMake ( KCondition **cond );
66 
67 
68 /* AddRef
69  * Release
70  */
71 KPROC_EXTERN rc_t CC KConditionAddRef ( const KCondition *self );
72 KPROC_EXTERN rc_t CC KConditionRelease ( const KCondition *self );
73 
74 
75 /* Wait
76  *  block on external lock until signalled
77  */
78 KPROC_EXTERN rc_t CC KConditionWait ( KCondition *self, struct KLock *lock );
79 KPROC_EXTERN rc_t CC KConditionTimedWait ( KCondition *self, struct KLock *lock, struct timeout_t *tm );
80 
81 
82 /* Signal
83  *  signal waiting threads
84  *  awaken at most a single thread
85  *
86  * NB - external lock used for synchronization must be locked by current thread
87  */
88 KPROC_EXTERN rc_t CC KConditionSignal ( KCondition *self );
89 
90 
91 /* Broadcast
92  *  signal waiting threads
93  *  awaken all waiting thread
94  *
95  * NB - external lock used for synchronization must be locked by current thread
96  */
97 KPROC_EXTERN rc_t CC KConditionBroadcast ( KCondition *self );
98 
99 #ifdef __cplusplus
100 }
101 #endif
102 
103 #endif /* _h_kproc_cond_ */
104