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