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