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