Gitiles
Code Review Sign In
review.shift-gmbh.com / SHIFTPHONES / android_device_shift_otter / c3a1fe5f39716a4897f865b3cd569278c2313c5f / . / gps / utils / msg_q.h
blob: 108cac8d8e49c7e4c89937e26039f0f5e8522cf5 [file] [log] [blame]
Michael Bestas3a0209e2023-05-04 01:15:47 +0300[diff] [blame]1/* Copyright (c) 2011, The Linux Foundation. All rights reserved.
2 *
3 * Redistribution and use in source and binary forms, with or without
4 * modification, are permitted provided that the following conditions are
5 * met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above
9 * copyright notice, this list of conditions and the following
10 * disclaimer in the documentation and/or other materials provided
11 * with the distribution.
12 * * Neither the name of The Linux Foundation nor the names of its
13 * contributors may be used to endorse or promote products derived
14 * from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
20 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
23 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
25 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
26 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29#ifndef __MSG_Q_H__
30#define __MSG_Q_H__
31
32#ifdef __cplusplus
33extern "C" {
34#endif /* __cplusplus */
35
36#include <stdlib.h>
37
38/** Linked List Return Codes */
39typedef enum
40{
41 eMSG_Q_SUCCESS = 0,
42 /**< Request was successful. */
43 eMSG_Q_FAILURE_GENERAL = -1,
44 /**< Failed because of a general failure. */
45 eMSG_Q_INVALID_PARAMETER = -2,
46 /**< Failed because the request contained invalid parameters. */
47 eMSG_Q_INVALID_HANDLE = -3,
48 /**< Failed because an invalid handle was specified. */
49 eMSG_Q_UNAVAILABLE_RESOURCE = -4,
50 /**< Failed because an there were not enough resources. */
51 eMSG_Q_INSUFFICIENT_BUFFER = -5,
52 /**< Failed because an the supplied buffer was too small. */
Albert I15cb0c92021-06-26 04:21:58 +0800[diff] [blame]53 eMSG_Q_EMPTY = -6
54 /**< Failed because list is empty. */
Michael Bestas3a0209e2023-05-04 01:15:47 +0300[diff] [blame]55}msq_q_err_type;
56
57/*===========================================================================
58FUNCTION msg_q_init
59
60DESCRIPTION
61 Initializes internal structures for message queue.
62
63 msg_q_data: pointer to an opaque Q handle to be returned; NULL if fails
64
65DEPENDENCIES
66 N/A
67
68RETURN VALUE
69 Look at error codes above.
70
71SIDE EFFECTS
72 N/A
73
74===========================================================================*/
75msq_q_err_type msg_q_init(void** msg_q_data);
76
77/*===========================================================================
78FUNCTION msg_q_init2
79
80DESCRIPTION
81 Initializes internal structures for message queue.
82
83DEPENDENCIES
84 N/A
85
86RETURN VALUE
87 opaque handle to the Q created; NULL if create fails
88
89SIDE EFFECTS
90 N/A
91
92===========================================================================*/
93const void* msg_q_init2();
94
95/*===========================================================================
96FUNCTION msg_q_destroy
97
98DESCRIPTION
99 Releases internal structures for message queue.
100
101 msg_q_data: State of message queue to be released.
102
103DEPENDENCIES
104 N/A
105
106RETURN VALUE
107 Look at error codes above.
108
109SIDE EFFECTS
110 N/A
111
112===========================================================================*/
113msq_q_err_type msg_q_destroy(void** msg_q_data);
114
115/*===========================================================================
116FUNCTION msg_q_snd
117
118DESCRIPTION
119 Sends data to the message queue. The passed in data pointer
120 is not modified or freed. Passed in msg_obj is expected to live throughout
121 the use of the msg_q (i.e. data is not allocated internally)
122
123 msg_q_data: Message Queue to add the element to.
124 msgp: Pointer to data to add into message queue.
125 dealloc: Function used to deallocate memory for this element. Pass NULL
126 if you do not want data deallocated during a flush operation
127
128DEPENDENCIES
129 N/A
130
131RETURN VALUE
132 Look at error codes above.
133
134SIDE EFFECTS
135 N/A
136
137===========================================================================*/
138msq_q_err_type msg_q_snd(void* msg_q_data, void* msg_obj, void (*dealloc)(void*));
139
140/*===========================================================================
141FUNCTION msg_q_rcv
142
143DESCRIPTION
144 Retrieves data from the message queue. msg_obj is the oldest message received
145 and pointer is simply removed from message queue.
146
147 msg_q_data: Message Queue to copy data from into msgp.
148 msg_obj: Pointer to space to copy msg_q contents to.
149
150DEPENDENCIES
151 N/A
152
153RETURN VALUE
154 Look at error codes above.
155
156SIDE EFFECTS
157 N/A
158
159===========================================================================*/
160msq_q_err_type msg_q_rcv(void* msg_q_data, void** msg_obj);
161
162/*===========================================================================
163FUNCTION msg_q_rmv
164
165DESCRIPTION
166 Remove data from the message queue. msg_obj is the oldest message received
167 and pointer is simply removed from message queue.
168
169 msg_q_data: Message Queue to copy data from into msgp.
170 msg_obj: Pointer to space to copy msg_q contents to.
171
172DEPENDENCIES
173 N/A
174
175RETURN VALUE
176 Look at error codes above.
177
178SIDE EFFECTS
179 N/A
180
181===========================================================================*/
182msq_q_err_type msg_q_rmv(void* msg_q_data, void** msg_obj);
183
184
185/*===========================================================================
186FUNCTION msg_q_flush
187
188DESCRIPTION
189 Function removes all elements from the message queue.
190
191 msg_q_data: Message Queue to remove elements from.
192
193DEPENDENCIES
194 N/A
195
196RETURN VALUE
197 Look at error codes above.
198
199SIDE EFFECTS
200 N/A
201
202===========================================================================*/
203msq_q_err_type msg_q_flush(void* msg_q_data);
204
205/*===========================================================================
206FUNCTION msg_q_unblock
207
208DESCRIPTION
209 This function will stop use of the message queue. All waiters will wake up
210 and likely receive nothing from the queue resulting in a negative return
211 value. The message queue can no longer be used until it is destroyed
212 and initialized again after calling this function.
213
214 msg_q_data: Message queue to unblock.
215
216DEPENDENCIES
217 N/A
218
219RETURN VALUE
220 Look at error codes above.
221
222SIDE EFFECTS
223 N/A
224
225===========================================================================*/
226msq_q_err_type msg_q_unblock(void* msg_q_data);
227
228#ifdef __cplusplus
229}
230#endif /* __cplusplus */
231
232#endif /* __MSG_Q_H__ */