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 */