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