[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_mutex.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of mutex object.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_MUTEX_H_\r
44 #define _CL_MUTEX_H_\r
45 \r
46 \r
47 #include <complib/cl_mutex_osd.h>\r
48 \r
49 \r
50 /****h* complib/Mutex\r
51 * NAME\r
52 *       Mutex\r
53 *\r
54 * DESCRIPTION\r
55 *       Mutex provides synchronization between threads for exclusive access to\r
56 *       a resource.\r
57 *\r
58 *       The Mutex functions manipulate a cl_mutex_t structure which should\r
59 *       be treated as opaque and should be manipulated only through the provided\r
60 *       functions.\r
61 *\r
62 * SEE ALSO\r
63 *       Structures:\r
64 *               cl_mutex_t\r
65 *\r
66 *       Initialization:\r
67 *               cl_mutex_construct, cl_mutex_init, cl_mutex_destroy\r
68 *\r
69 *       Manipulation\r
70 *               cl_mutex_acquire, cl_mutex_release\r
71 *********/\r
72 \r
73 \r
74 #ifdef __cplusplus\r
75 extern "C"\r
76 {\r
77 #endif\r
78 \r
79 \r
80 /****f* Component Library: Mutex/cl_mutex_construct\r
81 * NAME\r
82 *       cl_mutex_construct\r
83 *\r
84 * DESCRIPTION\r
85 *       The cl_mutex_construct function initializes the state of a\r
86 *       mutex.\r
87 *\r
88 * SYNOPSIS\r
89 */\r
90 CL_EXPORT void CL_API\r
91 cl_mutex_construct(\r
92         IN      cl_mutex_t* const       p_mutex );\r
93 /*\r
94 * PARAMETERS\r
95 *       p_mutex\r
96 *               [in] Pointer to a mutex structure whose state to initialize.\r
97 *\r
98 * RETURN VALUE\r
99 *       This function does not return a value.\r
100 *\r
101 * NOTES\r
102 *       Allows calling cl_semphore_destroy without first calling\r
103 *       cl_mutex_init.\r
104 *\r
105 *       Calling cl_mutex_construct is a prerequisite to calling any other\r
106 *       mutex function except cl_mutex_init.\r
107 *\r
108 * SEE ALSO\r
109 *       Mutex, cl_semphore_init cl_mutex_destroy\r
110 *********/\r
111 \r
112 \r
113 /****f* Component Library: Mutex/cl_mutex_init\r
114 * NAME\r
115 *       cl_mutex_init\r
116 *\r
117 * DESCRIPTION\r
118 *       The cl_mutex_init function initializes a mutex for use.\r
119 *\r
120 * SYNOPSIS\r
121 */\r
122 CL_EXPORT cl_status_t CL_API\r
123 cl_mutex_init(\r
124         IN      cl_mutex_t* const       p_mutex );\r
125 /*\r
126 * PARAMETERS\r
127 *       p_mutex\r
128 *               [in] Pointer to a mutex structure to initialize.\r
129 *\r
130 * RETURN VALUES\r
131 *       CL_SUCCESS if initialization succeeded.\r
132 *\r
133 *       CL_ERROR if initialization failed. Callers should call\r
134 *       cl_mutex_destroy to clean up any resources allocated during\r
135 *       initialization.\r
136 *\r
137 * NOTES\r
138 *       Initializes the mutex structure. Allows calling cl_mutex_aquire\r
139 *       and cl_mutex_release. The cl_mutex is always created in the unlocked state.\r
140 *\r
141 * SEE ALSO\r
142 *       Mutex, cl_mutex_construct, cl_mutex_destroy,\r
143 *       cl_mutex_acquire, cl_mutex_release\r
144 *********/\r
145 \r
146 \r
147 /****f* Component Library: Mutex/cl_mutex_destroy\r
148 * NAME\r
149 *       cl_mutex_destroy\r
150 *\r
151 * DESCRIPTION\r
152 *       The cl_mutex_destroy function performs all necessary cleanup of a\r
153 *       mutex.\r
154 *\r
155 * SYNOPSIS\r
156 */\r
157 CL_EXPORT void CL_API\r
158 cl_mutex_destroy(\r
159         IN      cl_mutex_t* const       p_mutex );\r
160 /*\r
161 * PARAMETERS\r
162 *       p_mutex\r
163 *               [in] Pointer to a mutex structure to destroy.\r
164 *\r
165 * RETURN VALUE\r
166 *       This function does not return a value.\r
167 *\r
168 * NOTES\r
169 *       Performs any necessary cleanup of a mutex. This function must only\r
170 *       be called if either cl_mutex_construct or cl_mutex_init has been\r
171 *       called.\r
172 *\r
173 * SEE ALSO\r
174 *       Mutex, cl_mutex_construct, cl_mutex_init\r
175 *********/\r
176 \r
177 \r
178 /****f* Component Library: Mutex/cl_mutex_acquire\r
179 * NAME\r
180 *       cl_mutex_acquire\r
181 *\r
182 * DESCRIPTION\r
183 *       The cl_mutex_acquire function acquires a mutex.\r
184 *\r
185 * SYNOPSIS\r
186 */\r
187 CL_EXPORT void CL_API\r
188 cl_mutex_acquire(\r
189         IN      cl_mutex_t* const       p_mutex );\r
190 /*\r
191 * PARAMETERS\r
192 *       p_mutex\r
193 *               [in] Pointer to a mutex structure to acquire.\r
194 *\r
195 * RETURN VALUE\r
196 *       This function does not return a value.\r
197 *\r
198 * SEE ALSO\r
199 *       Mutex, cl_mutex_release\r
200 *********/\r
201 \r
202 \r
203 /****f* Component Library: Mutex/cl_mutex_release\r
204 * NAME\r
205 *       cl_mutex_release\r
206 *\r
207 * DESCRIPTION\r
208 *       The cl_mutex_release function releases a mutex object.\r
209 *\r
210 * SYNOPSIS\r
211 */\r
212 CL_EXPORT void CL_API\r
213 cl_mutex_release(\r
214         IN      cl_mutex_t* const       p_mutex );\r
215 /*\r
216 * PARAMETERS\r
217 *       p_mutex\r
218 *               [in] Pointer to a mutex structure to release.\r
219 *\r
220 * RETURN VALUE\r
221 *       This function does not return a value.\r
222 *\r
223 * NOTES\r
224 *       Releases a mutex after a call to cl_mutex_acquire.\r
225 *\r
226 * SEE ALSO\r
227 *       Mutex, cl_mutex_acquire\r
228 *********/\r
229 \r
230 \r
231 #ifdef __cplusplus\r
232 }       /* extern "C" */\r
233 #endif\r
234 \r
235 #endif /* _CL_MUTEX_H_ */\r