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