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 };
  48
  49 /**
  50  * Creates a new DBusTimeout.
  51  * @param interval the timeout interval in milliseconds.
  52  * @param handler function to call when the timeout occurs.
  53  * @param data data to pass to the handler
  54  * @param free_data_function function to be called to free the data.
  55  * @returns the new DBusTimeout object,
  56  */
  57 DBusTimeout*
  58 _dbus_timeout_new (int                 interval,
  59                    DBusTimeoutHandler  handler,
  60                    void               *data,
  61                    DBusFreeFunction    free_data_function)
  62 {
  63   DBusTimeout *timeout;
  64
  65   timeout = dbus_new0 (DBusTimeout, 1);
  66   timeout->refcount = 1;
  67   timeout->interval = interval;
  68
  69   timeout->handler = handler;
  70   timeout->handler_data = data;
  71   timeout->free_handler_data_function = free_data_function;
  72
  73   return timeout;
  74 }
  75
  76 /**
  77  * Increments the reference count of a DBusTimeout object.
  78  *
  79  * @param timeout the timeout object.
  80  */
  81 void
  82 _dbus_timeout_ref (DBusTimeout *timeout)
  83 {
  84   timeout->refcount += 1;
  85 }
  86
  87 /**
  88  * Decrements the reference count of a DBusTimeout object
  89  * and finalizes the object if the count reaches zero.
  90  *
  91  * @param timeout the timeout object.
  92  */
  93 void
  94 _dbus_timeout_unref (DBusTimeout *timeout)
  95 {
  96   _dbus_assert (timeout != NULL);
  97   _dbus_assert (timeout->refcount > 0);
  98
  99   timeout->refcount -= 1;
 100   if (timeout->refcount == 0)
 101     {
 102       dbus_timeout_set_data (timeout, NULL, NULL); /* call free_data_function */
 103
 104       if (timeout->free_handler_data_function)
 105         (* timeout->free_handler_data_function) (timeout->handler_data);
 106
 107       dbus_free (timeout);
 108     }
 109 }
 110
 111 /**
 112  * @typedef DBusTimeoutList
 113  *
 114  * Opaque data type representing a list of timeouts
 115  * and a set of DBusAddTimeoutFunction/DBusRemoveTimeoutFunction.
 116  * Automatically handles removing/re-adding timeouts
 117  * when the DBusAddTimeoutFunction is updated or changed.
 118  * Holds a reference count to each timeout.
 119  *
 120  */
 121
 122 /**
 123  * DBusTimeoutList implementation details. All fields
 124  * are private.
 125  *
 126  */
 127 struct DBusTimeoutList
 128 {
 129   DBusList *timeouts; /**< Timeout objects. */
 130
 131   DBusAddTimeoutFunction add_timeout_function;       /**< Callback for adding a timeout. */
 132   DBusRemoveTimeoutFunction remove_timeout_function; /**< Callback for removing a timeout. */
 133   void *timeout_data;                                /**< Data for timeout callbacks */
 134   DBusFreeFunction timeout_free_data_function;       /**< Free function for timeout callback data */
 135 };
 136
 137 /**
 138  * Creates a new timeout list. Returns #NULL if insufficient
 139  * memory exists.
 140  *
 141  * @returns the new timeout list, or #NULL on failure.
 142  */
 143 DBusTimeoutList*
 144 _dbus_timeout_list_new (void)
 145 {
 146   DBusTimeoutList *timeout_list;
 147
 148   timeout_list = dbus_new0 (DBusTimeoutList, 1);
 149   if (timeout_list == NULL)
 150     return NULL;
 151
 152   return timeout_list;
 153 }
 154
 155 /**
 156  * Frees a DBusTimeoutList.
 157  *
 158  * @param timeout_list the timeout list.
 159  */
 160 void
 161 _dbus_timeout_list_free (DBusTimeoutList *timeout_list)
 162 {
 163   /* free timeout_data and remove timeouts as a side effect */
 164   _dbus_timeout_list_set_functions (timeout_list,
 165                                     NULL, NULL, NULL, NULL);
 166
 167   _dbus_list_foreach (&timeout_list->timeouts,
 168                       (DBusForeachFunction) _dbus_timeout_unref,
 169                       NULL);
 170   _dbus_list_clear (&timeout_list->timeouts);
 171
 172   dbus_free (timeout_list);
 173 }
 174
 175 /**
 176  * Sets the timeout functions. This function is the "backend"
 177  * for dbus_connection_set_timeout_functions().
 178  *
 179  * @param timeout_list the timeout list
 180  * @param add_function the add timeout function.
 181  * @param remove_function the remove timeout function.
 182  * @param data the data for those functions.
 183  * @param free_data_function the function to free the data.
 184  * @returns #FALSE if no memory
 185  *
 186  */
 187 dbus_bool_t
 188 _dbus_timeout_list_set_functions (DBusTimeoutList           *timeout_list,
 189                                   DBusAddTimeoutFunction     add_function,
 190                                   DBusRemoveTimeoutFunction  remove_function,
 191                                   void                      *data,
 192                                   DBusFreeFunction           free_data_function)
 193 {
 194   /* Add timeouts with the new function, failing on OOM */
 195   if (add_function != NULL)
 196     {
 197       DBusList *link;
 198
 199       link = _dbus_list_get_first_link (&timeout_list->timeouts);
 200       while (link != NULL)
 201         {
 202           DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
 203                                                      link);
 204
 205           if (!(* add_function) (link->data, data))
 206             {
 207               /* remove it all again and return FALSE */
 208               DBusList *link2;
 209
 210               link2 = _dbus_list_get_first_link (&timeout_list->timeouts);
 211               while (link2 != link)
 212                 {
 213                   DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
 214                                                              link2);
 215
 216                   (* remove_function) (link2->data, data);
 217
 218                   link2 = next;
 219                 }
 220
 221               return FALSE;
 222             }
 223
 224           link = next;
 225         }
 226     }
 227
 228   /* Remove all current timeouts from previous timeout handlers */
 229
 230   if (timeout_list->remove_timeout_function != NULL)
 231     {
 232       _dbus_list_foreach (&timeout_list->timeouts,
 233                           (DBusForeachFunction) timeout_list->remove_timeout_function,
 234                           timeout_list->timeout_data);
 235     }
 236
 237   if (timeout_list->timeout_free_data_function != NULL)
 238     (* timeout_list->timeout_free_data_function) (timeout_list->timeout_data);
 239
 240   timeout_list->add_timeout_function = add_function;
 241   timeout_list->remove_timeout_function = remove_function;
 242   timeout_list->timeout_data = data;
 243   timeout_list->timeout_free_data_function = free_data_function;
 244
 245   return TRUE;
 246 }
 247
 248 /**
 249  * Adds a new timeout to the timeout list, invoking the
 250  * application DBusAddTimeoutFunction if appropriate.
 251  *
 252  * @param timeout_list the timeout list.
 253  * @param timeout the timeout to add.
 254  * @returns #TRUE on success, #FALSE If no memory.
 255  */
 256 dbus_bool_t
 257 _dbus_timeout_list_add_timeout (DBusTimeoutList *timeout_list,
 258                                 DBusTimeout     *timeout)
 259 {
 260   if (!_dbus_list_append (&timeout_list->timeouts, timeout))
 261     return FALSE;
 262
 263   _dbus_timeout_ref (timeout);
 264
 265   if (timeout_list->add_timeout_function != NULL)
 266     {
 267       if (!(* timeout_list->add_timeout_function) (timeout,
 268                                                    timeout_list->timeout_data))
 269         {
 270           _dbus_list_remove_last (&timeout_list->timeouts, timeout);
 271           _dbus_timeout_unref (timeout);
 272           return FALSE;
 273         }
 274     }
 275
 276   return TRUE;
 277 }
 278
 279 /**
 280  * Removes a timeout from the timeout list, invoking the
 281  * application's DBusRemoveTimeoutFunction if appropriate.
 282  *
 283  * @param timeout_list the timeout list.
 284  * @param timeout the timeout to remove.
 285  */
 286 void
 287 _dbus_timeout_list_remove_timeout (DBusTimeoutList *timeout_list,
 288                                    DBusTimeout     *timeout)
 289 {
 290   if (!_dbus_list_remove (&timeout_list->timeouts, timeout))
 291     _dbus_assert_not_reached ("Nonexistent timeout was removed");
 292
 293   if (timeout_list->remove_timeout_function != NULL)
 294     (* timeout_list->remove_timeout_function) (timeout,
 295                                                timeout_list->timeout_data);
 296
 297   _dbus_timeout_unref (timeout);
 298 }
 299
 300 /** @} */
 301
 302 /**
 303  * @defgroup DBusTimeout DBusTimeout
 304  * @ingroup  DBus
 305  * @brief Object representing a timeout
 306  *
 307  * Types and functions related to DBusTimeout. A timeout
 308  * represents a timeout that the main loop needs to monitor,
 309  * as in Qt's QTimer or GLib's g_timeout_add().
 310  *
 311  * @{
 312  */
 313
 314
 315 /**
 316  * @typedef DBusTimeout
 317  *
 318  * Opaque object representing a timeout.
 319  */
 320
 321 /**
 322  * Gets the timeout interval. The dbus_timeout_handle()
 323  * should be called each time this interval elapses,
 324  * starting after it elapses once.
 325  *
 326  * @param timeout the DBusTimeout object.
 327  * @returns the interval in milliseconds.
 328  */
 329 int
 330 dbus_timeout_get_interval (DBusTimeout *timeout)
 331 {
 332   return timeout->interval;
 333 }
 334
 335 /**
 336  * Gets data previously set with dbus_timeout_set_data()
 337  * or #NULL if none.
 338  *
 339  * @param timeout the DBusTimeout object.
 340  * @returns previously-set data.
 341  */
 342 void*
 343 dbus_timeout_get_data (DBusTimeout *timeout)
 344 {
 345   return timeout->data;
 346 }
 347
 348 /**
 349  * Sets data which can be retrieved with dbus_timeout_get_data().
 350  * Intended for use by the DBusAddTimeoutFunction and
 351  * DBusRemoveTimeoutFunction to store their own data.  For example with
 352  * Qt you might store the QTimer for this timeout and with GLib
 353  * you might store a g_timeout_add result id.
 354  *
 355  * @param timeout the DBusTimeout object.
 356  * @param data the data.
 357  * @param free_data_function function to be called to free the data.
 358  */
 359 void
 360 dbus_timeout_set_data (DBusTimeout      *timeout,
 361                        void             *data,
 362                        DBusFreeFunction  free_data_function)
 363 {
 364   if (timeout->free_data_function != NULL)
 365     (* timeout->free_data_function) (timeout->data);
 366
 367   timeout->data = data;
 368   timeout->free_data_function = free_data_function;
 369 }
 370
 371 /**
 372  * Calls the timeout handler for this timeout.
 373  * This function should be called when the timeout
 374  * occurs.
 375  *
 376  * @param timeout the DBusTimeout object.
 377  */
 378 void
 379 dbus_timeout_handle (DBusTimeout *timeout)
 380 {
 381   (* timeout->handler) (timeout->handler_data);
 382 }