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