2005-01-16 Havoc Pennington <hp@redhat.com>
[platform/upstream/dbus.git] / 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 */