2006-10-21 Havoc Pennington <hp@redhat.com>
[platform/upstream/dbus.git] / dbus / dbus-timeout.c
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*
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 *
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
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
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
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*
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
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
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
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
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
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
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*
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
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
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
485 dbus_timeout_get_enabled (DBusTimeout *timeout)
486 {
487   return timeout->enabled;
488 }
489
490 /** @} end public API docs */