2 * Copyright © 2011 Canonical Limited
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the licence, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Author: Ryan Lortie <desrt@desrt.ca>
25 /* gwakeup.h is special -- GIO and some test cases include it. As such,
26 * it cannot include other glib headers without triggering the single
27 * includes warnings. We have to manually include its dependencies here
28 * (and at all other use sites).
30 #ifdef GLIB_COMPILATION
42 * @short_description: portable cross-thread event signal mechanism
44 * #GWakeup is a simple and portable way of signaling events between
45 * different threads in a way that integrates nicely with g_poll().
46 * GLib uses it internally for cross-thread signalling in the
47 * implementation of #GMainContext and #GCancellable.
49 * You first create a #GWakeup with g_wakeup_new() and initialise a
50 * #GPollFD from it using g_wakeup_get_pollfd(). Polling on the created
51 * #GPollFD will block until g_wakeup_signal() is called, at which point
52 * it will immediately return. Future attempts to poll will continue to
53 * return until g_wakeup_acknowledge() is called. g_wakeup_free() is
54 * used to free a #GWakeup.
56 * On sufficiently modern Linux, this is implemented using eventfd. On
57 * Windows it is implemented using an event handle. On other systems it
58 * is implemented with a pair of pipes.
65 #include "gmessages.h"
66 #include "giochannel.h"
74 wakeup = CreateEvent (NULL, TRUE, FALSE, NULL);
77 g_error ("Cannot create event for GWakeup: %s",
78 g_win32_error_message (GetLastError ()));
80 return (GWakeup *) wakeup;
84 g_wakeup_get_pollfd (GWakeup *wakeup,
87 poll_fd->fd = (gintptr) wakeup;
88 poll_fd->events = G_IO_IN;
92 g_wakeup_acknowledge (GWakeup *wakeup)
94 ResetEvent ((HANDLE) wakeup);
98 g_wakeup_signal (GWakeup *wakeup)
100 SetEvent ((HANDLE) wakeup);
104 g_wakeup_free (GWakeup *wakeup)
106 CloseHandle ((HANDLE) wakeup);
111 #include "glib-unix.h"
114 #if defined (HAVE_EVENTFD)
115 #include <sys/eventfd.h>
126 * Creates a new #GWakeup.
128 * You should use g_wakeup_free() to free it when you are done.
130 * Returns: a new #GWakeup
137 GError *error = NULL;
140 wakeup = g_slice_new (GWakeup);
142 /* try eventfd first, if we think we can */
143 #if defined (HAVE_EVENTFD)
144 #ifndef TEST_EVENTFD_FALLBACK
145 wakeup->fds[0] = eventfd (0, EFD_CLOEXEC | EFD_NONBLOCK);
150 if (wakeup->fds[0] != -1)
156 /* for any failure, try a pipe instead */
159 if (!g_unix_open_pipe (wakeup->fds, FD_CLOEXEC, &error))
160 g_error ("Creating pipes for GWakeup: %s\n", error->message);
162 if (!g_unix_set_fd_nonblocking (wakeup->fds[0], TRUE, &error) ||
163 !g_unix_set_fd_nonblocking (wakeup->fds[1], TRUE, &error))
164 g_error ("Set pipes non-blocking for GWakeup: %s\n", error->message);
170 * g_wakeup_get_pollfd:
171 * @wakeup: a #GWakeup
172 * @poll_fd: a #GPollFD
174 * Prepares a @poll_fd such that polling on it will succeed when
175 * g_wakeup_signal() has been called on @wakeup.
177 * @poll_fd is valid until @wakeup is freed.
182 g_wakeup_get_pollfd (GWakeup *wakeup,
185 poll_fd->fd = wakeup->fds[0];
186 poll_fd->events = G_IO_IN;
190 * g_wakeup_acknowledge:
191 * @wakeup: a #GWakeup
193 * Acknowledges receipt of a wakeup signal on @wakeup.
195 * You must call this after @wakeup polls as ready. If not, it will
196 * continue to poll as ready until you do so.
198 * If you call this function and @wakeup is not signaled, nothing
204 g_wakeup_acknowledge (GWakeup *wakeup)
208 /* read until it is empty */
209 while (read (wakeup->fds[0], buffer, sizeof buffer) == sizeof buffer);
214 * @wakeup: a #GWakeup
218 * Any future (or present) polling on the #GPollFD returned by
219 * g_wakeup_get_pollfd() will immediately succeed until such a time as
220 * g_wakeup_acknowledge() is called.
222 * This function is safe to call from a UNIX signal handler.
227 g_wakeup_signal (GWakeup *wakeup)
231 if (wakeup->fds[1] == -1)
232 write (wakeup->fds[0], &one, sizeof one);
234 write (wakeup->fds[1], &one, 1);
239 * @wakeup: a #GWakeup
243 * You must not currently be polling on the #GPollFD returned by
244 * g_wakeup_get_pollfd(), or the result is undefined.
247 g_wakeup_free (GWakeup *wakeup)
249 close (wakeup->fds[0]);
251 if (wakeup->fds[1] != -1)
252 close (wakeup->fds[1]);
254 g_slice_free (GWakeup, wakeup);