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 */ 40struct 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 */ 62DBusTimeout* 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 */ 92DBusTimeout * 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 */ 106void 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 */ 133void 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 */ 152void 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 */ 176struct 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 */ 193DBusTimeoutList* 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 */ 210void 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 */ 238dbus_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 */ 309dbus_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 */ 339void 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 */ 361void 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 */ 415int 416dbus_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 */ 428void* 429dbus_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 */ 445void 446dbus_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 */ 471dbus_bool_t 472dbus_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 */ 485dbus_bool_t 486dbus_timeout_get_enabled (DBusTimeout *timeout) 487{ 488 return timeout->enabled; 489} 490 491/** @} end public API docs */ 492