dbus/dbus-pending-call.c

   1 /* -*- mode: C; c-file-style: "gnu" -*- */
   2 /* dbus-pending-call.c Object representing a call in progress.
   3  *
   4  * Copyright (C) 2002, 2003 Red Hat Inc.
   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  *
  22  */
  23
  24 #include "dbus-internals.h"
  25 #include "dbus-connection-internal.h"
  26 #include "dbus-pending-call-internal.h"
  27 #include "dbus-pending-call.h"
  28 #include "dbus-list.h"
  29 #include "dbus-threads.h"
  30 #include "dbus-test.h"
  31
  32 /**
  33  * @defgroup DBusPendingCallInternals DBusPendingCall implementation details
  34  * @ingroup DBusInternals
  35  * @brief DBusPendingCall private implementation details.
  36  *
  37  * The guts of DBusPendingCall and its methods.
  38  *
  39  * @{
  40  */
  41
  42 /**
  43  * @brief Internals of DBusPendingCall
  44  *
  45  * Opaque object representing a reply message that we're waiting for.
  46  */
  47 struct DBusPendingCall
  48 {
  49   DBusAtomic refcount;                            /**< reference count */
  50
  51   DBusDataSlotList slot_list;                     /**< Data stored by allocated integer ID */
  52
  53   DBusPendingCallNotifyFunction function;         /**< Notifier when reply arrives. */
  54
  55   DBusConnection *connection;                     /**< Connections we're associated with */
  56   DBusMessage *reply;                             /**< Reply (after we've received it) */
  57   DBusTimeout *timeout;                           /**< Timeout */
  58
  59   DBusList *timeout_link;                         /**< Preallocated timeout response */
  60
  61   dbus_uint32_t reply_serial;                     /**< Expected serial of reply */
  62
  63   unsigned int completed : 1;                     /**< TRUE if completed */
  64   unsigned int timeout_added : 1;                 /**< Have added the timeout */
  65 };
  66
  67 static dbus_int32_t notify_user_data_slot = -1;
  68
  69 /**
  70  * Creates a new pending reply object.
  71  *
  72  * @param connection connection where reply will arrive
  73  * @param timeout_milliseconds length of timeout, -1 for default
  74  * @param timeout_handler timeout handler, takes pending call as data
  75  * @returns a new #DBusPendingCall or #NULL if no memory.
  76  */
  77 DBusPendingCall*
  78 _dbus_pending_call_new (DBusConnection    *connection,
  79                         int                timeout_milliseconds,
  80                         DBusTimeoutHandler timeout_handler)
  81 {
  82   DBusPendingCall *pending;
  83   DBusTimeout *timeout;
  84
  85   _dbus_assert (timeout_milliseconds >= 0 || timeout_milliseconds == -1);
  86
  87   if (timeout_milliseconds == -1)
  88     timeout_milliseconds = _DBUS_DEFAULT_TIMEOUT_VALUE;
  89
  90   /* it would probably seem logical to pass in _DBUS_INT_MAX for
  91    * infinite timeout, but then math in
  92    * _dbus_connection_block_for_reply would get all overflow-prone, so
  93    * smack that down.
  94    */
  95   if (timeout_milliseconds > _DBUS_ONE_HOUR_IN_MILLISECONDS * 6)
  96     timeout_milliseconds = _DBUS_ONE_HOUR_IN_MILLISECONDS * 6;
  97
  98   if (!dbus_pending_call_allocate_data_slot (&notify_user_data_slot))
  99     return NULL;
 100
 101   pending = dbus_new0 (DBusPendingCall, 1);
 102
 103   if (pending == NULL)
 104     {
 105       dbus_pending_call_free_data_slot (&notify_user_data_slot);
 106       return NULL;
 107     }
 108
 109   timeout = _dbus_timeout_new (timeout_milliseconds,
 110                                timeout_handler,
 111                                pending, NULL);
 112
 113   if (timeout == NULL)
 114     {
 115       dbus_pending_call_free_data_slot (&notify_user_data_slot);
 116       dbus_free (pending);
 117       return NULL;
 118     }
 119
 120   pending->refcount.value = 1;
 121   pending->connection = connection;
 122   pending->timeout = timeout;
 123
 124   _dbus_data_slot_list_init (&pending->slot_list);
 125
 126   return pending;
 127 }
 128
 129 /**
 130  * Sets the reply of a pending call with the given message,
 131  * or if the message is #NULL, by timing out the pending call.
 132  *
 133  * @param pending the pending call
 134  * @param message the message to complete the call with, or #NULL
 135  *  to time out the call
 136  */
 137 void
 138 _dbus_pending_call_set_reply (DBusPendingCall *pending,
 139                               DBusMessage     *message)
 140 {
 141   if (message == NULL)
 142     {
 143       message = pending->timeout_link->data;
 144       _dbus_list_clear (&pending->timeout_link);
 145     }
 146   else
 147     dbus_message_ref (message);
 148
 149   _dbus_verbose ("  handing message %p (%s) to pending call serial %u\n",
 150                  message,
 151                  dbus_message_get_type (message) == DBUS_MESSAGE_TYPE_METHOD_RETURN ?
 152                  "method return" :
 153                  dbus_message_get_type (message) == DBUS_MESSAGE_TYPE_ERROR ?
 154                  "error" : "other type",
 155                  pending->reply_serial);
 156
 157   _dbus_assert (pending->reply == NULL);
 158   _dbus_assert (pending->reply_serial == dbus_message_get_reply_serial (message));
 159   pending->reply = message;
 160 }
 161
 162 /**
 163  * Calls notifier function for the pending call
 164  * and sets the call to completed.
 165  *
 166  * @param pending the pending call
 167  *
 168  */
 169 void
 170 _dbus_pending_call_complete (DBusPendingCall *pending)
 171 {
 172   _dbus_assert (!pending->completed);
 173
 174   pending->completed = TRUE;
 175
 176   if (pending->function)
 177     {
 178       void *user_data;
 179       user_data = dbus_pending_call_get_data (pending,
 180                                               notify_user_data_slot);
 181
 182       (* pending->function) (pending, user_data);
 183     }
 184 }
 185
 186 void
 187 _dbus_pending_call_queue_timeout_error (DBusPendingCall *pending,
 188                                         DBusConnection *connection)
 189 {
 190   if (pending->timeout_link)
 191     {
 192       _dbus_connection_queue_synthesized_message_link (connection,
 193                                                        pending->timeout_link);
 194       pending->timeout_link = NULL;
 195     }
 196 }
 197
 198 /**
 199  * Checks to see if a timeout has been added
 200  *
 201  * @param pending the pending_call
 202  * @returns #TRUE if there is a timeout or #FALSE if not
 203  */
 204 dbus_bool_t
 205 _dbus_pending_call_is_timeout_added (DBusPendingCall  *pending)
 206 {
 207   _dbus_assert (pending != NULL);
 208
 209   return pending->timeout_added;
 210 }
 211
 212
 213 /**
 214  * Sets wether the timeout has been added
 215  *
 216  * @param pending the pending_call
 217  * @param is_added whether or not a timeout is added
 218  */
 219 void
 220 _dbus_pending_call_set_timeout_added (DBusPendingCall  *pending,
 221                                       dbus_bool_t       is_added)
 222 {
 223   _dbus_assert (pending != NULL);
 224
 225   pending->timeout_added = is_added;
 226 }
 227
 228
 229 /**
 230  * Retrives the timeout
 231  *
 232  * @param pending the pending_call
 233  * @returns a timeout object
 234  */
 235 DBusTimeout *
 236 _dbus_pending_call_get_timeout (DBusPendingCall  *pending)
 237 {
 238   _dbus_assert (pending != NULL);
 239
 240   return pending->timeout;
 241 }
 242
 243 /**
 244  * Gets the reply's serial number
 245  *
 246  * @param pending the pending_call
 247  * @returns a serial number for the reply or 0
 248  */
 249 dbus_uint32_t
 250 _dbus_pending_call_get_reply_serial (DBusPendingCall  *pending)
 251 {
 252   _dbus_assert (pending != NULL);
 253
 254   return pending->reply_serial;
 255 }
 256
 257 /**
 258  * Sets the reply's serial number
 259  *
 260  * @param pending the pending_call
 261  * @param serial the serial number
 262  */
 263 void
 264 _dbus_pending_call_set_reply_serial  (DBusPendingCall *pending,
 265                                       dbus_uint32_t serial)
 266 {
 267   _dbus_assert (pending != NULL);
 268   _dbus_assert (pending->reply_serial == 0);
 269
 270   pending->reply_serial = serial;
 271 }
 272
 273 /**
 274  * Gets the connection associated with this pending call
 275  *
 276  * @param pending the pending_call
 277  * @returns the connection associated with the pending call
 278  */
 279 DBusConnection *
 280 _dbus_pending_call_get_connection (DBusPendingCall *pending)
 281 {
 282   _dbus_assert (pending != NULL);
 283
 284   return pending->connection;
 285 }
 286
 287 /**
 288  * Sets the connection associated with the pending call
 289  *
 290  * @param pending the pending_call
 291  * @param connection the connection which is associated with the pending call
 292  */
 293 void
 294 _dbus_pending_call_set_connection (DBusPendingCall *pending,
 295                                    DBusConnection *connection)
 296 {
 297   _dbus_assert (pending != NULL);
 298
 299   pending->connection = connection;
 300 }
 301
 302 /**
 303  * NULLs out the connection
 304  *
 305  * @param pending the pending_call
 306  */
 307 void
 308 _dbus_pending_call_clear_connection (DBusPendingCall *pending)
 309 {
 310   _dbus_assert (pending != NULL);
 311
 312   pending->connection = NULL;
 313 }
 314
 315 /**
 316  * Sets the reply message associated with the pending call to a timeout error
 317  *
 318  * @param pending the pending_call
 319  * @param message the message we are sending the error reply to
 320  * @param serial serial number for the reply
 321  * @return #FALSE on OOM
 322  */
 323 dbus_bool_t
 324 _dbus_pending_call_set_timeout_error (DBusPendingCall *pending,
 325                                       DBusMessage *message,
 326                                       dbus_uint32_t serial)
 327 {
 328   DBusList *reply_link;
 329   DBusMessage *reply;
 330
 331   reply = dbus_message_new_error (message, DBUS_ERROR_NO_REPLY,
 332                                   "No reply within specified time");
 333   if (reply == NULL)
 334     return FALSE;
 335
 336   reply_link = _dbus_list_alloc_link (reply);
 337   if (reply_link == NULL)
 338     {
 339       dbus_message_unref (reply);
 340       return FALSE;
 341     }
 342
 343   pending->timeout_link = reply_link;
 344
 345   _dbus_pending_call_set_reply_serial (pending, serial);
 346
 347   return TRUE;
 348 }
 349
 350 /** @} */
 351
 352 /**
 353  * @defgroup DBusPendingCall DBusPendingCall
 354  * @ingroup  DBus
 355  * @brief Pending reply to a method call message
 356  *
 357  * A DBusPendingCall is an object representing an
 358  * expected reply. A #DBusPendingCall can be created
 359  * when you send a message that should have a reply.
 360  *
 361  * @{
 362  */
 363
 364 /**
 365  * @typedef DBusPendingCall
 366  *
 367  * Opaque data type representing a message pending.
 368  */
 369
 370 /**
 371  * Increments the reference count on a pending call.
 372  *
 373  * @param pending the pending call object
 374  * @returns the pending call object
 375  */
 376 DBusPendingCall *
 377 dbus_pending_call_ref (DBusPendingCall *pending)
 378 {
 379   _dbus_return_val_if_fail (pending != NULL, NULL);
 380
 381   _dbus_atomic_inc (&pending->refcount);
 382
 383   return pending;
 384 }
 385
 386 /**
 387  * Decrements the reference count on a pending call,
 388  * freeing it if the count reaches 0.
 389  *
 390  * @param pending the pending call object
 391  */
 392 void
 393 dbus_pending_call_unref (DBusPendingCall *pending)
 394 {
 395   dbus_bool_t last_unref;
 396
 397   _dbus_return_if_fail (pending != NULL);
 398
 399   last_unref = (_dbus_atomic_dec (&pending->refcount) == 1);
 400
 401   if (last_unref)
 402     {
 403       /* If we get here, we should be already detached
 404        * from the connection, or never attached.
 405        */
 406       _dbus_assert (pending->connection == NULL);
 407       _dbus_assert (!pending->timeout_added);
 408
 409       /* this assumes we aren't holding connection lock... */
 410       _dbus_data_slot_list_free (&pending->slot_list);
 411
 412       if (pending->timeout != NULL)
 413         _dbus_timeout_unref (pending->timeout);
 414
 415       if (pending->timeout_link)
 416         {
 417           dbus_message_unref ((DBusMessage *)pending->timeout_link->data);
 418           _dbus_list_free_link (pending->timeout_link);
 419           pending->timeout_link = NULL;
 420         }
 421
 422       if (pending->reply)
 423         {
 424           dbus_message_unref (pending->reply);
 425           pending->reply = NULL;
 426         }
 427
 428       dbus_free (pending);
 429
 430       dbus_pending_call_free_data_slot (&notify_user_data_slot);
 431     }
 432 }
 433
 434 /**
 435  * Sets a notification function to be called when the reply is
 436  * received or the pending call times out.
 437  *
 438  * @param pending the pending call
 439  * @param function notifier function
 440  * @param user_data data to pass to notifier function
 441  * @param free_user_data function to free the user data
 442  * @returns #FALSE if not enough memory
 443  */
 444 dbus_bool_t
 445 dbus_pending_call_set_notify (DBusPendingCall              *pending,
 446                               DBusPendingCallNotifyFunction function,
 447                               void                         *user_data,
 448                               DBusFreeFunction              free_user_data)
 449 {
 450   _dbus_return_val_if_fail (pending != NULL, FALSE);
 451
 452   /* could invoke application code! */
 453   if (!dbus_pending_call_set_data (pending, notify_user_data_slot,
 454                                    user_data, free_user_data))
 455     return FALSE;
 456
 457   pending->function = function;
 458
 459   return TRUE;
 460 }
 461
 462 /**
 463  * Cancels the pending call, such that any reply or error received
 464  * will just be ignored.  Drops the dbus library's internal reference
 465  * to the #DBusPendingCall so will free the call if nobody else is
 466  * holding a reference. However you usually get a reference
 467  * from dbus_connection_send() so probably your app owns a ref also.
 468  *
 469  * @param pending the pending call
 470  */
 471 void
 472 dbus_pending_call_cancel (DBusPendingCall *pending)
 473 {
 474   if (pending->connection)
 475     _dbus_connection_remove_pending_call (pending->connection,
 476                                           pending);
 477 }
 478
 479 /**
 480  * Checks whether the pending call has received a reply
 481  * yet, or not.
 482  *
 483  * @todo not thread safe? I guess it has to lock though it sucks
 484  *
 485  * @param pending the pending call
 486  * @returns #TRUE if a reply has been received */
 487 dbus_bool_t
 488 dbus_pending_call_get_completed (DBusPendingCall *pending)
 489 {
 490   return pending->completed;
 491 }
 492
 493 /**
 494  * Gets the reply, or returns #NULL if none has been received
 495  * yet. Ownership of the reply message passes to the caller. This
 496  * function can only be called once per pending call, since the reply
 497  * message is tranferred to the caller.
 498  *
 499  * @param pending the pending call
 500  * @returns the reply message or #NULL.
 501  */
 502 DBusMessage*
 503 dbus_pending_call_steal_reply (DBusPendingCall *pending)
 504 {
 505   DBusMessage *message;
 506
 507   _dbus_return_val_if_fail (pending->completed, NULL);
 508   _dbus_return_val_if_fail (pending->reply != NULL, NULL);
 509
 510   message = pending->reply;
 511   pending->reply = NULL;
 512
 513   return message;
 514 }
 515
 516 /**
 517  * Block until the pending call is completed.  The blocking is as with
 518  * dbus_connection_send_with_reply_and_block(); it does not enter the
 519  * main loop or process other messages, it simply waits for the reply
 520  * in question.
 521  *
 522  * If the pending call is already completed, this function returns
 523  * immediately.
 524  *
 525  * @todo when you start blocking, the timeout is reset, but it should
 526  * really only use time remaining since the pending call was created.
 527  *
 528  * @param pending the pending call
 529  */
 530 void
 531 dbus_pending_call_block (DBusPendingCall *pending)
 532 {
 533   _dbus_connection_block_pending_call (pending);
 534 }
 535
 536 static DBusDataSlotAllocator slot_allocator;
 537 _DBUS_DEFINE_GLOBAL_LOCK (pending_call_slots);
 538
 539 /**
 540  * Allocates an integer ID to be used for storing application-specific
 541  * data on any DBusPendingCall. The allocated ID may then be used
 542  * with dbus_pending_call_set_data() and dbus_pending_call_get_data().
 543  * The passed-in slot must be initialized to -1, and is filled in
 544  * with the slot ID. If the passed-in slot is not -1, it's assumed
 545  * to be already allocated, and its refcount is incremented.
 546  *
 547  * The allocated slot is global, i.e. all DBusPendingCall objects will
 548  * have a slot with the given integer ID reserved.
 549  *
 550  * @param slot_p address of a global variable storing the slot
 551  * @returns #FALSE on failure (no memory)
 552  */
 553 dbus_bool_t
 554 dbus_pending_call_allocate_data_slot (dbus_int32_t *slot_p)
 555 {
 556   return _dbus_data_slot_allocator_alloc (&slot_allocator,
 557                                           _DBUS_LOCK_NAME (pending_call_slots),
 558                                           slot_p);
 559 }
 560
 561 /**
 562  * Deallocates a global ID for #DBusPendingCall data slots.
 563  * dbus_pending_call_get_data() and dbus_pending_call_set_data() may
 564  * no longer be used with this slot.  Existing data stored on existing
 565  * DBusPendingCall objects will be freed when the #DBusPendingCall is
 566  * finalized, but may not be retrieved (and may only be replaced if
 567  * someone else reallocates the slot).  When the refcount on the
 568  * passed-in slot reaches 0, it is set to -1.
 569  *
 570  * @param slot_p address storing the slot to deallocate
 571  */
 572 void
 573 dbus_pending_call_free_data_slot (dbus_int32_t *slot_p)
 574 {
 575   _dbus_return_if_fail (*slot_p >= 0);
 576
 577   _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
 578 }
 579
 580 /**
 581  * Stores a pointer on a #DBusPendingCall, along
 582  * with an optional function to be used for freeing
 583  * the data when the data is set again, or when
 584  * the pending call is finalized. The slot number
 585  * must have been allocated with dbus_pending_call_allocate_data_slot().
 586  *
 587  * @param pending the pending_call
 588  * @param slot the slot number
 589  * @param data the data to store
 590  * @param free_data_func finalizer function for the data
 591  * @returns #TRUE if there was enough memory to store the data
 592  */
 593 dbus_bool_t
 594 dbus_pending_call_set_data (DBusPendingCall  *pending,
 595                             dbus_int32_t      slot,
 596                             void             *data,
 597                             DBusFreeFunction  free_data_func)
 598 {
 599   DBusFreeFunction old_free_func;
 600   void *old_data;
 601   dbus_bool_t retval;
 602
 603   _dbus_return_val_if_fail (pending != NULL, FALSE);
 604   _dbus_return_val_if_fail (slot >= 0, FALSE);
 605
 606   retval = _dbus_data_slot_list_set (&slot_allocator,
 607                                      &pending->slot_list,
 608                                      slot, data, free_data_func,
 609                                      &old_free_func, &old_data);
 610
 611   if (retval)
 612     {
 613       if (old_free_func)
 614         (* old_free_func) (old_data);
 615     }
 616
 617   return retval;
 618 }
 619
 620 /**
 621  * Retrieves data previously set with dbus_pending_call_set_data().
 622  * The slot must still be allocated (must not have been freed).
 623  *
 624  * @param pending the pending_call
 625  * @param slot the slot to get data from
 626  * @returns the data, or #NULL if not found
 627  */
 628 void*
 629 dbus_pending_call_get_data (DBusPendingCall   *pending,
 630                             dbus_int32_t       slot)
 631 {
 632   void *res;
 633
 634   _dbus_return_val_if_fail (pending != NULL, NULL);
 635
 636   res = _dbus_data_slot_list_get (&slot_allocator,
 637                                   &pending->slot_list,
 638                                   slot);
 639
 640   return res;
 641 }
 642
 643 /** @} */
 644
 645 #ifdef DBUS_BUILD_TESTS
 646
 647 /**
 648  * @ingroup DBusPendingCallInternals
 649  * Unit test for DBusPendingCall.
 650  *
 651  * @returns #TRUE on success.
 652  */
 653 dbus_bool_t
 654 _dbus_pending_call_test (const char *test_data_dir)
 655 {
 656
 657   return TRUE;
 658 }
 659 #endif /* DBUS_BUILD_TESTS */