• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-timeout.c DBusTimeout implementation
3  *
4  * Copyright (C) 2003  CodeFactory AB
5  *
6  * Licensed under the Academic Free License version 2.1
7  *
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.
12  *
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.
17  *
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
21  *
22  */
23 
24 #include "dbus-internals.h"
25 #include "dbus-timeout.h"
26 #include "dbus-list.h"
27 
28 /**
29  * @defgroup DBusTimeoutInternals DBusTimeout implementation details
30  * @ingroup  DBusInternals
31  * @brief implementation details for DBusTimeout
32  *
33  * @{
34  */
35 
36 /**
37  * Internals of DBusTimeout
38  */
39 struct DBusTimeout
40 {
41   int refcount;                                /**< Reference count */
42   int interval;                                /**< Timeout interval in milliseconds. */
43 
44   DBusTimeoutHandler handler;                  /**< Timeout handler. */
45   void *handler_data;                          /**< Timeout handler data. */
46   DBusFreeFunction free_handler_data_function; /**< Free the timeout handler data. */
47 
48   void *data;		   	               /**< Application data. */
49   DBusFreeFunction free_data_function;         /**< Free the application data. */
50   unsigned int enabled : 1;                    /**< True if timeout is active. */
51 };
52 
53 /**
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,
60  */
61 DBusTimeout*
_dbus_timeout_new(int interval,DBusTimeoutHandler handler,void * data,DBusFreeFunction free_data_function)62 _dbus_timeout_new (int                 interval,
63 		   DBusTimeoutHandler  handler,
64 		   void               *data,
65 		   DBusFreeFunction    free_data_function)
66 {
67   DBusTimeout *timeout;
68 
69   timeout = dbus_new0 (DBusTimeout, 1);
70   if (timeout == NULL)
71     return NULL;
72 
73   timeout->refcount = 1;
74   timeout->interval = interval;
75 
76   timeout->handler = handler;
77   timeout->handler_data = data;
78   timeout->free_handler_data_function = free_data_function;
79 
80   timeout->enabled = TRUE;
81 
82   return timeout;
83 }
84 
85 /**
86  * Increments the reference count of a DBusTimeout object.
87  *
88  * @param timeout the timeout object.
89  * @returns the timeout object.
90  */
91 DBusTimeout *
_dbus_timeout_ref(DBusTimeout * timeout)92 _dbus_timeout_ref (DBusTimeout *timeout)
93 {
94   timeout->refcount += 1;
95 
96   return timeout;
97 }
98 
99 /**
100  * Decrements the reference count of a DBusTimeout object
101  * and finalizes the object if the count reaches zero.
102  *
103  * @param timeout the timeout object.
104  */
105 void
_dbus_timeout_unref(DBusTimeout * timeout)106 _dbus_timeout_unref (DBusTimeout *timeout)
107 {
108   _dbus_assert (timeout != NULL);
109   _dbus_assert (timeout->refcount > 0);
110 
111   timeout->refcount -= 1;
112   if (timeout->refcount == 0)
113     {
114       dbus_timeout_set_data (timeout, NULL, NULL); /* call free_data_function */
115 
116       if (timeout->free_handler_data_function)
117 	(* timeout->free_handler_data_function) (timeout->handler_data);
118 
119       dbus_free (timeout);
120     }
121 }
122 
123 /**
124  * Changes the timeout interval. Note that you have to disable and
125  * re-enable the timeout using the timeout toggle function
126  * (_dbus_connection_toggle_timeout_unlocked() etc.) to notify the
127  * application of this change.
128  *
129  * @param timeout the timeout
130  * @param interval the new interval
131  */
132 void
_dbus_timeout_set_interval(DBusTimeout * timeout,int interval)133 _dbus_timeout_set_interval (DBusTimeout *timeout,
134                             int          interval)
135 {
136   _dbus_assert (interval >= 0);
137 
138   timeout->interval = interval;
139 }
140 
141 /**
142  * Changes the timeout's enabled-ness. Note that you should use
143  * _dbus_connection_toggle_timeout_unlocked() etc. instead, if
144  * the timeout is passed out to an application main loop.
145  * i.e. you can't use this function in the D-Bus library, it's
146  * only used in the message bus daemon implementation.
147  *
148  * @param timeout the timeout
149  * @param enabled #TRUE if timeout should be enabled.
150  */
151 void
_dbus_timeout_set_enabled(DBusTimeout * timeout,dbus_bool_t enabled)152 _dbus_timeout_set_enabled (DBusTimeout  *timeout,
153                            dbus_bool_t   enabled)
154 {
155   timeout->enabled = enabled != FALSE;
156 }
157 
158 
159 /**
160  * @typedef DBusTimeoutList
161  *
162  * Opaque data type representing a list of timeouts
163  * and a set of DBusAddTimeoutFunction/DBusRemoveTimeoutFunction.
164  * Automatically handles removing/re-adding timeouts
165  * when the DBusAddTimeoutFunction is updated or changed.
166  * Holds a reference count to each timeout.
167  *
168  */
169 
170 /**
171  * DBusTimeoutList implementation details. All fields
172  * are private.
173  *
174  */
175 struct DBusTimeoutList
176 {
177   DBusList *timeouts; /**< Timeout objects. */
178 
179   DBusAddTimeoutFunction add_timeout_function;       /**< Callback for adding a timeout. */
180   DBusRemoveTimeoutFunction remove_timeout_function; /**< Callback for removing a timeout. */
181   DBusTimeoutToggledFunction timeout_toggled_function; /**< Callback when timeout is enabled/disabled or changes interval */
182   void *timeout_data;                                /**< Data for timeout callbacks */
183   DBusFreeFunction timeout_free_data_function;       /**< Free function for timeout callback data */
184 };
185 
186 /**
187  * Creates a new timeout list. Returns #NULL if insufficient
188  * memory exists.
189  *
190  * @returns the new timeout list, or #NULL on failure.
191  */
192 DBusTimeoutList*
_dbus_timeout_list_new(void)193 _dbus_timeout_list_new (void)
194 {
195   DBusTimeoutList *timeout_list;
196 
197   timeout_list = dbus_new0 (DBusTimeoutList, 1);
198   if (timeout_list == NULL)
199     return NULL;
200 
201   return timeout_list;
202 }
203 
204 /**
205  * Frees a DBusTimeoutList.
206  *
207  * @param timeout_list the timeout list.
208  */
209 void
_dbus_timeout_list_free(DBusTimeoutList * timeout_list)210 _dbus_timeout_list_free (DBusTimeoutList *timeout_list)
211 {
212   /* free timeout_data and remove timeouts as a side effect */
213   _dbus_timeout_list_set_functions (timeout_list,
214 				    NULL, NULL, NULL, NULL, NULL);
215 
216   _dbus_list_foreach (&timeout_list->timeouts,
217 		      (DBusForeachFunction) _dbus_timeout_unref,
218 		      NULL);
219   _dbus_list_clear (&timeout_list->timeouts);
220 
221   dbus_free (timeout_list);
222 }
223 
224 /**
225  * Sets the timeout functions. This function is the "backend"
226  * for dbus_connection_set_timeout_functions().
227  *
228  * @param timeout_list the timeout list
229  * @param add_function the add timeout function.
230  * @param remove_function the remove timeout function.
231  * @param toggled_function toggle notify function, or #NULL
232  * @param data the data for those functions.
233  * @param free_data_function the function to free the data.
234  * @returns #FALSE if no memory
235  *
236  */
237 dbus_bool_t
_dbus_timeout_list_set_functions(DBusTimeoutList * timeout_list,DBusAddTimeoutFunction add_function,DBusRemoveTimeoutFunction remove_function,DBusTimeoutToggledFunction toggled_function,void * data,DBusFreeFunction free_data_function)238 _dbus_timeout_list_set_functions (DBusTimeoutList           *timeout_list,
239 				  DBusAddTimeoutFunction     add_function,
240 				  DBusRemoveTimeoutFunction  remove_function,
241                                   DBusTimeoutToggledFunction toggled_function,
242 				  void                      *data,
243 				  DBusFreeFunction           free_data_function)
244 {
245   /* Add timeouts with the new function, failing on OOM */
246   if (add_function != NULL)
247     {
248       DBusList *link;
249 
250       link = _dbus_list_get_first_link (&timeout_list->timeouts);
251       while (link != NULL)
252         {
253           DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
254                                                      link);
255 
256           if (!(* add_function) (link->data, data))
257             {
258               /* remove it all again and return FALSE */
259               DBusList *link2;
260 
261               link2 = _dbus_list_get_first_link (&timeout_list->timeouts);
262               while (link2 != link)
263                 {
264                   DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
265                                                              link2);
266 
267                   (* remove_function) (link2->data, data);
268 
269                   link2 = next;
270                 }
271 
272               return FALSE;
273             }
274 
275           link = next;
276         }
277     }
278 
279   /* Remove all current timeouts from previous timeout handlers */
280 
281   if (timeout_list->remove_timeout_function != NULL)
282     {
283       _dbus_list_foreach (&timeout_list->timeouts,
284 			  (DBusForeachFunction) timeout_list->remove_timeout_function,
285 			  timeout_list->timeout_data);
286     }
287 
288   if (timeout_list->timeout_free_data_function != NULL)
289     (* timeout_list->timeout_free_data_function) (timeout_list->timeout_data);
290 
291   timeout_list->add_timeout_function = add_function;
292   timeout_list->remove_timeout_function = remove_function;
293   timeout_list->timeout_toggled_function = toggled_function;
294   timeout_list->timeout_data = data;
295   timeout_list->timeout_free_data_function = free_data_function;
296 
297   return TRUE;
298 }
299 
300 /**
301  * Adds a new timeout to the timeout list, invoking the
302  * application DBusAddTimeoutFunction if appropriate.
303  *
304  * @param timeout_list the timeout list.
305  * @param timeout the timeout to add.
306  * @returns #TRUE on success, #FALSE If no memory.
307  */
308 dbus_bool_t
_dbus_timeout_list_add_timeout(DBusTimeoutList * timeout_list,DBusTimeout * timeout)309 _dbus_timeout_list_add_timeout (DBusTimeoutList *timeout_list,
310 				DBusTimeout     *timeout)
311 {
312   if (!_dbus_list_append (&timeout_list->timeouts, timeout))
313     return FALSE;
314 
315   _dbus_timeout_ref (timeout);
316 
317   if (timeout_list->add_timeout_function != NULL)
318     {
319       if (!(* timeout_list->add_timeout_function) (timeout,
320                                                    timeout_list->timeout_data))
321         {
322           _dbus_list_remove_last (&timeout_list->timeouts, timeout);
323           _dbus_timeout_unref (timeout);
324           return FALSE;
325         }
326     }
327 
328   return TRUE;
329 }
330 
331 /**
332  * Removes a timeout from the timeout list, invoking the
333  * application's DBusRemoveTimeoutFunction if appropriate.
334  *
335  * @param timeout_list the timeout list.
336  * @param timeout the timeout to remove.
337  */
338 void
_dbus_timeout_list_remove_timeout(DBusTimeoutList * timeout_list,DBusTimeout * timeout)339 _dbus_timeout_list_remove_timeout (DBusTimeoutList *timeout_list,
340 				   DBusTimeout     *timeout)
341 {
342   if (!_dbus_list_remove (&timeout_list->timeouts, timeout))
343     _dbus_assert_not_reached ("Nonexistent timeout was removed");
344 
345   if (timeout_list->remove_timeout_function != NULL)
346     (* timeout_list->remove_timeout_function) (timeout,
347 					       timeout_list->timeout_data);
348 
349   _dbus_timeout_unref (timeout);
350 }
351 
352 /**
353  * Sets a timeout to the given enabled state, invoking the
354  * application's DBusTimeoutToggledFunction if appropriate.
355  *
356  * @param timeout_list the timeout list.
357  * @param timeout the timeout to toggle.
358  * @param enabled #TRUE to enable
359  */
360 void
_dbus_timeout_list_toggle_timeout(DBusTimeoutList * timeout_list,DBusTimeout * timeout,dbus_bool_t enabled)361 _dbus_timeout_list_toggle_timeout (DBusTimeoutList           *timeout_list,
362                                    DBusTimeout               *timeout,
363                                    dbus_bool_t                enabled)
364 {
365   enabled = !!enabled;
366 
367   if (enabled == timeout->enabled)
368     return;
369 
370   timeout->enabled = enabled;
371 
372   if (timeout_list->timeout_toggled_function != NULL)
373     (* timeout_list->timeout_toggled_function) (timeout,
374                                                 timeout_list->timeout_data);
375 }
376 
377 /** @} */
378 
379 /**
380  * @defgroup DBusTimeout DBusTimeout
381  * @ingroup  DBus
382  * @brief Object representing a timeout
383  *
384  * Types and functions related to DBusTimeout. A timeout
385  * represents a timeout that the main loop needs to monitor,
386  * as in Qt's QTimer or GLib's g_timeout_add().
387  *
388  * Use dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions()
389  * to be notified when libdbus needs to add or remove timeouts.
390  *
391  * @{
392  */
393 
394 
395 /**
396  * @typedef DBusTimeout
397  *
398  * Opaque object representing a timeout.
399  */
400 
401 /**
402  * Gets the timeout interval. The dbus_timeout_handle()
403  * should be called each time this interval elapses,
404  * starting after it elapses once.
405  *
406  * The interval may change during the life of the
407  * timeout; if so, the timeout will be disabled and
408  * re-enabled (calling the "timeout toggled function")
409  * to notify you of the change.
410  *
411  * @param timeout the DBusTimeout object.
412  * @returns the interval in milliseconds.
413  */
414 int
dbus_timeout_get_interval(DBusTimeout * timeout)415 dbus_timeout_get_interval (DBusTimeout *timeout)
416 {
417   return timeout->interval;
418 }
419 
420 /**
421  * Gets data previously set with dbus_timeout_set_data()
422  * or #NULL if none.
423  *
424  * @param timeout the DBusTimeout object.
425  * @returns previously-set data.
426  */
427 void*
dbus_timeout_get_data(DBusTimeout * timeout)428 dbus_timeout_get_data (DBusTimeout *timeout)
429 {
430   return timeout->data;
431 }
432 
433 /**
434  * Sets data which can be retrieved with dbus_timeout_get_data().
435  * Intended for use by the DBusAddTimeoutFunction and
436  * DBusRemoveTimeoutFunction to store their own data.  For example with
437  * Qt you might store the QTimer for this timeout and with GLib
438  * you might store a g_timeout_add result id.
439  *
440  * @param timeout the DBusTimeout object.
441  * @param data the data.
442  * @param free_data_function function to be called to free the data.
443  */
444 void
dbus_timeout_set_data(DBusTimeout * timeout,void * data,DBusFreeFunction free_data_function)445 dbus_timeout_set_data (DBusTimeout      *timeout,
446 		       void             *data,
447 		       DBusFreeFunction  free_data_function)
448 {
449   if (timeout->free_data_function != NULL)
450     (* timeout->free_data_function) (timeout->data);
451 
452   timeout->data = data;
453   timeout->free_data_function = free_data_function;
454 }
455 
456 /**
457  * Calls the timeout handler for this timeout.
458  * This function should be called when the timeout
459  * occurs.
460  *
461  * If this function returns #FALSE, then there wasn't
462  * enough memory to handle the timeout. Typically just
463  * letting the timeout fire again next time it naturally
464  * times out is an adequate response to that problem,
465  * but you could try to do more if you wanted.
466  *
467  * @param timeout the DBusTimeout object.
468  * @returns #FALSE if there wasn't enough memory
469  */
470 dbus_bool_t
dbus_timeout_handle(DBusTimeout * timeout)471 dbus_timeout_handle (DBusTimeout *timeout)
472 {
473   return (* timeout->handler) (timeout->handler_data);
474 }
475 
476 
477 /**
478  * Returns whether a timeout is enabled or not. If not
479  * enabled, it should not be polled by the main loop.
480  *
481  * @param timeout the DBusTimeout object
482  * @returns #TRUE if the timeout is enabled
483  */
484 dbus_bool_t
dbus_timeout_get_enabled(DBusTimeout * timeout)485 dbus_timeout_get_enabled (DBusTimeout *timeout)
486 {
487   return timeout->enabled;
488 }
489 
490 /** @} end public API docs */
491