1/*
2 * Copyright © 2008 Kristian Høgsberg
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice (including the
13 * next paragraph) shall be included in all copies or substantial
14 * portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
20 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23 * SOFTWARE.
24 */
25
26/** \file wayland-util.h
27 *
28 * \brief Utility classes, functions, and macros.
29 */
30
31#ifndef WAYLAND_UTIL_H
32#define WAYLAND_UTIL_H
33
34#include <math.h>
35#include <stddef.h>
36#include <inttypes.h>
37#include <stdarg.h>
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/* GCC visibility */
44#if defined(__GNUC__) && __GNUC__ >= 4
45#define WL_EXPORT __attribute__ ((visibility("default")))
46#else
47#define WL_EXPORT
48#endif
49
50/* Deprecated attribute */
51#if defined(__GNUC__) && __GNUC__ >= 4
52#define WL_DEPRECATED __attribute__ ((deprecated))
53#else
54#define WL_DEPRECATED
55#endif
56
57/* Printf annotation */
58#if defined(__GNUC__) && __GNUC__ >= 4
59#define WL_PRINTF(x, y) __attribute__((__format__(__printf__, x, y)))
60#else
61#define WL_PRINTF(x, y)
62#endif
63
64struct wl_message {
65 const char *name;
66 const char *signature;
67 const struct wl_interface **types;
68};
69
70struct wl_interface {
71 const char *name;
72 int version;
73 int method_count;
74 const struct wl_message *methods;
75 int event_count;
76 const struct wl_message *events;
77};
78
79/** \class wl_list
80 *
81 * \brief doubly-linked list
82 *
83 * The list head is of "struct wl_list" type, and must be initialized
84 * using wl_list_init(). All entries in the list must be of the same
85 * type. The item type must have a "struct wl_list" member. This
86 * member will be initialized by wl_list_insert(). There is no need to
87 * call wl_list_init() on the individual item. To query if the list is
88 * empty in O(1), use wl_list_empty().
89 *
90 * Let's call the list reference "struct wl_list foo_list", the item type as
91 * "item_t", and the item member as "struct wl_list link".
92 *
93 * The following code will initialize a list:
94 * \code
95 * struct wl_list foo_list;
96 *
97 * struct item_t {
98 * int foo;
99 * struct wl_list link;
100 * };
101 * struct item_t item1, item2, item3;
102 *
103 * wl_list_init(&foo_list);
104 * wl_list_insert(&foo_list, &item1.link); // Pushes item1 at the head
105 * wl_list_insert(&foo_list, &item2.link); // Pushes item2 at the head
106 * wl_list_insert(&item2.link, &item3.link); // Pushes item3 after item2
107 * \endcode
108 *
109 * The list now looks like [item2, item3, item1]
110 *
111 * Iterate the list in ascending order:
112 * \code
113 * item_t *item;
114 * wl_list_for_each(item, foo_list, link) {
115 * Do_something_with_item(item);
116 * }
117 * \endcode
118 */
119struct wl_list {
120 struct wl_list *prev;
121 struct wl_list *next;
122};
123
124void
125wl_list_init(struct wl_list *list);
126
127void
128wl_list_insert(struct wl_list *list, struct wl_list *elm);
129
130void
131wl_list_remove(struct wl_list *elm);
132
133int
134wl_list_length(const struct wl_list *list);
135
136int
137wl_list_empty(const struct wl_list *list);
138
139void
140wl_list_insert_list(struct wl_list *list, struct wl_list *other);
141
142/**
143 * Retrieves a pointer to the containing struct of a given member item.
144 *
145 * This macro allows conversion from a pointer to a item to its containing
146 * struct. This is useful if you have a contained item like a wl_list,
147 * wl_listener, or wl_signal, provided via a callback or other means and would
148 * like to retrieve the struct that contains it.
149 *
150 * To demonstrate, the following example retrieves a pointer to
151 * `example_container` given only its `destroy_listener` member:
152 *
153 * \code
154 * struct example_container {
155 * struct wl_listener destroy_listener;
156 * // other members...
157 * };
158 *
159 * void example_container_destroy(struct wl_listener *listener, void *data)
160 * {
161 * struct example_container *ctr;
162 *
163 * ctr = wl_container_of(listener, ctr, destroy_listener);
164 * // destroy ctr...
165 * }
166 * \endcode
167 *
168 * \param ptr A valid pointer to the contained item.
169 *
170 * \param sample A pointer to the type of content that the list item
171 * stores. Sample does not need be a valid pointer; a null or
172 * an uninitialised pointer will suffice.
173 *
174 * \param member The named location of ptr within the sample type.
175 *
176 * \return The container for the specified pointer.
177 */
178#define wl_container_of(ptr, sample, member) \
179 (__typeof__(sample))((char *)(ptr) - \
180 offsetof(__typeof__(*sample), member))
181/* If the above macro causes problems on your compiler you might be
182 * able to find an alternative name for the non-standard __typeof__
183 * operator and add a special case here */
184
185#define wl_list_for_each(pos, head, member) \
186 for (pos = wl_container_of((head)->next, pos, member); \
187 &pos->member != (head); \
188 pos = wl_container_of(pos->member.next, pos, member))
189
190#define wl_list_for_each_safe(pos, tmp, head, member) \
191 for (pos = wl_container_of((head)->next, pos, member), \
192 tmp = wl_container_of((pos)->member.next, tmp, member); \
193 &pos->member != (head); \
194 pos = tmp, \
195 tmp = wl_container_of(pos->member.next, tmp, member))
196
197#define wl_list_for_each_reverse(pos, head, member) \
198 for (pos = wl_container_of((head)->prev, pos, member); \
199 &pos->member != (head); \
200 pos = wl_container_of(pos->member.prev, pos, member))
201
202#define wl_list_for_each_reverse_safe(pos, tmp, head, member) \
203 for (pos = wl_container_of((head)->prev, pos, member), \
204 tmp = wl_container_of((pos)->member.prev, tmp, member); \
205 &pos->member != (head); \
206 pos = tmp, \
207 tmp = wl_container_of(pos->member.prev, tmp, member))
208
209struct wl_array {
210 size_t size;
211 size_t alloc;
212 void *data;
213};
214
215#define wl_array_for_each(pos, array) \
216 for (pos = (array)->data; \
217 (const char *) pos < ((const char *) (array)->data + (array)->size); \
218 (pos)++)
219
220void
221wl_array_init(struct wl_array *array);
222
223void
224wl_array_release(struct wl_array *array);
225
226void *
227wl_array_add(struct wl_array *array, size_t size);
228
229int
230wl_array_copy(struct wl_array *array, struct wl_array *source);
231
232typedef int32_t wl_fixed_t;
233
234static inline double
235wl_fixed_to_double (wl_fixed_t f)
236{
237 union {
238 double d;
239 int64_t i;
240 } u;
241
242 u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
243
244 return u.d - (3LL << 43);
245}
246
247static inline wl_fixed_t
248wl_fixed_from_double(double d)
249{
250 union {
251 double d;
252 int64_t i;
253 } u;
254
255 u.d = d + (3LL << (51 - 8));
256
257 return u.i;
258}
259
260static inline int
261wl_fixed_to_int(wl_fixed_t f)
262{
263 return f / 256;
264}
265
266static inline wl_fixed_t
267wl_fixed_from_int(int i)
268{
269 return i * 256;
270}
271
272/**
273 * \brief A union representing all of the basic data types that can be passed
274 * along the wayland wire format.
275 *
276 * This union represents all of the basic data types that can be passed in the
277 * wayland wire format. It is used by dispatchers and runtime-friendly
278 * versions of the event and request marshaling functions.
279 */
280union wl_argument {
281 int32_t i; /**< signed integer */
282 uint32_t u; /**< unsigned integer */
283 wl_fixed_t f; /**< fixed point */
284 const char *s; /**< string */
285 struct wl_object *o; /**< object */
286 uint32_t n; /**< new_id */
287 struct wl_array *a; /**< array */
288 int32_t h; /**< file descriptor */
289};
290
291/**
292 * \brief A function pointer type for a dispatcher.
293 *
294 * A dispatcher is a function that handles the emitting of callbacks in client
295 * code. For programs directly using the C library, this is done by using
296 * libffi to call function pointers. When binding to languages other than C,
297 * dispatchers provide a way to abstract the function calling process to be
298 * friendlier to other function calling systems.
299 *
300 * A dispatcher takes five arguments: The first is the dispatcher-specific
301 * implementation data associated with the target object. The second is the
302 * object on which the callback is being invoked (either wl_proxy or
303 * wl_resource). The third and fourth arguments are the opcode the wl_message
304 * structure corresponding to the callback being emitted. The final argument
305 * is an array of arguments received from the other process via the wire
306 * protocol.
307 */
308typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t,
309 const struct wl_message *,
310 union wl_argument *);
311
312typedef void (*wl_log_func_t)(const char *, va_list) WL_PRINTF(1, 0);
313
314#ifdef __cplusplus
315}
316#endif
317
318#endif
319