1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-timeout.c DBusTimeout implementation
4 * Copyright (C) 2003 CodeFactory AB
6 * Licensed under the Academic Free License version 1.2
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "dbus-internals.h"
25 #include "dbus-timeout.h"
26 #include "dbus-list.h"
29 * @defgroup DBusTimeoutInternals DBusTimeout implementation details
30 * @ingroup DBusInternals
31 * @brief implementation details for DBusTimeout
37 * Internals of DBusTimeout
41 int refcount; /**< Reference count */
42 int interval; /**< Timeout interval in milliseconds. */
44 DBusTimeoutHandler handler; /**< Timeout handler. */
45 void *handler_data; /**< Timeout handler data. */
46 DBusFreeFunction free_handler_data_function; /**< Free the timeout handler data. */
48 void *data; /**< Application data. */
49 DBusFreeFunction free_data_function; /**< Free the application data. */
50 unsigned int enabled : 1; /**< True if timeout is active. */
54 * Creates a new DBusTimeout, enabled by default.
55 * @param interval the timeout interval in milliseconds.
56 * @param handler function to call when the timeout occurs.
57 * @param data data to pass to the handler
58 * @param free_data_function function to be called to free the data.
59 * @returns the new DBusTimeout object,
62 _dbus_timeout_new (int interval,
63 DBusTimeoutHandler handler,
65 DBusFreeFunction free_data_function)
69 timeout = dbus_new0 (DBusTimeout, 1);
73 timeout->refcount = 1;
74 timeout->interval = interval;
76 timeout->handler = handler;
77 timeout->handler_data = data;
78 timeout->free_handler_data_function = free_data_function;
80 timeout->enabled = TRUE;
86 * Increments the reference count of a DBusTimeout object.
88 * @param timeout the timeout object.
91 _dbus_timeout_ref (DBusTimeout *timeout)
93 timeout->refcount += 1;
97 * Decrements the reference count of a DBusTimeout object
98 * and finalizes the object if the count reaches zero.
100 * @param timeout the timeout object.
103 _dbus_timeout_unref (DBusTimeout *timeout)
105 _dbus_assert (timeout != NULL);
106 _dbus_assert (timeout->refcount > 0);
108 timeout->refcount -= 1;
109 if (timeout->refcount == 0)
111 dbus_timeout_set_data (timeout, NULL, NULL); /* call free_data_function */
113 if (timeout->free_handler_data_function)
114 (* timeout->free_handler_data_function) (timeout->handler_data);
121 * Changes the timeout interval. Note that you have to disable and
122 * re-enable the timeout using the timeout toggle function
123 * (_dbus_connection_toggle_timeout() etc.) to notify the application
126 * @param timeout the timeout
127 * @param interval the new interval
130 _dbus_timeout_set_interval (DBusTimeout *timeout,
133 _dbus_assert (interval >= 0);
135 timeout->interval = interval;
139 * Changes the timeout's enabled-ness. Note that you should use
140 * _dbus_connection_toggle_timeout() etc. instead, if
141 * the timeout is passed out to an application main loop.
142 * i.e. you can't use this function in the D-BUS library, it's
143 * only used in the message bus daemon implementation.
145 * @param timeout the timeout
146 * @param enabled #TRUE if timeout should be enabled.
149 _dbus_timeout_set_enabled (DBusTimeout *timeout,
152 timeout->enabled = enabled != FALSE;
157 * @typedef DBusTimeoutList
159 * Opaque data type representing a list of timeouts
160 * and a set of DBusAddTimeoutFunction/DBusRemoveTimeoutFunction.
161 * Automatically handles removing/re-adding timeouts
162 * when the DBusAddTimeoutFunction is updated or changed.
163 * Holds a reference count to each timeout.
168 * DBusTimeoutList implementation details. All fields
172 struct DBusTimeoutList
174 DBusList *timeouts; /**< Timeout objects. */
176 DBusAddTimeoutFunction add_timeout_function; /**< Callback for adding a timeout. */
177 DBusRemoveTimeoutFunction remove_timeout_function; /**< Callback for removing a timeout. */
178 DBusTimeoutToggledFunction timeout_toggled_function; /**< Callback when timeout is enabled/disabled or changes interval */
179 void *timeout_data; /**< Data for timeout callbacks */
180 DBusFreeFunction timeout_free_data_function; /**< Free function for timeout callback data */
184 * Creates a new timeout list. Returns #NULL if insufficient
187 * @returns the new timeout list, or #NULL on failure.
190 _dbus_timeout_list_new (void)
192 DBusTimeoutList *timeout_list;
194 timeout_list = dbus_new0 (DBusTimeoutList, 1);
195 if (timeout_list == NULL)
202 * Frees a DBusTimeoutList.
204 * @param timeout_list the timeout list.
207 _dbus_timeout_list_free (DBusTimeoutList *timeout_list)
209 /* free timeout_data and remove timeouts as a side effect */
210 _dbus_timeout_list_set_functions (timeout_list,
211 NULL, NULL, NULL, NULL, NULL);
213 _dbus_list_foreach (&timeout_list->timeouts,
214 (DBusForeachFunction) _dbus_timeout_unref,
216 _dbus_list_clear (&timeout_list->timeouts);
218 dbus_free (timeout_list);
222 * Sets the timeout functions. This function is the "backend"
223 * for dbus_connection_set_timeout_functions().
225 * @param timeout_list the timeout list
226 * @param add_function the add timeout function.
227 * @param remove_function the remove timeout function.
228 * @param toggled_function toggle notify function, or #NULL
229 * @param data the data for those functions.
230 * @param free_data_function the function to free the data.
231 * @returns #FALSE if no memory
235 _dbus_timeout_list_set_functions (DBusTimeoutList *timeout_list,
236 DBusAddTimeoutFunction add_function,
237 DBusRemoveTimeoutFunction remove_function,
238 DBusTimeoutToggledFunction toggled_function,
240 DBusFreeFunction free_data_function)
242 /* Add timeouts with the new function, failing on OOM */
243 if (add_function != NULL)
247 link = _dbus_list_get_first_link (&timeout_list->timeouts);
250 DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
253 if (!(* add_function) (link->data, data))
255 /* remove it all again and return FALSE */
258 link2 = _dbus_list_get_first_link (&timeout_list->timeouts);
259 while (link2 != link)
261 DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
264 (* remove_function) (link2->data, data);
276 /* Remove all current timeouts from previous timeout handlers */
278 if (timeout_list->remove_timeout_function != NULL)
280 _dbus_list_foreach (&timeout_list->timeouts,
281 (DBusForeachFunction) timeout_list->remove_timeout_function,
282 timeout_list->timeout_data);
285 if (timeout_list->timeout_free_data_function != NULL)
286 (* timeout_list->timeout_free_data_function) (timeout_list->timeout_data);
288 timeout_list->add_timeout_function = add_function;
289 timeout_list->remove_timeout_function = remove_function;
290 timeout_list->timeout_toggled_function = toggled_function;
291 timeout_list->timeout_data = data;
292 timeout_list->timeout_free_data_function = free_data_function;
298 * Adds a new timeout to the timeout list, invoking the
299 * application DBusAddTimeoutFunction if appropriate.
301 * @param timeout_list the timeout list.
302 * @param timeout the timeout to add.
303 * @returns #TRUE on success, #FALSE If no memory.
306 _dbus_timeout_list_add_timeout (DBusTimeoutList *timeout_list,
307 DBusTimeout *timeout)
309 if (!_dbus_list_append (&timeout_list->timeouts, timeout))
312 _dbus_timeout_ref (timeout);
314 if (timeout_list->add_timeout_function != NULL)
316 if (!(* timeout_list->add_timeout_function) (timeout,
317 timeout_list->timeout_data))
319 _dbus_list_remove_last (&timeout_list->timeouts, timeout);
320 _dbus_timeout_unref (timeout);
329 * Removes a timeout from the timeout list, invoking the
330 * application's DBusRemoveTimeoutFunction if appropriate.
332 * @param timeout_list the timeout list.
333 * @param timeout the timeout to remove.
336 _dbus_timeout_list_remove_timeout (DBusTimeoutList *timeout_list,
337 DBusTimeout *timeout)
339 if (!_dbus_list_remove (&timeout_list->timeouts, timeout))
340 _dbus_assert_not_reached ("Nonexistent timeout was removed");
342 if (timeout_list->remove_timeout_function != NULL)
343 (* timeout_list->remove_timeout_function) (timeout,
344 timeout_list->timeout_data);
346 _dbus_timeout_unref (timeout);
350 * Sets a timeout to the given enabled state, invoking the
351 * application's DBusTimeoutToggledFunction if appropriate.
353 * @param timeout_list the timeout list.
354 * @param timeout the timeout to toggle.
355 * @param enabled #TRUE to enable
358 _dbus_timeout_list_toggle_timeout (DBusTimeoutList *timeout_list,
359 DBusTimeout *timeout,
364 if (enabled == timeout->enabled)
367 timeout->enabled = enabled;
369 if (timeout_list->timeout_toggled_function != NULL)
370 (* timeout_list->timeout_toggled_function) (timeout,
371 timeout_list->timeout_data);
377 * @defgroup DBusTimeout DBusTimeout
379 * @brief Object representing a timeout
381 * Types and functions related to DBusTimeout. A timeout
382 * represents a timeout that the main loop needs to monitor,
383 * as in Qt's QTimer or GLib's g_timeout_add().
390 * @typedef DBusTimeout
392 * Opaque object representing a timeout.
396 * Gets the timeout interval. The dbus_timeout_handle()
397 * should be called each time this interval elapses,
398 * starting after it elapses once.
400 * The interval may change during the life of the
401 * timeout; if so, the timeout will be disabled and
402 * re-enabled (calling the "timeout toggled function")
403 * to notify you of the change.
405 * @param timeout the DBusTimeout object.
406 * @returns the interval in milliseconds.
409 dbus_timeout_get_interval (DBusTimeout *timeout)
411 return timeout->interval;
415 * Gets data previously set with dbus_timeout_set_data()
418 * @param timeout the DBusTimeout object.
419 * @returns previously-set data.
422 dbus_timeout_get_data (DBusTimeout *timeout)
424 return timeout->data;
428 * Sets data which can be retrieved with dbus_timeout_get_data().
429 * Intended for use by the DBusAddTimeoutFunction and
430 * DBusRemoveTimeoutFunction to store their own data. For example with
431 * Qt you might store the QTimer for this timeout and with GLib
432 * you might store a g_timeout_add result id.
434 * @param timeout the DBusTimeout object.
435 * @param data the data.
436 * @param free_data_function function to be called to free the data.
439 dbus_timeout_set_data (DBusTimeout *timeout,
441 DBusFreeFunction free_data_function)
443 if (timeout->free_data_function != NULL)
444 (* timeout->free_data_function) (timeout->data);
446 timeout->data = data;
447 timeout->free_data_function = free_data_function;
451 * Calls the timeout handler for this timeout.
452 * This function should be called when the timeout
455 * If this function returns #FALSE, then there wasn't
456 * enough memory to handle the timeout. Typically just
457 * letting the timeout fire again next time it naturally
458 * times out is an adequate response to that problem,
459 * but you could try to do more if you wanted.
461 * @param timeout the DBusTimeout object.
462 * @returns #FALSE if there wasn't enough memory
465 dbus_timeout_handle (DBusTimeout *timeout)
467 return (* timeout->handler) (timeout->handler_data);
472 * Returns whether a timeout is enabled or not. If not
473 * enabled, it should not be polled by the main loop.
475 * @param timeout the DBusTimeout object
476 * @returns #TRUE if the timeout is enabled
479 dbus_timeout_get_enabled (DBusTimeout *timeout)
481 return timeout->enabled;
484 /** @} end public API docs */