1	/*
2	* Copyright © 2008-2012 Kristian Høgsberg
3	* Copyright © 2010-2012 Intel Corporation
4	*
5	* Permission is hereby granted, free of charge, to any person obtaining
6	* a copy of this software and associated documentation files (the
7	* "Software"), to deal in the Software without restriction, including
8	* without limitation the rights to use, copy, modify, merge, publish,
9	* distribute, sublicense, and/or sell copies of the Software, and to
10	* permit persons to whom the Software is furnished to do so, subject to
11	* the following conditions:
12	*
13	* The above copyright notice and this permission notice (including the
14	* next paragraph) shall be included in all copies or substantial
15	* portions of the Software.
16	*
17	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18	* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19	* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20	* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
21	* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
22	* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
23	* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24	* SOFTWARE.
25	*/
26
27	#define _GNU_SOURCE
28
29	#include <stdlib.h>
30	#include <stdint.h>
31	#include <stddef.h>
32	#include <stdio.h>
33	#include <stdbool.h>
34	#include <errno.h>
35	#include <string.h>
36	#include <unistd.h>
37	#include <sys/socket.h>
38	#include <sys/un.h>
39	#include <ctype.h>
40	#include <assert.h>
41	#include <fcntl.h>
42	#include <poll.h>
43	#include <pthread.h>
44
45	#include "wayland-util.h"
46	#include "wayland-os.h"
47	#include "wayland-client.h"
48	#include "wayland-private.h"
49
50	/** \cond */
51
52	enum wl_proxy_flag {
53	WL_PROXY_FLAG_ID_DELETED = (1 << 0),
54	WL_PROXY_FLAG_DESTROYED = (1 << 1),
55	WL_PROXY_FLAG_WRAPPER = (1 << 2),
56	};
57
58	struct wl_zombie {
59	int event_count;
60	int *fd_count;
61	};
62
63	struct wl_proxy {
64	struct wl_object object;
65	struct wl_display *display;
66	struct wl_event_queue *queue;
67	uint32_t flags;
68	int refcount;
69	void *user_data;
70	wl_dispatcher_func_t dispatcher;
71	uint32_t version;
72	const char * const *tag;
73	};
74
75	struct wl_event_queue {
76	struct wl_list event_list;
77	struct wl_display *display;
78	};
79
80	struct wl_display {
81	struct wl_proxy proxy;
82	struct wl_connection *connection;
83
84	/* errno of the last wl_display error */
85	int last_error;
86
87	/* When display gets an error event from some object, it stores
88	* information about it here, so that client can get this
89	* information afterwards */
90	struct {
91	/* Code of the error. It can be compared to
92	* the interface's errors enumeration. */
93	uint32_t code;
94	/* interface (protocol) in which the error occurred */
95	const struct wl_interface *interface;
96	/* id of the proxy that caused the error. There's no warranty
97	* that the proxy is still valid. It's up to client how it will
98	* use it */
99	uint32_t id;
100	} protocol_error;
101	int fd;
102	struct wl_map objects;
103	struct wl_event_queue display_queue;
104	struct wl_event_queue default_queue;
105	pthread_mutex_t mutex;
106
107	int reader_count;
108	uint32_t read_serial;
109	pthread_cond_t reader_cond;
110	};
111
112	/** \endcond */
113
114	static int debug_client = 0;
115
116	/**
117	* This helper function wakes up all threads that are
118	* waiting for display->reader_cond (i. e. when reading is done,
119	* canceled, or an error occurred)
120	*
121	* NOTE: must be called with display->mutex locked
122	*/
123	static void
124	display_wakeup_threads(struct wl_display *display)
125	{
126	/* Thread can get sleeping only in read_events(). If we're
127	* waking it up, it means that the read completed or was
128	* canceled, so we must increase the read_serial.
129	* This prevents from indefinite sleeping in read_events().
130	*/
131	++display->read_serial;
132
133	pthread_cond_broadcast(cond: &display->reader_cond);
134	}
135
136	/**
137	* This function is called for local errors (no memory, server hung up)
138	*
139	* \param display
140	* \param error error value (EINVAL, EFAULT, ...)
141	*
142	* \note this function is called with display mutex locked
143	*/
144	static void
145	display_fatal_error(struct wl_display *display, int error)
146	{
147	if (display->last_error)
148	return;
149
150	if (!error)
151	error = EFAULT;
152
153	display->last_error = error;
154
155	display_wakeup_threads(display);
156	}
157
158	/**
159	* This function is called for error events
160	* and indicates that in some object an error occurred.
161	* The difference between this function and display_fatal_error()
162	* is that this one handles errors that will come by wire,
163	* whereas display_fatal_error() is called for local errors.
164	*
165	* \param display
166	* \param code error code
167	* \param id id of the object that generated the error
168	* \param intf protocol interface
169	*/
170	static void
171	display_protocol_error(struct wl_display *display, uint32_t code,
172	uint32_t id, const struct wl_interface *intf)
173	{
174	int err;
175
176	if (display->last_error)
177	return;
178
179	/* set correct errno */
180	if (intf && wl_interface_equal(iface1: intf, iface2: &wl_display_interface)) {
181	switch (code) {
182	case WL_DISPLAY_ERROR_INVALID_OBJECT:
183	case WL_DISPLAY_ERROR_INVALID_METHOD:
184	err = EINVAL;
185	break;
186	case WL_DISPLAY_ERROR_NO_MEMORY:
187	err = ENOMEM;
188	break;
189	case WL_DISPLAY_ERROR_IMPLEMENTATION:
190	err = EPROTO;
191	break;
192	default:
193	err = EFAULT;
194	}
195	} else {
196	err = EPROTO;
197	}
198
199	pthread_mutex_lock(mutex: &display->mutex);
200
201	display->last_error = err;
202
203	display->protocol_error.code = code;
204	display->protocol_error.id = id;
205	display->protocol_error.interface = intf;
206
207	/*
208	* here it is not necessary to wake up threads like in
209	* display_fatal_error, because this function is called from
210	* an event handler and that means that read_events() is done
211	* and woke up all threads. Since wl_display_prepare_read()
212	* fails when there are events in the queue, no threads
213	* can sleep in read_events() during dispatching
214	* (and therefore during calling this function), so this is safe.
215	*/
216
217	pthread_mutex_unlock(mutex: &display->mutex);
218	}
219
220	static void
221	wl_event_queue_init(struct wl_event_queue *queue, struct wl_display *display)
222	{
223	wl_list_init(list: &queue->event_list);
224	queue->display = display;
225	}
226
227	static void
228	wl_proxy_unref(struct wl_proxy *proxy)
229	{
230	assert(proxy->refcount > 0);
231	if (--proxy->refcount > 0)
232	return;
233
234	/* If we get here, the client must have explicitly requested
235	* deletion. */
236	assert(proxy->flags & WL_PROXY_FLAG_DESTROYED);
237	free(ptr: proxy);
238	}
239
240	static void
241	validate_closure_objects(struct wl_closure *closure)
242	{
243	const char *signature;
244	struct argument_details arg;
245	int i, count;
246	struct wl_proxy *proxy;
247
248	signature = closure->message->signature;
249	count = arg_count_for_signature(signature);
250	for (i = 0; i < count; i++) {
251	signature = get_next_argument(signature, details: &arg);
252	switch (arg.type) {
253	case 'n':
254	case 'o':
255	proxy = (struct wl_proxy *) closure->args[i].o;
256	if (proxy && proxy->flags & WL_PROXY_FLAG_DESTROYED)
257	closure->args[i].o = NULL;
258	break;
259	default:
260	break;
261	}
262	}
263	}
264
265	/* Destroys a closure which was demarshaled for dispatch; unrefs all the
266	* proxies in its arguments, as well as its own proxy, and destroys the
267	* closure itself. */
268	static void
269	destroy_queued_closure(struct wl_closure *closure)
270	{
271	const char *signature;
272	struct argument_details arg;
273	struct wl_proxy *proxy;
274	int i, count;
275
276	signature = closure->message->signature;
277	count = arg_count_for_signature(signature);
278	for (i = 0; i < count; i++) {
279	signature = get_next_argument(signature, details: &arg);
280	switch (arg.type) {
281	case 'n':
282	case 'o':
283	proxy = (struct wl_proxy *) closure->args[i].o;
284	if (proxy)
285	wl_proxy_unref(proxy);
286	break;
287	default:
288	break;
289	}
290	}
291
292	wl_proxy_unref(proxy: closure->proxy);
293	wl_closure_destroy(closure);
294	}
295
296	static void
297	wl_event_queue_release(struct wl_event_queue *queue)
298	{
299	struct wl_closure *closure;
300
301	while (!wl_list_empty(list: &queue->event_list)) {
302	closure = wl_container_of(queue->event_list.next,
303	closure, link);
304	wl_list_remove(elm: &closure->link);
305	destroy_queued_closure(closure);
306	}
307	}
308
309	/** Destroy an event queue
310	*
311	* \param queue The event queue to be destroyed
312	*
313	* Destroy the given event queue. Any pending event on that queue is
314	* discarded.
315	*
316	* The \ref wl_display object used to create the queue should not be
317	* destroyed until all event queues created with it are destroyed with
318	* this function.
319	*
320	* \memberof wl_event_queue
321	*/
322	WL_EXPORT void
323	wl_event_queue_destroy(struct wl_event_queue *queue)
324	{
325	struct wl_display *display = queue->display;
326
327	pthread_mutex_lock(mutex: &display->mutex);
328	wl_event_queue_release(queue);
329	free(ptr: queue);
330	pthread_mutex_unlock(mutex: &display->mutex);
331	}
332
333	/** Create a new event queue for this display
334	*
335	* \param display The display context object
336	* \return A new event queue associated with this display or NULL on
337	* failure.
338	*
339	* \memberof wl_display
340	*/
341	WL_EXPORT struct wl_event_queue *
342	wl_display_create_queue(struct wl_display *display)
343	{
344	struct wl_event_queue *queue;
345
346	queue = malloc(size: sizeof *queue);
347	if (queue == NULL)
348	return NULL;
349
350	wl_event_queue_init(queue, display);
351
352	return queue;
353	}
354
355	static int
356	message_count_fds(const char *signature)
357	{
358	unsigned int count, i, fds = 0;
359	struct argument_details arg;
360
361	count = arg_count_for_signature(signature);
362	for (i = 0; i < count; i++) {
363	signature = get_next_argument(signature, details: &arg);
364	if (arg.type == 'h')
365	fds++;
366	}
367
368	return fds;
369	}
370
371	static struct wl_zombie *
372	prepare_zombie(struct wl_proxy *proxy)
373	{
374	const struct wl_interface *interface = proxy->object.interface;
375	const struct wl_message *message;
376	int i, count;
377	struct wl_zombie *zombie = NULL;
378
379	/* If we hit an event with an FD, ensure we have a zombie object and
380	* fill the fd_count slot for that event with the number of FDs for
381	* that event. Interfaces with no events containing FDs will not have
382	* zombie objects created. */
383	for (i = 0; i < interface->event_count; i++) {
384	message = &interface->events[i];
385	count = message_count_fds(signature: message->signature);
386
387	if (!count)
388	continue;
389
390	if (!zombie) {
391	zombie = zalloc(s: sizeof(*zombie) +
392	(interface->event_count * sizeof(int)));
393	if (!zombie)
394	return NULL;
395
396	zombie->event_count = interface->event_count;
397	zombie->fd_count = (int *) &zombie[1];
398	}
399
400	zombie->fd_count[i] = count;
401	}
402
403	return zombie;
404	}
405
406	static enum wl_iterator_result
407	free_zombies(void *element, void *data, uint32_t flags)
408	{
409	if (flags & WL_MAP_ENTRY_ZOMBIE)
410	free(ptr: element);
411
412	return WL_ITERATOR_CONTINUE;
413	}
414
415	static struct wl_proxy *
416	proxy_create(struct wl_proxy *factory, const struct wl_interface *interface,
417	uint32_t version)
418	{
419	struct wl_proxy *proxy;
420	struct wl_display *display = factory->display;
421
422	proxy = zalloc(s: sizeof *proxy);
423	if (proxy == NULL)
424	return NULL;
425
426	proxy->object.interface = interface;
427	proxy->display = display;
428	proxy->queue = factory->queue;
429	proxy->refcount = 1;
430	proxy->version = version;
431
432	proxy->object.id = wl_map_insert_new(map: &display->objects, flags: 0, data: proxy);
433
434	return proxy;
435	}
436
437	/** Create a proxy object with a given interface
438	*
439	* \param factory Factory proxy object
440	* \param interface Interface the proxy object should use
441	* \return A newly allocated proxy object or NULL on failure
442	*
443	* This function creates a new proxy object with the supplied interface. The
444	* proxy object will have an id assigned from the client id space. The id
445	* should be created on the compositor side by sending an appropriate request
446	* with \ref wl_proxy_marshal().
447	*
448	* The proxy will inherit the display and event queue of the factory object.
449	*
450	* \note This should not normally be used by non-generated code.
451	*
452	* \sa wl_display, wl_event_queue, wl_proxy_marshal()
453	*
454	* \memberof wl_proxy
455	*/
456	WL_EXPORT struct wl_proxy *
457	wl_proxy_create(struct wl_proxy *factory, const struct wl_interface *interface)
458	{
459	struct wl_display *display = factory->display;
460	struct wl_proxy *proxy;
461
462	pthread_mutex_lock(mutex: &display->mutex);
463	proxy = proxy_create(factory, interface, version: factory->version);
464	pthread_mutex_unlock(mutex: &display->mutex);
465
466	return proxy;
467	}
468
469	/* The caller should hold the display lock */
470	static struct wl_proxy *
471	wl_proxy_create_for_id(struct wl_proxy *factory,
472	uint32_t id, const struct wl_interface *interface)
473	{
474	struct wl_proxy *proxy;
475	struct wl_display *display = factory->display;
476
477	proxy = zalloc(s: sizeof *proxy);
478	if (proxy == NULL)
479	return NULL;
480
481	proxy->object.interface = interface;
482	proxy->object.id = id;
483	proxy->display = display;
484	proxy->queue = factory->queue;
485	proxy->refcount = 1;
486	proxy->version = factory->version;
487
488	wl_map_insert_at(map: &display->objects, flags: 0, i: id, data: proxy);
489
490	return proxy;
491	}
492
493	static void
494	proxy_destroy(struct wl_proxy *proxy)
495	{
496	if (proxy->flags & WL_PROXY_FLAG_ID_DELETED) {
497	wl_map_remove(map: &proxy->display->objects, i: proxy->object.id);
498	} else if (proxy->object.id < WL_SERVER_ID_START) {
499	struct wl_zombie *zombie = prepare_zombie(proxy);
500
501	/* The map now contains the zombie entry, until the delete_id
502	* event arrives. */
503	wl_map_insert_at(map: &proxy->display->objects,
504	flags: WL_MAP_ENTRY_ZOMBIE,
505	i: proxy->object.id,
506	data: zombie);
507	} else {
508	wl_map_insert_at(map: &proxy->display->objects, flags: 0,
509	i: proxy->object.id, NULL);
510	}
511
512	proxy->flags |= WL_PROXY_FLAG_DESTROYED;
513
514	wl_proxy_unref(proxy);
515	}
516
517	static void
518	wl_proxy_destroy_caller_locks(struct wl_proxy *proxy)
519	{
520	if (proxy->flags & WL_PROXY_FLAG_WRAPPER)
521	wl_abort(fmt: "Tried to destroy wrapper with wl_proxy_destroy()\n");
522
523	proxy_destroy(proxy);
524	}
525
526	/** Destroy a proxy object
527	*
528	* \param proxy The proxy to be destroyed
529	*
530	* \c proxy must not be a proxy wrapper.
531	*
532	* \note This function will abort in response to egregious
533	* errors, and will do so with the display lock held. This means
534	* SIGABRT handlers must not perform any actions that would
535	* attempt to take that lock, or a deadlock would occur.
536	*
537	* \memberof wl_proxy
538	*/
539	WL_EXPORT void
540	wl_proxy_destroy(struct wl_proxy *proxy)
541	{
542	struct wl_display *display = proxy->display;
543
544	pthread_mutex_lock(mutex: &display->mutex);
545
546	wl_proxy_destroy_caller_locks(proxy);
547
548	pthread_mutex_unlock(mutex: &display->mutex);
549	}
550
551	/** Set a proxy's listener
552	*
553	* \param proxy The proxy object
554	* \param implementation The listener to be added to proxy
555	* \param data User data to be associated with the proxy
556	* \return 0 on success or -1 on failure
557	*
558	* Set proxy's listener to \c implementation and its user data to
559	* \c data. If a listener has already been set, this function
560	* fails and nothing is changed.
561	*
562	* \c implementation is a vector of function pointers. For an opcode
563	* \c n, \c implementation[n] should point to the handler of \c n for
564	* the given object.
565	*
566	* \c proxy must not be a proxy wrapper.
567	*
568	* \memberof wl_proxy
569	*/
570	WL_EXPORT int
571	wl_proxy_add_listener(struct wl_proxy *proxy,
572	void (**implementation)(void), void *data)
573	{
574	if (proxy->flags & WL_PROXY_FLAG_WRAPPER)
575	wl_abort(fmt: "Proxy %p is a wrapper\n", proxy);
576
577	if (proxy->object.implementation || proxy->dispatcher) {
578	wl_log(fmt: "proxy %p already has listener\n", proxy);
579	return -1;
580	}
581
582	proxy->object.implementation = implementation;
583	proxy->user_data = data;
584
585	return 0;
586	}
587
588	/** Get a proxy's listener
589	*
590	* \param proxy The proxy object
591	* \return The address of the proxy's listener or NULL if no listener is set
592	*
593	* Gets the address to the proxy's listener; which is the listener set with
594	* \ref wl_proxy_add_listener.
595	*
596	* This function is useful in clients with multiple listeners on the same
597	* interface to allow the identification of which code to execute.
598	*
599	* \memberof wl_proxy
600	*/
601	WL_EXPORT const void *
602	wl_proxy_get_listener(struct wl_proxy *proxy)
603	{
604	return proxy->object.implementation;
605	}
606
607	/** Set a proxy's listener (with dispatcher)
608	*
609	* \param proxy The proxy object
610	* \param dispatcher The dispatcher to be used for this proxy
611	* \param implementation The dispatcher-specific listener implementation
612	* \param data User data to be associated with the proxy
613	* \return 0 on success or -1 on failure
614	*
615	* Set proxy's listener to use \c dispatcher_func as its dispatcher and \c
616	* dispatcher_data as its dispatcher-specific implementation and its user data
617	* to \c data. If a listener has already been set, this function
618	* fails and nothing is changed.
619	*
620	* The exact details of dispatcher_data depend on the dispatcher used. This
621	* function is intended to be used by language bindings, not user code.
622	*
623	* \c proxy must not be a proxy wrapper.
624	*
625	* \memberof wl_proxy
626	*/
627	WL_EXPORT int
628	wl_proxy_add_dispatcher(struct wl_proxy *proxy,
629	wl_dispatcher_func_t dispatcher,
630	const void *implementation, void *data)
631	{
632	if (proxy->flags & WL_PROXY_FLAG_WRAPPER)
633	wl_abort(fmt: "Proxy %p is a wrapper\n", proxy);
634
635	if (proxy->object.implementation || proxy->dispatcher) {
636	wl_log(fmt: "proxy %p already has listener\n", proxy);
637	return -1;
638	}
639
640	proxy->object.implementation = implementation;
641	proxy->dispatcher = dispatcher;
642	proxy->user_data = data;
643
644	return 0;
645	}
646
647	static struct wl_proxy *
648	create_outgoing_proxy(struct wl_proxy *proxy, const struct wl_message *message,
649	union wl_argument *args,
650	const struct wl_interface *interface, uint32_t version)
651	{
652	int i, count;
653	const char *signature;
654	struct argument_details arg;
655	struct wl_proxy *new_proxy = NULL;
656
657	signature = message->signature;
658	count = arg_count_for_signature(signature);
659	for (i = 0; i < count; i++) {
660	signature = get_next_argument(signature, details: &arg);
661
662	switch (arg.type) {
663	case 'n':
664	new_proxy = proxy_create(factory: proxy, interface, version);
665	if (new_proxy == NULL)
666	return NULL;
667
668	args[i].o = &new_proxy->object;
669	break;
670	}
671	}
672
673	return new_proxy;
674	}
675
676	/** Prepare a request to be sent to the compositor
677	*
678	* \param proxy The proxy object
679	* \param opcode Opcode of the request to be sent
680	* \param args Extra arguments for the given request
681	* \param interface The interface to use for the new proxy
682	*
683	* This function translates a request given an opcode, an interface and a
684	* wl_argument array to the wire format and writes it to the connection
685	* buffer.
686	*
687	* For new-id arguments, this function will allocate a new wl_proxy
688	* and send the ID to the server. The new wl_proxy will be returned
689	* on success or NULL on error with errno set accordingly. The newly
690	* created proxy will inherit their version from their parent.
691	*
692	* \note This is intended to be used by language bindings and not in
693	* non-generated code.
694	*
695	* \sa wl_proxy_marshal()
696	*
697	* \memberof wl_proxy
698	*/
699	WL_EXPORT struct wl_proxy *
700	wl_proxy_marshal_array_constructor(struct wl_proxy *proxy,
701	uint32_t opcode, union wl_argument *args,
702	const struct wl_interface *interface)
703	{
704	return wl_proxy_marshal_array_constructor_versioned(proxy, opcode,
705	args, interface,
706	version: proxy->version);
707	}
708
709
710	/** Prepare a request to be sent to the compositor
711	*
712	* \param proxy The proxy object
713	* \param opcode Opcode of the request to be sent
714	* \param args Extra arguments for the given request
715	* \param interface The interface to use for the new proxy
716	* \param version The protocol object version for the new proxy
717	*
718	* Translates the request given by opcode and the extra arguments into the
719	* wire format and write it to the connection buffer. This version takes an
720	* array of the union type wl_argument.
721	*
722	* For new-id arguments, this function will allocate a new wl_proxy
723	* and send the ID to the server. The new wl_proxy will be returned
724	* on success or NULL on error with errno set accordingly. The newly
725	* created proxy will have the version specified.
726	*
727	* \note This is intended to be used by language bindings and not in
728	* non-generated code.
729	*
730	* \sa wl_proxy_marshal()
731	*
732	* \memberof wl_proxy
733	*/
734	WL_EXPORT struct wl_proxy *
735	wl_proxy_marshal_array_constructor_versioned(struct wl_proxy *proxy,
736	uint32_t opcode,
737	union wl_argument *args,
738	const struct wl_interface *interface,
739	uint32_t version)
740	{
741	return wl_proxy_marshal_array_flags(proxy, opcode, interface, version, flags: 0, args);
742	}
743
744	/** Prepare a request to be sent to the compositor
745	*
746	* \param proxy The proxy object
747	* \param opcode Opcode of the request to be sent
748	* \param interface The interface to use for the new proxy
749	* \param version The protocol object version of the new proxy
750	* \param flags Flags that modify marshalling behaviour
751	* \param ... Extra arguments for the given request
752	* \return A new wl_proxy for the new_id argument or NULL on error
753	*
754	* Translates the request given by opcode and the extra arguments into the
755	* wire format and write it to the connection buffer.
756	*
757	* For new-id arguments, this function will allocate a new wl_proxy
758	* and send the ID to the server. The new wl_proxy will be returned
759	* on success or NULL on error with errno set accordingly. The newly
760	* created proxy will have the version specified.
761	*
762	* The flag WL_MARSHAL_FLAG_DESTROY may be passed to ensure the proxy
763	* is destroyed atomically with the marshalling in order to prevent
764	* races that can occur if the display lock is dropped between the
765	* marshal and destroy operations.
766	*
767	* \note This should not normally be used by non-generated code.
768	*
769	* \memberof wl_proxy
770	*/
771	WL_EXPORT struct wl_proxy *
772	wl_proxy_marshal_flags(struct wl_proxy *proxy, uint32_t opcode,
773	const struct wl_interface *interface, uint32_t version,
774	uint32_t flags, ...)
775	{
776	union wl_argument args[WL_CLOSURE_MAX_ARGS];
777	va_list ap;
778
779	va_start(ap, flags);
780	wl_argument_from_va_list(signature: proxy->object.interface->methods[opcode].signature,
781	args, WL_CLOSURE_MAX_ARGS, ap);
782	va_end(ap);
783
784	return wl_proxy_marshal_array_flags(proxy, opcode, interface, version, flags, args);
785	}
786
787	/** Prepare a request to be sent to the compositor
788	*
789	* \param proxy The proxy object
790	* \param opcode Opcode of the request to be sent
791	* \param interface The interface to use for the new proxy
792	* \param version The protocol object version for the new proxy
793	* \param flags Flags that modify marshalling behaviour
794	* \param args Extra arguments for the given request
795	*
796	* Translates the request given by opcode and the extra arguments into the
797	* wire format and write it to the connection buffer. This version takes an
798	* array of the union type wl_argument.
799	*
800	* For new-id arguments, this function will allocate a new wl_proxy
801	* and send the ID to the server. The new wl_proxy will be returned
802	* on success or NULL on error with errno set accordingly. The newly
803	* created proxy will have the version specified.
804	*
805	* The flag WL_MARSHAL_FLAG_DESTROY may be passed to ensure the proxy
806	* is destroyed atomically with the marshalling in order to prevent
807	* races that can occur if the display lock is dropped between the
808	* marshal and destroy operations.
809	*
810	* \note This is intended to be used by language bindings and not in
811	* non-generated code.
812	*
813	* \sa wl_proxy_marshal_flags()
814	*
815	* \memberof wl_proxy
816	*/
817	WL_EXPORT struct wl_proxy *
818	wl_proxy_marshal_array_flags(struct wl_proxy *proxy, uint32_t opcode,
819	const struct wl_interface *interface, uint32_t version,
820	uint32_t flags, union wl_argument *args)
821	{
822	struct wl_closure *closure;
823	struct wl_proxy *new_proxy = NULL;
824	const struct wl_message *message;
825	struct wl_display *disp = proxy->display;
826
827	pthread_mutex_lock(mutex: &disp->mutex);
828
829	message = &proxy->object.interface->methods[opcode];
830	if (interface) {
831	new_proxy = create_outgoing_proxy(proxy, message,
832	args, interface,
833	version);
834	if (new_proxy == NULL)
835	goto err_unlock;
836	}
837
838	if (proxy->display->last_error) {
839	goto err_unlock;
840	}
841
842	closure = wl_closure_marshal(sender: &proxy->object, opcode, args, message);
843	if (closure == NULL) {
844	wl_log(fmt: "Error marshalling request: %s\n", strerror(errno));
845	display_fatal_error(display: proxy->display, errno);
846	goto err_unlock;
847	}
848
849	if (debug_client)
850	wl_closure_print(closure, target: &proxy->object, true, false, NULL);
851
852	if (wl_closure_send(closure, connection: proxy->display->connection)) {
853	wl_log(fmt: "Error sending request: %s\n", strerror(errno));
854	display_fatal_error(display: proxy->display, errno);
855	}
856
857	wl_closure_destroy(closure);
858
859	err_unlock:
860	if (flags & WL_MARSHAL_FLAG_DESTROY)
861	wl_proxy_destroy_caller_locks(proxy);
862
863	pthread_mutex_unlock(mutex: &disp->mutex);
864
865	return new_proxy;
866	}
867
868
869	/** Prepare a request to be sent to the compositor
870	*
871	* \param proxy The proxy object
872	* \param opcode Opcode of the request to be sent
873	* \param ... Extra arguments for the given request
874	*
875	* This function is similar to wl_proxy_marshal_constructor(), except
876	* it doesn't create proxies for new-id arguments.
877	*
878	* \note This should not normally be used by non-generated code.
879	*
880	* \sa wl_proxy_create()
881	*
882	* \memberof wl_proxy
883	*/
884	WL_EXPORT void
885	wl_proxy_marshal(struct wl_proxy *proxy, uint32_t opcode, ...)
886	{
887	union wl_argument args[WL_CLOSURE_MAX_ARGS];
888	va_list ap;
889
890	va_start(ap, opcode);
891	wl_argument_from_va_list(signature: proxy->object.interface->methods[opcode].signature,
892	args, WL_CLOSURE_MAX_ARGS, ap);
893	va_end(ap);
894
895	wl_proxy_marshal_array_constructor(proxy, opcode, args, NULL);
896	}
897
898	/** Prepare a request to be sent to the compositor
899	*
900	* \param proxy The proxy object
901	* \param opcode Opcode of the request to be sent
902	* \param interface The interface to use for the new proxy
903	* \param ... Extra arguments for the given request
904	* \return A new wl_proxy for the new_id argument or NULL on error
905	*
906	* This function translates a request given an opcode, an interface and extra
907	* arguments to the wire format and writes it to the connection buffer. The
908	* types of the extra arguments must correspond to the argument types of the
909	* method associated with the opcode in the interface.
910	*
911	* For new-id arguments, this function will allocate a new wl_proxy
912	* and send the ID to the server. The new wl_proxy will be returned
913	* on success or NULL on error with errno set accordingly. The newly
914	* created proxy will inherit their version from their parent.
915	*
916	* \note This should not normally be used by non-generated code.
917	*
918	* \memberof wl_proxy
919	*/
920	WL_EXPORT struct wl_proxy *
921	wl_proxy_marshal_constructor(struct wl_proxy *proxy, uint32_t opcode,
922	const struct wl_interface *interface, ...)
923	{
924	union wl_argument args[WL_CLOSURE_MAX_ARGS];
925	va_list ap;
926
927	va_start(ap, interface);
928	wl_argument_from_va_list(signature: proxy->object.interface->methods[opcode].signature,
929	args, WL_CLOSURE_MAX_ARGS, ap);
930	va_end(ap);
931
932	return wl_proxy_marshal_array_constructor(proxy, opcode,
933	args, interface);
934	}
935
936
937	/** Prepare a request to be sent to the compositor
938	*
939	* \param proxy The proxy object
940	* \param opcode Opcode of the request to be sent
941	* \param interface The interface to use for the new proxy
942	* \param version The protocol object version of the new proxy
943	* \param ... Extra arguments for the given request
944	* \return A new wl_proxy for the new_id argument or NULL on error
945	*
946	* Translates the request given by opcode and the extra arguments into the
947	* wire format and write it to the connection buffer.
948	*
949	* For new-id arguments, this function will allocate a new wl_proxy
950	* and send the ID to the server. The new wl_proxy will be returned
951	* on success or NULL on error with errno set accordingly. The newly
952	* created proxy will have the version specified.
953	*
954	* \note This should not normally be used by non-generated code.
955	*
956	* \memberof wl_proxy
957	*/
958	WL_EXPORT struct wl_proxy *
959	wl_proxy_marshal_constructor_versioned(struct wl_proxy *proxy, uint32_t opcode,
960	const struct wl_interface *interface,
961	uint32_t version, ...)
962	{
963	union wl_argument args[WL_CLOSURE_MAX_ARGS];
964	va_list ap;
965
966	va_start(ap, version);
967	wl_argument_from_va_list(signature: proxy->object.interface->methods[opcode].signature,
968	args, WL_CLOSURE_MAX_ARGS, ap);
969	va_end(ap);
970
971	return wl_proxy_marshal_array_constructor_versioned(proxy, opcode,
972	args, interface,
973	version);
974	}
975
976	/** Prepare a request to be sent to the compositor
977	*
978	* \param proxy The proxy object
979	* \param opcode Opcode of the request to be sent
980	* \param args Extra arguments for the given request
981	*
982	* This function is similar to wl_proxy_marshal_array_constructor(), except
983	* it doesn't create proxies for new-id arguments.
984	*
985	* \note This is intended to be used by language bindings and not in
986	* non-generated code.
987	*
988	* \sa wl_proxy_marshal()
989	*
990	* \memberof wl_proxy
991	*/
992	WL_EXPORT void
993	wl_proxy_marshal_array(struct wl_proxy *proxy, uint32_t opcode,
994	union wl_argument *args)
995	{
996	wl_proxy_marshal_array_constructor(proxy, opcode, args, NULL);
997	}
998
999	static void
1000	display_handle_error(void *data,
1001	struct wl_display *display, void *object,
1002	uint32_t code, const char *message)
1003	{
1004	struct wl_proxy *proxy = object;
1005	uint32_t object_id;
1006	const struct wl_interface *interface;
1007
1008	if (proxy) {
1009	wl_log(fmt: "%s@%u: error %d: %s\n",
1010	proxy->object.interface->name,
1011	proxy->object.id,
1012	code, message);
1013
1014	object_id = proxy->object.id;
1015	interface = proxy->object.interface;
1016	} else {
1017	wl_log(fmt: "[destroyed object]: error %d: %s\n",
1018	code, message);
1019
1020	object_id = 0;
1021	interface = NULL;
1022	}
1023
1024	display_protocol_error(display, code, id: object_id, intf: interface);
1025	}
1026
1027	static void
1028	display_handle_delete_id(void *data, struct wl_display *display, uint32_t id)
1029	{
1030	struct wl_proxy *proxy;
1031
1032	pthread_mutex_lock(mutex: &display->mutex);
1033
1034	proxy = wl_map_lookup(map: &display->objects, i: id);
1035
1036	if (wl_object_is_zombie(map: &display->objects, id)) {
1037	/* For zombie objects, the 'proxy' is actually the zombie
1038	* event-information structure, which we can free. */
1039	free(ptr: proxy);
1040	wl_map_remove(map: &display->objects, i: id);
1041	} else if (proxy) {
1042	proxy->flags |= WL_PROXY_FLAG_ID_DELETED;
1043	} else {
1044	wl_log(fmt: "error: received delete_id for unknown id (%u)\n", id);
1045	}
1046
1047	pthread_mutex_unlock(mutex: &display->mutex);
1048	}
1049
1050	static const struct wl_display_listener display_listener = {
1051	display_handle_error,
1052	display_handle_delete_id
1053	};
1054
1055	static int
1056	connect_to_socket(const char *name)
1057	{
1058	struct sockaddr_un addr;
1059	socklen_t size;
1060	const char *runtime_dir;
1061	int name_size, fd;
1062	bool path_is_absolute;
1063
1064	if (name == NULL)
1065	name = getenv(name: "WAYLAND_DISPLAY");
1066	if (name == NULL)
1067	name = "wayland-0";
1068
1069	path_is_absolute = name[0] == '/';
1070
1071	runtime_dir = getenv(name: "XDG_RUNTIME_DIR");
1072	if (!runtime_dir && !path_is_absolute) {
1073	wl_log(fmt: "error: XDG_RUNTIME_DIR not set in the environment.\n");
1074	/* to prevent programs reporting
1075	* "failed to create display: Success" */
1076	errno = ENOENT;
1077	return -1;
1078	}
1079
1080	fd = wl_os_socket_cloexec(PF_LOCAL, SOCK_STREAM, protocol: 0);
1081	if (fd < 0)
1082	return -1;
1083
1084	memset(s: &addr, c: 0, n: sizeof addr);
1085	addr.sun_family = AF_LOCAL;
1086	if (!path_is_absolute) {
1087	name_size =
1088	snprintf(s: addr.sun_path, maxlen: sizeof addr.sun_path,
1089	format: "%s/%s", runtime_dir, name) + 1;
1090	} else {
1091	/* absolute path */
1092	name_size =
1093	snprintf(s: addr.sun_path, maxlen: sizeof addr.sun_path,
1094	format: "%s", name) + 1;
1095	}
1096
1097	assert(name_size > 0);
1098	if (name_size > (int)sizeof addr.sun_path) {
1099	if (!path_is_absolute) {
1100	wl_log(fmt: "error: socket path \"%s/%s\" plus null terminator"
1101	" exceeds %i bytes\n", runtime_dir, name, (int) sizeof(addr.sun_path));
1102	} else {
1103	wl_log(fmt: "error: socket path \"%s\" plus null terminator"
1104	" exceeds %i bytes\n", name, (int) sizeof(addr.sun_path));
1105	}
1106	close(fd: fd);
1107	/* to prevent programs reporting
1108	* "failed to add socket: Success" */
1109	errno = ENAMETOOLONG;
1110	return -1;
1111	};
1112
1113	size = offsetof (struct sockaddr_un, sun_path) + name_size;
1114
1115	if (connect(fd: fd, addr: (struct sockaddr *) &addr, len: size) < 0) {
1116	close(fd: fd);
1117	return -1;
1118	}
1119
1120	return fd;
1121	}
1122
1123	/** Connect to Wayland display on an already open fd
1124	*
1125	* \param fd The fd to use for the connection
1126	* \return A \ref wl_display object or \c NULL on failure
1127	*
1128	* The wl_display takes ownership of the fd and will close it when the
1129	* display is destroyed. The fd will also be closed in case of
1130	* failure.
1131	*
1132	* \memberof wl_display
1133	*/
1134	WL_EXPORT struct wl_display *
1135	wl_display_connect_to_fd(int fd)
1136	{
1137	struct wl_display *display;
1138	const char *debug;
1139
1140	debug = getenv(name: "WAYLAND_DEBUG");
1141	if (debug && (strstr(haystack: debug, needle: "client") || strstr(haystack: debug, needle: "1")))
1142	debug_client = 1;
1143
1144	display = zalloc(s: sizeof *display);
1145	if (display == NULL) {
1146	close(fd: fd);
1147	return NULL;
1148	}
1149
1150	display->fd = fd;
1151	wl_map_init(map: &display->objects, WL_MAP_CLIENT_SIDE);
1152	wl_event_queue_init(queue: &display->default_queue, display);
1153	wl_event_queue_init(queue: &display->display_queue, display);
1154	pthread_mutex_init(mutex: &display->mutex, NULL);
1155	pthread_cond_init(cond: &display->reader_cond, NULL);
1156	display->reader_count = 0;
1157
1158	wl_map_insert_new(map: &display->objects, flags: 0, NULL);
1159
1160	display->proxy.object.interface = &wl_display_interface;
1161	display->proxy.object.id =
1162	wl_map_insert_new(map: &display->objects, flags: 0, data: display);
1163	display->proxy.display = display;
1164	display->proxy.object.implementation = (void(**)(void)) &display_listener;
1165	display->proxy.user_data = display;
1166	display->proxy.queue = &display->default_queue;
1167	display->proxy.flags = 0;
1168	display->proxy.refcount = 1;
1169
1170	/* We set this version to 0 for backwards compatibility.
1171	*
1172	* If a client is using old versions of protocol headers,
1173	* it will use unversioned API to create proxies. Those
1174	* proxies will inherit this 0.
1175	*
1176	* A client could be passing these proxies into library
1177	* code newer than the headers that checks proxy
1178	* versions. When the proxy version is reported as 0
1179	* the library will know that it can't reliably determine
1180	* the proxy version, and should do whatever fallback is
1181	* required.
1182	*
1183	* This trick forces wl_display to always report 0, but
1184	* since it's a special object that we can't bind
1185	* specific versions of anyway, this should be fine.
1186	*/
1187	display->proxy.version = 0;
1188
1189	display->connection = wl_connection_create(fd: display->fd);
1190	if (display->connection == NULL)
1191	goto err_connection;
1192
1193	return display;
1194
1195	err_connection:
1196	pthread_mutex_destroy(mutex: &display->mutex);
1197	pthread_cond_destroy(cond: &display->reader_cond);
1198	wl_map_release(map: &display->objects);
1199	close(fd: display->fd);
1200	free(ptr: display);
1201
1202	return NULL;
1203	}
1204
1205	/** Connect to a Wayland display
1206	*
1207	* \param name Name of the Wayland display to connect to
1208	* \return A \ref wl_display object or \c NULL on failure
1209	*
1210	* Connect to the Wayland display named \c name. If \c name is \c NULL,
1211	* its value will be replaced with the WAYLAND_DISPLAY environment
1212	* variable if it is set, otherwise display "wayland-0" will be used.
1213	*
1214	* If WAYLAND_SOCKET is set, it's interpreted as a file descriptor number
1215	* referring to an already opened socket. In this case, the socket is used
1216	* as-is and \c name is ignored.
1217	*
1218	* If \c name is a relative path, then the socket is opened relative to
1219	* the XDG_RUNTIME_DIR directory.
1220	*
1221	* If \c name is an absolute path, then that path is used as-is for
1222	* the location of the socket at which the Wayland server is listening;
1223	* no qualification inside XDG_RUNTIME_DIR is attempted.
1224	*
1225	* If \c name is \c NULL and the WAYLAND_DISPLAY environment variable
1226	* is set to an absolute pathname, then that pathname is used as-is
1227	* for the socket in the same manner as if \c name held an absolute
1228	* path. Support for absolute paths in \c name and WAYLAND_DISPLAY
1229	* is present since Wayland version 1.15.
1230	*
1231	* \memberof wl_display
1232	*/
1233	WL_EXPORT struct wl_display *
1234	wl_display_connect(const char *name)
1235	{
1236	char *connection, *end;
1237	int flags, fd;
1238
1239	connection = getenv(name: "WAYLAND_SOCKET");
1240	if (connection) {
1241	int prev_errno = errno;
1242	errno = 0;
1243	fd = strtol(nptr: connection, endptr: &end, base: 10);
1244	if (errno != 0 || connection == end || *end != '\0')
1245	return NULL;
1246	errno = prev_errno;
1247
1248	flags = fcntl(fd: fd, F_GETFD);
1249	if (flags == -1 && errno == EBADF)
1250	return NULL;
1251	else if (flags != -1)
1252	fcntl(fd: fd, F_SETFD, flags | FD_CLOEXEC);
1253	unsetenv(name: "WAYLAND_SOCKET");
1254	} else {
1255	fd = connect_to_socket(name);
1256	if (fd < 0)
1257	return NULL;
1258	}
1259
1260	return wl_display_connect_to_fd(fd);
1261	}
1262
1263	/** Close a connection to a Wayland display
1264	*
1265	* \param display The display context object
1266	*
1267	* Close the connection to \c display and free all resources associated
1268	* with it.
1269	*
1270	* \memberof wl_display
1271	*/
1272	WL_EXPORT void
1273	wl_display_disconnect(struct wl_display *display)
1274	{
1275	wl_connection_destroy(connection: display->connection);
1276	wl_map_for_each(map: &display->objects, func: free_zombies, NULL);
1277	wl_map_release(map: &display->objects);
1278	wl_event_queue_release(queue: &display->default_queue);
1279	wl_event_queue_release(queue: &display->display_queue);
1280	pthread_mutex_destroy(mutex: &display->mutex);
1281	pthread_cond_destroy(cond: &display->reader_cond);
1282	close(fd: display->fd);
1283
1284	free(ptr: display);
1285	}
1286
1287	/** Get a display context's file descriptor
1288	*
1289	* \param display The display context object
1290	* \return Display object file descriptor
1291	*
1292	* Return the file descriptor associated with a display so it can be
1293	* integrated into the client's main loop.
1294	*
1295	* \memberof wl_display
1296	*/
1297	WL_EXPORT int
1298	wl_display_get_fd(struct wl_display *display)
1299	{
1300	return display->fd;
1301	}
1302
1303	static void
1304	sync_callback(void *data, struct wl_callback *callback, uint32_t serial)
1305	{
1306	int *done = data;
1307
1308	*done = 1;
1309	wl_callback_destroy(wl_callback: callback);
1310	}
1311
1312	static const struct wl_callback_listener sync_listener = {
1313	sync_callback
1314	};
1315
1316	/** Block until all pending request are processed by the server
1317	*
1318	* \param display The display context object
1319	* \param queue The queue on which to run the roundtrip
1320	* \return The number of dispatched events on success or -1 on failure
1321	*
1322	* This function blocks until the server has processed all currently issued
1323	* requests by sending a request to the display server and waiting for a
1324	* reply before returning.
1325	*
1326	* This function uses wl_display_dispatch_queue() internally. It is not allowed
1327	* to call this function while the thread is being prepared for reading events,
1328	* and doing so will cause a dead lock.
1329	*
1330	* \note This function may dispatch other events being received on the given
1331	* queue.
1332	*
1333	* \sa wl_display_roundtrip()
1334	* \memberof wl_display
1335	*/
1336	WL_EXPORT int
1337	wl_display_roundtrip_queue(struct wl_display *display, struct wl_event_queue *queue)
1338	{
1339	struct wl_display *display_wrapper;
1340	struct wl_callback *callback;
1341	int done, ret = 0;
1342
1343	done = 0;
1344
1345	display_wrapper = wl_proxy_create_wrapper(proxy: display);
1346	if (!display_wrapper)
1347	return -1;
1348
1349	wl_proxy_set_queue(proxy: (struct wl_proxy *) display_wrapper, queue);
1350	callback = wl_display_sync(wl_display: display_wrapper);
1351	wl_proxy_wrapper_destroy(proxy_wrapper: display_wrapper);
1352
1353	if (callback == NULL)
1354	return -1;
1355
1356	wl_callback_add_listener(wl_callback: callback, listener: &sync_listener, data: &done);
1357	while (!done && ret >= 0)
1358	ret = wl_display_dispatch_queue(display, queue);
1359
1360	if (ret == -1 && !done)
1361	wl_callback_destroy(wl_callback: callback);
1362
1363	return ret;
1364	}
1365
1366	/** Block until all pending request are processed by the server
1367	*
1368	* \param display The display context object
1369	* \return The number of dispatched events on success or -1 on failure
1370	*
1371	* This function blocks until the server has processed all currently issued
1372	* requests by sending a request to the display server and waiting for a reply
1373	* before returning.
1374	*
1375	* This function uses wl_display_dispatch_queue() internally. It is not allowed
1376	* to call this function while the thread is being prepared for reading events,
1377	* and doing so will cause a dead lock.
1378	*
1379	* \note This function may dispatch other events being received on the default
1380	* queue.
1381	*
1382	* \memberof wl_display
1383	*/
1384	WL_EXPORT int
1385	wl_display_roundtrip(struct wl_display *display)
1386	{
1387	return wl_display_roundtrip_queue(display, queue: &display->default_queue);
1388	}
1389
1390	static int
1391	create_proxies(struct wl_proxy *sender, struct wl_closure *closure)
1392	{
1393	struct wl_proxy *proxy;
1394	const char *signature;
1395	struct argument_details arg;
1396	uint32_t id;
1397	int i;
1398	int count;
1399
1400	signature = closure->message->signature;
1401	count = arg_count_for_signature(signature);
1402	for (i = 0; i < count; i++) {
1403	signature = get_next_argument(signature, details: &arg);
1404	switch (arg.type) {
1405	case 'n':
1406	id = closure->args[i].n;
1407	if (id == 0) {
1408	closure->args[i].o = NULL;
1409	break;
1410	}
1411	proxy = wl_proxy_create_for_id(factory: sender, id,
1412	interface: closure->message->types[i]);
1413	if (proxy == NULL)
1414	return -1;
1415	closure->args[i].o = (struct wl_object *)proxy;
1416	break;
1417	default:
1418	break;
1419	}
1420	}
1421
1422	return 0;
1423	}
1424
1425	static void
1426	increase_closure_args_refcount(struct wl_closure *closure)
1427	{
1428	const char *signature;
1429	struct argument_details arg;
1430	int i, count;
1431	struct wl_proxy *proxy;
1432
1433	signature = closure->message->signature;
1434	count = arg_count_for_signature(signature);
1435	for (i = 0; i < count; i++) {
1436	signature = get_next_argument(signature, details: &arg);
1437	switch (arg.type) {
1438	case 'n':
1439	case 'o':
1440	proxy = (struct wl_proxy *) closure->args[i].o;
1441	if (proxy)
1442	proxy->refcount++;
1443	break;
1444	default:
1445	break;
1446	}
1447	}
1448
1449	closure->proxy->refcount++;
1450	}
1451
1452	static int
1453	queue_event(struct wl_display *display, int len)
1454	{
1455	uint32_t p[2], id;
1456	int opcode, size;
1457	struct wl_proxy *proxy;
1458	struct wl_closure *closure;
1459	const struct wl_message *message;
1460	struct wl_event_queue *queue;
1461	struct timespec tp;
1462	unsigned int time;
1463	int num_zombie_fds;
1464
1465	wl_connection_copy(connection: display->connection, data: p, size: sizeof p);
1466	id = p[0];
1467	opcode = p[1] & 0xffff;
1468	size = p[1] >> 16;
1469	if (len < size)
1470	return 0;
1471
1472	/* If our proxy is gone or a zombie, just eat the event (and any FDs,
1473	* if applicable). */
1474	proxy = wl_map_lookup(map: &display->objects, i: id);
1475	if (!proxy || wl_object_is_zombie(map: &display->objects, id)) {
1476	struct wl_zombie *zombie = wl_map_lookup(map: &display->objects, i: id);
1477	num_zombie_fds = (zombie && opcode < zombie->event_count) ?
1478	zombie->fd_count[opcode] : 0;
1479
1480	if (debug_client) {
1481	clock_gettime(CLOCK_REALTIME, tp: &tp);
1482	time = (tp.tv_sec * 1000000L) + (tp.tv_nsec / 1000);
1483
1484	fprintf(stderr, format: "[%7u.%03u] discarded [%s]@%d.[event %d]"
1485	"(%d fd, %d byte)\n",
1486	time / 1000, time % 1000,
1487	zombie ? "zombie" : "unknown",
1488	id, opcode,
1489	num_zombie_fds, size);
1490	}
1491	if (num_zombie_fds > 0)
1492	wl_connection_close_fds_in(connection: display->connection,
1493	max: num_zombie_fds);
1494
1495	wl_connection_consume(connection: display->connection, size);
1496	return size;
1497	}
1498
1499	if (opcode >= proxy->object.interface->event_count) {
1500	wl_log(fmt: "interface '%s' has no event %u\n",
1501	proxy->object.interface->name, opcode);
1502	return -1;
1503	}
1504
1505	message = &proxy->object.interface->events[opcode];
1506	closure = wl_connection_demarshal(connection: display->connection, size,
1507	objects: &display->objects, message);
1508	if (!closure)
1509	return -1;
1510
1511	if (create_proxies(sender: proxy, closure) < 0) {
1512	wl_closure_destroy(closure);
1513	return -1;
1514	}
1515
1516	if (wl_closure_lookup_objects(closure, objects: &display->objects) != 0) {
1517	wl_closure_destroy(closure);
1518	return -1;
1519	}
1520
1521	closure->proxy = proxy;
1522	increase_closure_args_refcount(closure);
1523
1524	if (proxy == &display->proxy)
1525	queue = &display->display_queue;
1526	else
1527	queue = proxy->queue;
1528
1529	wl_list_insert(list: queue->event_list.prev, elm: &closure->link);
1530
1531	return size;
1532	}
1533
1534	static uint32_t
1535	id_from_object(union wl_argument *arg)
1536	{
1537	struct wl_proxy *proxy;
1538
1539	if (arg->o) {
1540	proxy = (struct wl_proxy *)arg->o;
1541	return proxy->object.id;
1542	}
1543
1544	return 0;
1545	}
1546
1547	static void
1548	dispatch_event(struct wl_display *display, struct wl_event_queue *queue)
1549	{
1550	struct wl_closure *closure;
1551	struct wl_proxy *proxy;
1552	int opcode;
1553	bool proxy_destroyed;
1554
1555	closure = wl_container_of(queue->event_list.next, closure, link);
1556	wl_list_remove(elm: &closure->link);
1557	opcode = closure->opcode;
1558
1559	/* Verify that the receiving object is still valid by checking if has
1560	* been destroyed by the application. */
1561	validate_closure_objects(closure);
1562	proxy = closure->proxy;
1563	proxy_destroyed = !!(proxy->flags & WL_PROXY_FLAG_DESTROYED);
1564	if (proxy_destroyed) {
1565	if (debug_client)
1566	wl_closure_print(closure, target: &proxy->object, false, true, n_parse: id_from_object);
1567	destroy_queued_closure(closure);
1568	return;
1569	}
1570
1571	pthread_mutex_unlock(mutex: &display->mutex);
1572
1573	if (proxy->dispatcher) {
1574	if (debug_client)
1575	wl_closure_print(closure, target: &proxy->object, false, false, n_parse: id_from_object);
1576
1577	wl_closure_dispatch(closure, dispatcher: proxy->dispatcher,
1578	target: &proxy->object, opcode);
1579	} else if (proxy->object.implementation) {
1580	if (debug_client)
1581	wl_closure_print(closure, target: &proxy->object, false, false, n_parse: id_from_object);
1582
1583	wl_closure_invoke(closure, flags: WL_CLOSURE_INVOKE_CLIENT,
1584	target: &proxy->object, opcode, data: proxy->user_data);
1585	}
1586
1587	pthread_mutex_lock(mutex: &display->mutex);
1588
1589	destroy_queued_closure(closure);
1590	}
1591
1592	static int
1593	read_events(struct wl_display *display)
1594	{
1595	int total, rem, size;
1596	uint32_t serial;
1597
1598	display->reader_count--;
1599	if (display->reader_count == 0) {
1600	total = wl_connection_read(connection: display->connection);
1601	if (total == -1) {
1602	if (errno == EAGAIN) {
1603	/* we must wake up threads whenever
1604	* the reader_count dropped to 0 */
1605	display_wakeup_threads(display);
1606
1607	return 0;
1608	}
1609
1610	display_fatal_error(display, errno);
1611	return -1;
1612	} else if (total == 0) {
1613	/* The compositor has closed the socket. This
1614	* should be considered an error so we'll fake
1615	* an errno */
1616	errno = EPIPE;
1617	display_fatal_error(display, errno);
1618	return -1;
1619	}
1620
1621	for (rem = total; rem >= 8; rem -= size) {
1622	size = queue_event(display, len: rem);
1623	if (size == -1) {
1624	display_fatal_error(display, errno);
1625	return -1;
1626	} else if (size == 0) {
1627	break;
1628	}
1629	}
1630
1631	display_wakeup_threads(display);
1632	} else {
1633	serial = display->read_serial;
1634	while (display->read_serial == serial)
1635	pthread_cond_wait(cond: &display->reader_cond,
1636	mutex: &display->mutex);
1637
1638	if (display->last_error) {
1639	errno = display->last_error;
1640	return -1;
1641	}
1642	}
1643
1644	return 0;
1645	}
1646
1647	static void
1648	cancel_read(struct wl_display *display)
1649	{
1650	display->reader_count--;
1651	if (display->reader_count == 0)
1652	display_wakeup_threads(display);
1653	}
1654
1655	/** Read events from display file descriptor
1656	*
1657	* \param display The display context object
1658	* \return 0 on success or -1 on error. In case of error errno will
1659	* be set accordingly
1660	*
1661	* Calling this function will result in data available on the display file
1662	* descriptor being read and read events will be queued on their corresponding
1663	* event queues.
1664	*
1665	* Before calling this function, depending on what thread it is to be called
1666	* from, wl_display_prepare_read_queue() or wl_display_prepare_read() needs to
1667	* be called. See wl_display_prepare_read_queue() for more details.
1668	*
1669	* When being called at a point where other threads have been prepared to read
1670	* (using wl_display_prepare_read_queue() or wl_display_prepare_read()) this
1671	* function will sleep until all other prepared threads have either been
1672	* cancelled (using wl_display_cancel_read()) or them self entered this
1673	* function. The last thread that calls this function will then read and queue
1674	* events on their corresponding event queues, and finally wake up all other
1675	* wl_display_read_events() calls causing them to return.
1676	*
1677	* If a thread cancels a read preparation when all other threads that have
1678	* prepared to read has either called wl_display_cancel_read() or
1679	* wl_display_read_events(), all reader threads will return without having read
1680	* any data.
1681	*
1682	* To dispatch events that may have been queued, call
1683	* wl_display_dispatch_pending() or wl_display_dispatch_queue_pending().
1684	*
1685	* \sa wl_display_prepare_read(), wl_display_cancel_read(),
1686	* wl_display_dispatch_pending(), wl_display_dispatch()
1687	*
1688	* \memberof wl_display
1689	*/
1690	WL_EXPORT int
1691	wl_display_read_events(struct wl_display *display)
1692	{
1693	int ret;
1694
1695	pthread_mutex_lock(mutex: &display->mutex);
1696
1697	if (display->last_error) {
1698	cancel_read(display);
1699	pthread_mutex_unlock(mutex: &display->mutex);
1700
1701	errno = display->last_error;
1702	return -1;
1703	}
1704
1705	ret = read_events(display);
1706
1707	pthread_mutex_unlock(mutex: &display->mutex);
1708
1709	return ret;
1710	}
1711
1712	static int
1713	dispatch_queue(struct wl_display *display, struct wl_event_queue *queue)
1714	{
1715	int count;
1716
1717	if (display->last_error)
1718	goto err;
1719
1720	count = 0;
1721	while (!wl_list_empty(list: &display->display_queue.event_list)) {
1722	dispatch_event(display, queue: &display->display_queue);
1723	if (display->last_error)
1724	goto err;
1725	count++;
1726	}
1727
1728	while (!wl_list_empty(list: &queue->event_list)) {
1729	dispatch_event(display, queue);
1730	if (display->last_error)
1731	goto err;
1732	count++;
1733	}
1734
1735	return count;
1736
1737	err:
1738	errno = display->last_error;
1739
1740	return -1;
1741	}
1742
1743	/** Prepare to read events from the display's file descriptor to a queue
1744	*
1745	* \param display The display context object
1746	* \param queue The event queue to use
1747	* \return 0 on success or -1 if event queue was not empty
1748	*
1749	* This function (or wl_display_prepare_read()) must be called before reading
1750	* from the file descriptor using wl_display_read_events(). Calling
1751	* wl_display_prepare_read_queue() announces the calling thread's intention to
1752	* read and ensures that until the thread is ready to read and calls
1753	* wl_display_read_events(), no other thread will read from the file descriptor.
1754	* This only succeeds if the event queue is empty, and if not -1 is returned and
1755	* errno set to EAGAIN.
1756	*
1757	* If a thread successfully calls wl_display_prepare_read_queue(), it must
1758	* either call wl_display_read_events() when it's ready or cancel the read
1759	* intention by calling wl_display_cancel_read().
1760	*
1761	* Use this function before polling on the display fd or integrate the fd into a
1762	* toolkit event loop in a race-free way. A correct usage would be (with most
1763	* error checking left out):
1764	*
1765	* \code
1766	* while (wl_display_prepare_read_queue(display, queue) != 0)
1767	* wl_display_dispatch_queue_pending(display, queue);
1768	* wl_display_flush(display);
1769	*
1770	* ret = poll(fds, nfds, -1);
1771	* if (has_error(ret))
1772	* wl_display_cancel_read(display);
1773	* else
1774	* wl_display_read_events(display);
1775	*
1776	* wl_display_dispatch_queue_pending(display, queue);
1777	* \endcode
1778	*
1779	* Here we call wl_display_prepare_read_queue(), which ensures that between
1780	* returning from that call and eventually calling wl_display_read_events(), no
1781	* other thread will read from the fd and queue events in our queue. If the call
1782	* to wl_display_prepare_read_queue() fails, we dispatch the pending events and
1783	* try again until we're successful.
1784	*
1785	* The wl_display_prepare_read_queue() function doesn't acquire exclusive access
1786	* to the display's fd. It only registers that the thread calling this function
1787	* has intention to read from fd. When all registered readers call
1788	* wl_display_read_events(), only one (at random) eventually reads and queues
1789	* the events and the others are sleeping meanwhile. This way we avoid races and
1790	* still can read from more threads.
1791	*
1792	* \sa wl_display_cancel_read(), wl_display_read_events(),
1793	* wl_display_prepare_read()
1794	*
1795	* \memberof wl_display
1796	*/
1797	WL_EXPORT int
1798	wl_display_prepare_read_queue(struct wl_display *display,
1799	struct wl_event_queue *queue)
1800	{
1801	int ret;
1802
1803	pthread_mutex_lock(mutex: &display->mutex);
1804
1805	if (!wl_list_empty(list: &queue->event_list)) {
1806	errno = EAGAIN;
1807	ret = -1;
1808	} else {
1809	display->reader_count++;
1810	ret = 0;
1811	}
1812
1813	pthread_mutex_unlock(mutex: &display->mutex);
1814
1815	return ret;
1816	}
1817
1818	/** Prepare to read events from the display's file descriptor
1819	*
1820	* \param display The display context object
1821	* \return 0 on success or -1 if event queue was not empty
1822	*
1823	* This function does the same thing as wl_display_prepare_read_queue()
1824	* with the default queue passed as the queue.
1825	*
1826	* \sa wl_display_prepare_read_queue
1827	* \memberof wl_display
1828	*/
1829	WL_EXPORT int
1830	wl_display_prepare_read(struct wl_display *display)
1831	{
1832	return wl_display_prepare_read_queue(display, queue: &display->default_queue);
1833	}
1834
1835	/** Cancel read intention on display's fd
1836	*
1837	* \param display The display context object
1838	*
1839	* After a thread successfully called wl_display_prepare_read() it must
1840	* either call wl_display_read_events() or wl_display_cancel_read().
1841	* If the threads do not follow this rule it will lead to deadlock.
1842	*
1843	* \sa wl_display_prepare_read(), wl_display_read_events()
1844	*
1845	* \memberof wl_display
1846	*/
1847	WL_EXPORT void
1848	wl_display_cancel_read(struct wl_display *display)
1849	{
1850	pthread_mutex_lock(mutex: &display->mutex);
1851
1852	cancel_read(display);
1853
1854	pthread_mutex_unlock(mutex: &display->mutex);
1855	}
1856
1857	static int
1858	wl_display_poll(struct wl_display *display, short int events)
1859	{
1860	int ret;
1861	struct pollfd pfd[1];
1862
1863	pfd[0].fd = display->fd;
1864	pfd[0].events = events;
1865	do {
1866	ret = poll(fds: pfd, nfds: 1, timeout: -1);
1867	} while (ret == -1 && errno == EINTR);
1868
1869	return ret;
1870	}
1871
1872	/** Dispatch events in an event queue
1873	*
1874	* \param display The display context object
1875	* \param queue The event queue to dispatch
1876	* \return The number of dispatched events on success or -1 on failure
1877	*
1878	* Dispatch events on the given event queue.
1879	*
1880	* If the given event queue is empty, this function blocks until there are
1881	* events to be read from the display fd. Events are read and queued on
1882	* the appropriate event queues. Finally, events on given event queue are
1883	* dispatched. On failure -1 is returned and errno set appropriately.
1884	*
1885	* In a multi threaded environment, do not manually wait using poll() (or
1886	* equivalent) before calling this function, as doing so might cause a dead
1887	* lock. If external reliance on poll() (or equivalent) is required, see
1888	* wl_display_prepare_read_queue() of how to do so.
1889	*
1890	* This function is thread safe as long as it dispatches the right queue on the
1891	* right thread. It is also compatible with the multi thread event reading
1892	* preparation API (see wl_display_prepare_read_queue()), and uses the
1893	* equivalent functionality internally. It is not allowed to call this function
1894	* while the thread is being prepared for reading events, and doing so will
1895	* cause a dead lock.
1896	*
1897	* It can be used as a helper function to ease the procedure of reading and
1898	* dispatching events.
1899	*
1900	* \note Since Wayland 1.5 the display has an extra queue
1901	* for its own events (i. e. delete_id). This queue is dispatched always,
1902	* no matter what queue we passed as an argument to this function.
1903	* That means that this function can return non-0 value even when it
1904	* haven't dispatched any event for the given queue.
1905	*
1906	* \sa wl_display_dispatch(), wl_display_dispatch_pending(),
1907	* wl_display_dispatch_queue_pending(), wl_display_prepare_read_queue()
1908	*
1909	* \memberof wl_display
1910	*/
1911	WL_EXPORT int
1912	wl_display_dispatch_queue(struct wl_display *display,
1913	struct wl_event_queue *queue)
1914	{
1915	int ret;
1916
1917	if (wl_display_prepare_read_queue(display, queue) == -1)
1918	return wl_display_dispatch_queue_pending(display, queue);
1919
1920	while (true) {
1921	ret = wl_display_flush(display);
1922
1923	if (ret != -1 || errno != EAGAIN)
1924	break;
1925
1926	if (wl_display_poll(display, POLLOUT) == -1) {
1927	wl_display_cancel_read(display);
1928	return -1;
1929	}
1930	}
1931
1932	/* Don't stop if flushing hits an EPIPE; continue so we can read any
1933	* protocol error that may have triggered it. */
1934	if (ret < 0 && errno != EPIPE) {
1935	wl_display_cancel_read(display);
1936	return -1;
1937	}
1938
1939	if (wl_display_poll(display, POLLIN) == -1) {
1940	wl_display_cancel_read(display);
1941	return -1;
1942	}
1943
1944	if (wl_display_read_events(display) == -1)
1945	return -1;
1946
1947	return wl_display_dispatch_queue_pending(display, queue);
1948	}
1949
1950	/** Dispatch pending events in an event queue
1951	*
1952	* \param display The display context object
1953	* \param queue The event queue to dispatch
1954	* \return The number of dispatched events on success or -1 on failure
1955	*
1956	* Dispatch all incoming events for objects assigned to the given
1957	* event queue. On failure -1 is returned and errno set appropriately.
1958	* If there are no events queued, this function returns immediately.
1959	*
1960	* \memberof wl_display
1961	* \since 1.0.2
1962	*/
1963	WL_EXPORT int
1964	wl_display_dispatch_queue_pending(struct wl_display *display,
1965	struct wl_event_queue *queue)
1966	{
1967	int ret;
1968
1969	pthread_mutex_lock(mutex: &display->mutex);
1970
1971	ret = dispatch_queue(display, queue);
1972
1973	pthread_mutex_unlock(mutex: &display->mutex);
1974
1975	return ret;
1976	}
1977
1978	/** Process incoming events
1979	*
1980	* \param display The display context object
1981	* \return The number of dispatched events on success or -1 on failure
1982	*
1983	* Dispatch events on the default event queue.
1984	*
1985	* If the default event queue is empty, this function blocks until there are
1986	* events to be read from the display fd. Events are read and queued on
1987	* the appropriate event queues. Finally, events on the default event queue
1988	* are dispatched. On failure -1 is returned and errno set appropriately.
1989	*
1990	* In a multi threaded environment, do not manually wait using poll() (or
1991	* equivalent) before calling this function, as doing so might cause a dead
1992	* lock. If external reliance on poll() (or equivalent) is required, see
1993	* wl_display_prepare_read_queue() of how to do so.
1994	*
1995	* This function is thread safe as long as it dispatches the right queue on the
1996	* right thread. It is also compatible with the multi thread event reading
1997	* preparation API (see wl_display_prepare_read_queue()), and uses the
1998	* equivalent functionality internally. It is not allowed to call this function
1999	* while the thread is being prepared for reading events, and doing so will
2000	* cause a dead lock.
2001	*
2002	* \note It is not possible to check if there are events on the queue
2003	* or not. For dispatching default queue events without blocking, see \ref
2004	* wl_display_dispatch_pending().
2005	*
2006	* \sa wl_display_dispatch_pending(), wl_display_dispatch_queue(),
2007	* wl_display_read_events()
2008	*
2009	* \memberof wl_display
2010	*/
2011	WL_EXPORT int
2012	wl_display_dispatch(struct wl_display *display)
2013	{
2014	return wl_display_dispatch_queue(display, queue: &display->default_queue);
2015	}
2016
2017	/** Dispatch default queue events without reading from the display fd
2018	*
2019	* \param display The display context object
2020	* \return The number of dispatched events or -1 on failure
2021	*
2022	* This function dispatches events on the main event queue. It does not
2023	* attempt to read the display fd and simply returns zero if the main
2024	* queue is empty, i.e., it doesn't block.
2025	*
2026	* \sa wl_display_dispatch(), wl_display_dispatch_queue(),
2027	* wl_display_flush()
2028	*
2029	* \memberof wl_display
2030	*/
2031	WL_EXPORT int
2032	wl_display_dispatch_pending(struct wl_display *display)
2033	{
2034	return wl_display_dispatch_queue_pending(display,
2035	queue: &display->default_queue);
2036	}
2037
2038	/** Retrieve the last error that occurred on a display
2039	*
2040	* \param display The display context object
2041	* \return The last error that occurred on \c display or 0 if no error occurred
2042	*
2043	* Return the last error that occurred on the display. This may be an error sent
2044	* by the server or caused by the local client.
2045	*
2046	* \note Errors are \b fatal. If this function returns non-zero the display
2047	* can no longer be used.
2048	*
2049	* \memberof wl_display
2050	*/
2051	WL_EXPORT int
2052	wl_display_get_error(struct wl_display *display)
2053	{
2054	int ret;
2055
2056	pthread_mutex_lock(mutex: &display->mutex);
2057
2058	ret = display->last_error;
2059
2060	pthread_mutex_unlock(mutex: &display->mutex);
2061
2062	return ret;
2063	}
2064
2065	/** Retrieves the information about a protocol error:
2066	*
2067	* \param display The Wayland display
2068	* \param interface if not NULL, stores the interface where the error occurred,
2069	* or NULL, if unknown.
2070	* \param id if not NULL, stores the object id that generated
2071	* the error, or 0, if the object id is unknown. There's no
2072	* guarantee the object is still valid; the client must know
2073	* if it deleted the object.
2074	* \return The error code as defined in the interface specification.
2075	*
2076	* \code
2077	* int err = wl_display_get_error(display);
2078	*
2079	* if (err == EPROTO) {
2080	* code = wl_display_get_protocol_error(display, &interface, &id);
2081	* handle_error(code, interface, id);
2082	* }
2083	*
2084	* ...
2085	* \endcode
2086	* \memberof wl_display
2087	*/
2088	WL_EXPORT uint32_t
2089	wl_display_get_protocol_error(struct wl_display *display,
2090	const struct wl_interface **interface,
2091	uint32_t *id)
2092	{
2093	uint32_t ret;
2094
2095	pthread_mutex_lock(mutex: &display->mutex);
2096
2097	ret = display->protocol_error.code;
2098
2099	if (interface)
2100	*interface = display->protocol_error.interface;
2101	if (id)
2102	*id = display->protocol_error.id;
2103
2104	pthread_mutex_unlock(mutex: &display->mutex);
2105
2106	return ret;
2107	}
2108
2109
2110	/** Send all buffered requests on the display to the server
2111	*
2112	* \param display The display context object
2113	* \return The number of bytes sent on success or -1 on failure
2114	*
2115	* Send all buffered data on the client side to the server. Clients should
2116	* always call this function before blocking on input from the display fd.
2117	* On success, the number of bytes sent to the server is returned. On
2118	* failure, this function returns -1 and errno is set appropriately.
2119	*
2120	* wl_display_flush() never blocks. It will write as much data as
2121	* possible, but if all data could not be written, errno will be set
2122	* to EAGAIN and -1 returned. In that case, use poll on the display
2123	* file descriptor to wait for it to become writable again.
2124	*
2125	* \memberof wl_display
2126	*/
2127	WL_EXPORT int
2128	wl_display_flush(struct wl_display *display)
2129	{
2130	int ret;
2131
2132	pthread_mutex_lock(mutex: &display->mutex);
2133
2134	if (display->last_error) {
2135	errno = display->last_error;
2136	ret = -1;
2137	} else {
2138	/* We don't make EPIPE a fatal error here, so that we may try to
2139	* read events after the failed flush. When the compositor sends
2140	* an error it will close the socket, and if we make EPIPE fatal
2141	* here we don't get a chance to process the error. */
2142	ret = wl_connection_flush(connection: display->connection);
2143	if (ret < 0 && errno != EAGAIN && errno != EPIPE)
2144	display_fatal_error(display, errno);
2145	}
2146
2147	pthread_mutex_unlock(mutex: &display->mutex);
2148
2149	return ret;
2150	}
2151
2152	/** Set the user data associated with a proxy
2153	*
2154	* \param proxy The proxy object
2155	* \param user_data The data to be associated with proxy
2156	*
2157	* Set the user data associated with \c proxy. When events for this
2158	* proxy are received, \c user_data will be supplied to its listener.
2159	*
2160	* \memberof wl_proxy
2161	*/
2162	WL_EXPORT void
2163	wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data)
2164	{
2165	proxy->user_data = user_data;
2166	}
2167
2168	/** Get the user data associated with a proxy
2169	*
2170	* \param proxy The proxy object
2171	* \return The user data associated with proxy
2172	*
2173	* \memberof wl_proxy
2174	*/
2175	WL_EXPORT void *
2176	wl_proxy_get_user_data(struct wl_proxy *proxy)
2177	{
2178	return proxy->user_data;
2179	}
2180
2181	/** Get the protocol object version of a proxy object
2182	*
2183	* \param proxy The proxy object
2184	* \return The protocol object version of the proxy or 0
2185	*
2186	* Gets the protocol object version of a proxy object, or 0
2187	* if the proxy was created with unversioned API.
2188	*
2189	* A returned value of 0 means that no version information is
2190	* available, so the caller must make safe assumptions about
2191	* the object's real version.
2192	*
2193	* wl_display's version will always return 0.
2194	*
2195	* \memberof wl_proxy
2196	*/
2197	WL_EXPORT uint32_t
2198	wl_proxy_get_version(struct wl_proxy *proxy)
2199	{
2200	return proxy->version;
2201	}
2202
2203	/** Get the id of a proxy object
2204	*
2205	* \param proxy The proxy object
2206	* \return The id the object associated with the proxy
2207	*
2208	* \memberof wl_proxy
2209	*/
2210	WL_EXPORT uint32_t
2211	wl_proxy_get_id(struct wl_proxy *proxy)
2212	{
2213	return proxy->object.id;
2214	}
2215
2216	/** Set the tag of a proxy object
2217	*
2218	* A toolkit or application can set a unique tag on a proxy in order to
2219	* identify whether an object is managed by itself or some external part.
2220	*
2221	* To create a tag, the recommended way is to define a statically allocated
2222	* constant char array containing some descriptive string. The tag will be the
2223	* pointer to the non-const pointer to the beginning of the array.
2224	*
2225	* For example, to define and set a tag on a surface managed by a certain
2226	* subsystem:
2227	*
2228	* static const char *my_tag = "my tag";
2229	*
2230	* wl_proxy_set_tag((struct wl_proxy *) surface, &my_tag);
2231	*
2232	* Then, in a callback with wl_surface as an argument, in order to check
2233	* whether it's a surface managed by the same subsystem.
2234	*
2235	* const char * const *tag;
2236	*
2237	* tag = wl_proxy_get_tag((struct wl_proxy *) surface);
2238	* if (tag != &my_tag)
2239	* return;
2240	*
2241	* ...
2242	*
2243	* For debugging purposes, a tag should be suitable to be included in a debug
2244	* log entry, e.g.
2245	*
2246	* const char * const *tag;
2247	*
2248	* tag = wl_proxy_get_tag((struct wl_proxy *) surface);
2249	* printf("Got a surface with the tag %p (%s)\n",
2250	* tag, (tag && *tag) ? *tag : "");
2251	*
2252	* \param proxy The proxy object
2253	* \param tag The tag
2254	*
2255	* \memberof wl_proxy
2256	* \since 1.17.90
2257	*/
2258	WL_EXPORT void
2259	wl_proxy_set_tag(struct wl_proxy *proxy,
2260	const char * const *tag)
2261	{
2262	proxy->tag = tag;
2263	}
2264
2265	/** Get the tag of a proxy object
2266	*
2267	* See wl_proxy_set_tag for details.
2268	*
2269	* \param proxy The proxy object
2270	*
2271	* \memberof wl_proxy
2272	* \since 1.17.90
2273	*/
2274	WL_EXPORT const char * const *
2275	wl_proxy_get_tag(struct wl_proxy *proxy)
2276	{
2277	return proxy->tag;
2278	}
2279
2280	/** Get the interface name (class) of a proxy object
2281	*
2282	* \param proxy The proxy object
2283	* \return The interface name of the object associated with the proxy
2284	*
2285	* \memberof wl_proxy
2286	*/
2287	WL_EXPORT const char *
2288	wl_proxy_get_class(struct wl_proxy *proxy)
2289	{
2290	return proxy->object.interface->name;
2291	}
2292
2293	/** Assign a proxy to an event queue
2294	*
2295	* \param proxy The proxy object
2296	* \param queue The event queue that will handle this proxy or NULL
2297	*
2298	* Assign proxy to event queue. Events coming from \c proxy will be
2299	* queued in \c queue from now. If queue is NULL, then the display's
2300	* default queue is set to the proxy.
2301	*
2302	* \note By default, the queue set in proxy is the one inherited from parent.
2303	*
2304	* \sa wl_display_dispatch_queue()
2305	*
2306	* \memberof wl_proxy
2307	*/
2308	WL_EXPORT void
2309	wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue)
2310	{
2311	if (queue) {
2312	assert(proxy->display == queue->display);
2313	proxy->queue = queue;
2314	} else {
2315	proxy->queue = &proxy->display->default_queue;
2316	}
2317	}
2318
2319	/** Create a proxy wrapper for making queue assignments thread-safe
2320	*
2321	* \param proxy The proxy object to be wrapped
2322	* \return A proxy wrapper for the given proxy or NULL on failure
2323	*
2324	* A proxy wrapper is type of 'struct wl_proxy' instance that can be used when
2325	* sending requests instead of using the original proxy. A proxy wrapper does
2326	* not have an implementation or dispatcher, and events received on the
2327	* object is still emitted on the original proxy. Trying to set an
2328	* implementation or dispatcher will have no effect but result in a warning
2329	* being logged.
2330	*
2331	* Setting the proxy queue of the proxy wrapper will make new objects created
2332	* using the proxy wrapper use the set proxy queue.
2333	* Even though there is no implementation nor dispatcher, the proxy queue can
2334	* be changed. This will affect the default queue of new objects created by
2335	* requests sent via the proxy wrapper.
2336	*
2337	* A proxy wrapper can only be destroyed using wl_proxy_wrapper_destroy().
2338	*
2339	* A proxy wrapper must be destroyed before the proxy it was created from.
2340	*
2341	* If a user reads and dispatches events on more than one thread, it is
2342	* necessary to use a proxy wrapper when sending requests on objects when the
2343	* intention is that a newly created proxy is to use a proxy queue different
2344	* from the proxy the request was sent on, as creating the new proxy and then
2345	* setting the queue is not thread safe.
2346	*
2347	* For example, a module that runs using its own proxy queue that needs to
2348	* do display roundtrip must wrap the wl_display proxy object before sending
2349	* the wl_display.sync request. For example:
2350	*
2351	* \code
2352	*
2353	* struct wl_event_queue *queue = ...;
2354	* struct wl_display *wrapped_display;
2355	* struct wl_callback *callback;
2356	*
2357	* wrapped_display = wl_proxy_create_wrapper(display);
2358	* wl_proxy_set_queue((struct wl_proxy *) wrapped_display, queue);
2359	* callback = wl_display_sync(wrapped_display);
2360	* wl_proxy_wrapper_destroy(wrapped_display);
2361	* wl_callback_add_listener(callback, ...);
2362	*
2363	* \endcode
2364	*
2365	* \memberof wl_proxy
2366	*/
2367	WL_EXPORT void *
2368	wl_proxy_create_wrapper(void *proxy)
2369	{
2370	struct wl_proxy *wrapped_proxy = proxy;
2371	struct wl_proxy *wrapper;
2372
2373	wrapper = zalloc(s: sizeof *wrapper);
2374	if (!wrapper)
2375	return NULL;
2376
2377	pthread_mutex_lock(mutex: &wrapped_proxy->display->mutex);
2378
2379	wrapper->object.interface = wrapped_proxy->object.interface;
2380	wrapper->object.id = wrapped_proxy->object.id;
2381	wrapper->version = wrapped_proxy->version;
2382	wrapper->display = wrapped_proxy->display;
2383	wrapper->queue = wrapped_proxy->queue;
2384	wrapper->flags = WL_PROXY_FLAG_WRAPPER;
2385	wrapper->refcount = 1;
2386
2387	pthread_mutex_unlock(mutex: &wrapped_proxy->display->mutex);
2388
2389	return wrapper;
2390	}
2391
2392	/** Destroy a proxy wrapper
2393	* \param proxy_wrapper The proxy wrapper to be destroyed
2394	*
2395	* \memberof wl_proxy
2396	*/
2397	WL_EXPORT void
2398	wl_proxy_wrapper_destroy(void *proxy_wrapper)
2399	{
2400	struct wl_proxy *wrapper = proxy_wrapper;
2401
2402	if (!(wrapper->flags & WL_PROXY_FLAG_WRAPPER))
2403	wl_abort(fmt: "Tried to destroy non-wrapper proxy with "
2404	"wl_proxy_wrapper_destroy\n");
2405
2406	assert(wrapper->refcount == 1);
2407
2408	free(ptr: wrapper);
2409	}
2410
2411	WL_EXPORT void
2412	wl_log_set_handler_client(wl_log_func_t handler)
2413	{
2414	wl_log_handler = handler;
2415	}
2416