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.h"
  27 #include "dbus-list.h"
  28 #include "dbus-threads.h"
  29 #include "dbus-test.h"
  30
  31 /**
  32  * @defgroup DBusPendingCallInternals DBusPendingCall implementation details
  33  * @ingroup DBusInternals
  34  * @brief DBusPendingCall private implementation details.
  35  *
  36  * The guts of DBusPendingCall and its methods.
  37  *
  38  * @{
  39  */
  40
  41 static dbus_int32_t notify_user_data_slot = -1;
  42
  43 /**
  44  * Creates a new pending reply object.
  45  *
  46  * @param connection connection where reply will arrive
  47  * @param timeout_milliseconds length of timeout, -1 for default
  48  * @param timeout_handler timeout handler, takes pending call as data
  49  * @returns a new #DBusPendingCall or #NULL if no memory.
  50  */
  51 DBusPendingCall*
  52 _dbus_pending_call_new (DBusConnection    *connection,
  53                         int                timeout_milliseconds,
  54                         DBusTimeoutHandler timeout_handler)
  55 {
  56   DBusPendingCall *pending;
  57   DBusTimeout *timeout;
  58
  59   _dbus_assert (timeout_milliseconds >= 0 || timeout_milliseconds == -1);
  60
  61   if (timeout_milliseconds == -1)
  62     timeout_milliseconds = _DBUS_DEFAULT_TIMEOUT_VALUE;
  63
  64   if (!dbus_pending_call_allocate_data_slot (&notify_user_data_slot))
  65     return NULL;
  66
  67   pending = dbus_new0 (DBusPendingCall, 1);
  68
  69   if (pending == NULL)
  70     {
  71       dbus_pending_call_free_data_slot (&notify_user_data_slot);
  72       return NULL;
  73     }
  74
  75   timeout = _dbus_timeout_new (timeout_milliseconds,
  76                                timeout_handler,
  77                                pending, NULL);
  78
  79   if (timeout == NULL)
  80     {
  81       dbus_pending_call_free_data_slot (&notify_user_data_slot);
  82       dbus_free (pending);
  83       return NULL;
  84     }
  85
  86   pending->refcount.value = 1;
  87   pending->connection = connection;
  88   pending->timeout = timeout;
  89
  90   _dbus_data_slot_list_init (&pending->slot_list);
  91
  92   return pending;
  93 }
  94
  95 /**
  96  * Calls notifier function for the pending call
  97  * and sets the call to completed.
  98  *
  99  * @param pending the pending call
 100  *
 101  */
 102 void
 103 _dbus_pending_call_notify (DBusPendingCall *pending)
 104 {
 105   pending->completed = TRUE;
 106
 107   if (pending->function)
 108     {
 109       void *user_data;
 110       user_data = dbus_pending_call_get_data (pending,
 111                                               notify_user_data_slot);
 112
 113       (* pending->function) (pending, user_data);
 114     }
 115 }
 116
 117 /** @} */
 118
 119 /**
 120  * @defgroup DBusPendingCall DBusPendingCall
 121  * @ingroup  DBus
 122  * @brief Pending reply to a method call message
 123  *
 124  * A DBusPendingCall is an object representing an
 125  * expected reply. A #DBusPendingCall can be created
 126  * when you send a message that should have a reply.
 127  *
 128  * @{
 129  */
 130
 131 /**
 132  * @typedef DBusPendingCall
 133  *
 134  * Opaque data type representing a message pending.
 135  */
 136
 137 /**
 138  * Increments the reference count on a pending call.
 139  *
 140  * @param pending the pending call object
 141  * @returns the pending call object
 142  */
 143 DBusPendingCall *
 144 dbus_pending_call_ref (DBusPendingCall *pending)
 145 {
 146   _dbus_return_val_if_fail (pending != NULL, NULL);
 147
 148   _dbus_atomic_inc (&pending->refcount);
 149
 150   return pending;
 151 }
 152
 153 /**
 154  * Decrements the reference count on a pending call,
 155  * freeing it if the count reaches 0.
 156  *
 157  * @param pending the pending call object
 158  */
 159 void
 160 dbus_pending_call_unref (DBusPendingCall *pending)
 161 {
 162   dbus_bool_t last_unref;
 163
 164   _dbus_return_if_fail (pending != NULL);
 165
 166   last_unref = (_dbus_atomic_dec (&pending->refcount) == 1);
 167
 168   if (last_unref)
 169     {
 170       /* If we get here, we should be already detached
 171        * from the connection, or never attached.
 172        */
 173       _dbus_assert (pending->connection == NULL);
 174       _dbus_assert (!pending->timeout_added);
 175
 176       /* this assumes we aren't holding connection lock... */
 177       _dbus_data_slot_list_free (&pending->slot_list);
 178
 179       if (pending->timeout != NULL)
 180         _dbus_timeout_unref (pending->timeout);
 181
 182       if (pending->timeout_link)
 183         {
 184           dbus_message_unref ((DBusMessage *)pending->timeout_link->data);
 185           _dbus_list_free_link (pending->timeout_link);
 186           pending->timeout_link = NULL;
 187         }
 188
 189       if (pending->reply)
 190         {
 191           dbus_message_unref (pending->reply);
 192           pending->reply = NULL;
 193         }
 194
 195       dbus_free (pending);
 196
 197       dbus_pending_call_free_data_slot (&notify_user_data_slot);
 198     }
 199 }
 200
 201 /**
 202  * Sets a notification function to be called when the reply is
 203  * received or the pending call times out.
 204  *
 205  * @param pending the pending call
 206  * @param function notifier function
 207  * @param user_data data to pass to notifier function
 208  * @param free_user_data function to free the user data
 209  * @returns #FALSE if not enough memory
 210  */
 211 dbus_bool_t
 212 dbus_pending_call_set_notify (DBusPendingCall              *pending,
 213                               DBusPendingCallNotifyFunction function,
 214                               void                         *user_data,
 215                               DBusFreeFunction              free_user_data)
 216 {
 217   _dbus_return_val_if_fail (pending != NULL, FALSE);
 218
 219   /* could invoke application code! */
 220   if (!dbus_pending_call_set_data (pending, notify_user_data_slot,
 221                                    user_data, free_user_data))
 222     return FALSE;
 223
 224   pending->function = function;
 225
 226   return TRUE;
 227 }
 228
 229 /**
 230  * Cancels the pending call, such that any reply
 231  * or error received will just be ignored.
 232  * Drops at least one reference to the #DBusPendingCall
 233  * so will free the call if nobody else is holding
 234  * a reference.
 235  *
 236  * @param pending the pending call
 237  */
 238 void
 239 dbus_pending_call_cancel (DBusPendingCall *pending)
 240 {
 241   if (pending->connection)
 242     _dbus_connection_remove_pending_call (pending->connection,
 243                                           pending);
 244 }
 245
 246 /**
 247  * Checks whether the pending call has received a reply
 248  * yet, or not.
 249  *
 250  * @todo not thread safe? I guess it has to lock though it sucks
 251  *
 252  * @param pending the pending call
 253  * @returns #TRUE if a reply has been received */
 254 dbus_bool_t
 255 dbus_pending_call_get_completed (DBusPendingCall *pending)
 256 {
 257   return pending->completed;
 258 }
 259
 260 /**
 261  * Gets the reply, or returns #NULL if none has been received yet. The
 262  * reference count is not incremented on the returned message, so you
 263  * have to keep a reference count on the pending call (or add one
 264  * to the message).
 265  *
 266  * @todo not thread safe? I guess it has to lock though it sucks
 267  * @todo maybe to make this threadsafe, it should be steal_reply(), i.e. only one thread can ever get the message
 268  *
 269  * @param pending the pending call
 270  * @returns the reply message or #NULL.
 271  */
 272 DBusMessage*
 273 dbus_pending_call_get_reply (DBusPendingCall *pending)
 274 {
 275   return pending->reply;
 276 }
 277
 278 /**
 279  * Block until the pending call is completed.  The blocking is as with
 280  * dbus_connection_send_with_reply_and_block(); it does not enter the
 281  * main loop or process other messages, it simply waits for the reply
 282  * in question.
 283  *
 284  * If the pending call is already completed, this function returns
 285  * immediately.
 286  *
 287  * @todo when you start blocking, the timeout is reset, but it should
 288  * really only use time remaining since the pending call was created.
 289  *
 290  * @param pending the pending call
 291  */
 292 void
 293 dbus_pending_call_block (DBusPendingCall *pending)
 294 {
 295   DBusMessage *message;
 296
 297   if (dbus_pending_call_get_completed (pending))
 298     return;
 299
 300   /* message may be NULL if no reply */
 301   message = _dbus_connection_block_for_reply (pending->connection,
 302                                               pending->reply_serial,
 303                                               dbus_timeout_get_interval (pending->timeout));
 304
 305   _dbus_connection_lock (pending->connection);
 306   _dbus_pending_call_complete_and_unlock (pending, message);
 307   if (message)
 308     dbus_message_unref (message);
 309 }
 310
 311 static DBusDataSlotAllocator slot_allocator;
 312 _DBUS_DEFINE_GLOBAL_LOCK (pending_call_slots);
 313
 314 /**
 315  * Allocates an integer ID to be used for storing application-specific
 316  * data on any DBusPendingCall. The allocated ID may then be used
 317  * with dbus_pending_call_set_data() and dbus_pending_call_get_data().
 318  * The passed-in slot must be initialized to -1, and is filled in
 319  * with the slot ID. If the passed-in slot is not -1, it's assumed
 320  * to be already allocated, and its refcount is incremented.
 321  *
 322  * The allocated slot is global, i.e. all DBusPendingCall objects will
 323  * have a slot with the given integer ID reserved.
 324  *
 325  * @param slot_p address of a global variable storing the slot
 326  * @returns #FALSE on failure (no memory)
 327  */
 328 dbus_bool_t
 329 dbus_pending_call_allocate_data_slot (dbus_int32_t *slot_p)
 330 {
 331   return _dbus_data_slot_allocator_alloc (&slot_allocator,
 332                                           _DBUS_LOCK_NAME (pending_call_slots),
 333                                           slot_p);
 334 }
 335
 336 /**
 337  * Deallocates a global ID for #DBusPendingCall data slots.
 338  * dbus_pending_call_get_data() and dbus_pending_call_set_data() may
 339  * no longer be used with this slot.  Existing data stored on existing
 340  * DBusPendingCall objects will be freed when the #DBusPendingCall is
 341  * finalized, but may not be retrieved (and may only be replaced if
 342  * someone else reallocates the slot).  When the refcount on the
 343  * passed-in slot reaches 0, it is set to -1.
 344  *
 345  * @param slot_p address storing the slot to deallocate
 346  */
 347 void
 348 dbus_pending_call_free_data_slot (dbus_int32_t *slot_p)
 349 {
 350   _dbus_return_if_fail (*slot_p >= 0);
 351
 352   _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
 353 }
 354
 355 /**
 356  * Stores a pointer on a #DBusPendingCall, along
 357  * with an optional function to be used for freeing
 358  * the data when the data is set again, or when
 359  * the pending call is finalized. The slot number
 360  * must have been allocated with dbus_pending_call_allocate_data_slot().
 361  *
 362  * @param pending the pending_call
 363  * @param slot the slot number
 364  * @param data the data to store
 365  * @param free_data_func finalizer function for the data
 366  * @returns #TRUE if there was enough memory to store the data
 367  */
 368 dbus_bool_t
 369 dbus_pending_call_set_data (DBusPendingCall  *pending,
 370                             dbus_int32_t      slot,
 371                             void             *data,
 372                             DBusFreeFunction  free_data_func)
 373 {
 374   DBusFreeFunction old_free_func;
 375   void *old_data;
 376   dbus_bool_t retval;
 377
 378   _dbus_return_val_if_fail (pending != NULL, FALSE);
 379   _dbus_return_val_if_fail (slot >= 0, FALSE);
 380
 381   retval = _dbus_data_slot_list_set (&slot_allocator,
 382                                      &pending->slot_list,
 383                                      slot, data, free_data_func,
 384                                      &old_free_func, &old_data);
 385
 386   if (retval)
 387     {
 388       if (old_free_func)
 389         (* old_free_func) (old_data);
 390     }
 391
 392   return retval;
 393 }
 394
 395 /**
 396  * Retrieves data previously set with dbus_pending_call_set_data().
 397  * The slot must still be allocated (must not have been freed).
 398  *
 399  * @param pending the pending_call
 400  * @param slot the slot to get data from
 401  * @returns the data, or #NULL if not found
 402  */
 403 void*
 404 dbus_pending_call_get_data (DBusPendingCall   *pending,
 405                             dbus_int32_t       slot)
 406 {
 407   void *res;
 408
 409   _dbus_return_val_if_fail (pending != NULL, NULL);
 410
 411   res = _dbus_data_slot_list_get (&slot_allocator,
 412                                   &pending->slot_list,
 413                                   slot);
 414
 415   return res;
 416 }
 417
 418 /** @} */
 419
 420 #ifdef DBUS_BUILD_TESTS
 421
 422 /**
 423  * @ingroup DBusPendingCallInternals
 424  * Unit test for DBusPendingCall.
 425  *
 426  * @returns #TRUE on success.
 427  */
 428 dbus_bool_t
 429 _dbus_pending_call_test (const char *test_data_dir)
 430 {
 431
 432   return TRUE;
 433 }
 434 #endif /* DBUS_BUILD_TESTS */