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