1 /*
2  * Copyright (C) 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*
18  * Implementation Notes
19  * Each platform must supply a platform-specific platform_condition_variable.h
20  * to provide definitions and a platform-specific condition_variable.c to
21  * provide the implementation for the definitions in this file.
22  */
23 
24 #ifndef CHPP_CONDITION_VARIABLE_H_
25 #define CHPP_CONDITION_VARIABLE_H_
26 
27 #include <inttypes.h>
28 #include <stdbool.h>
29 
30 #include "chpp/mutex.h"
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 /*
37  * Platform-specific condition variable struct defined in the platform's
38  * platform_condition_variable.h that enables the funcions defined here.
39  */
40 struct ChppConditionVariable;
41 
42 /**
43  * Initializes the platform-specific ChppConditionVariable.
44  */
45 static void chppConditionVariableInit(struct ChppConditionVariable *cv);
46 
47 /**
48  * Deinitializes the platform-specific ChppConditionVariable.
49  */
50 static void chppConditionVariableDeinit(struct ChppConditionVariable *cv);
51 
52 /**
53  * Waits until signaled through chppConditionVariableSignal(). Only one entity
54  * may be waiting on a condition variable at one time.
55  *
56  * It is expected that the provided mutex is locked before the function is
57  * invoked, and otherwise results in undefined behavior.
58  *
59  * @param cv The pointer to the condition variable.
60  * @param mutex The mutex to use with this condition variable.
61  *
62  * @return True if the wait succeeded.
63  */
64 static bool chppConditionVariableWait(struct ChppConditionVariable *cv,
65                                       struct ChppMutex *mutex);
66 
67 /**
68  * Same as chppConditionVariableWait(), but with a specified timeout.
69  *
70  * @param cv The pointer to the condition variable.
71  * @param mutex The mutex to use with this condition variable.
72  * @param timeoutNs The timeout in nanoseconds.
73  *
74  * @return True if the wait succeeded.
75  */
76 static bool chppConditionVariableTimedWait(struct ChppConditionVariable *cv,
77                                            struct ChppMutex *mutex,
78                                            uint64_t timeoutNs);
79 
80 /**
81  * Signals on an entity waiting on the condition variable through
82  * chppConditionVariableWait().
83  *
84  * @param cv The pointer to the condition variable.
85  */
86 static void chppConditionVariableSignal(struct ChppConditionVariable *cv);
87 
88 #ifdef __cplusplus
89 }
90 #endif
91 
92 #include "chpp/platform/platform_condition_variable.h"
93 
94 #endif  // CHPP_CONDITION_VARIABLE_H_
95