_dbus_bindings/pending-call.c

   1 /* Implementation of PendingCall helper type for D-Bus bindings.
   2  *
   3  * Copyright (C) 2006 Collabora Ltd.
   4  *
   5  * Licensed under the Academic Free License version 2.1
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  22  *
  23  */
  24
  25 #include "dbus_bindings-internal.h"
  26
  27 PyDoc_STRVAR(PendingCall_tp_doc,
  28 "Object representing a pending D-Bus call, returned by\n"
  29 "Connection.send_message_with_reply(). Cannot be instantiated directly.\n"
  30 );
  31
  32 static PyTypeObject PendingCallType;
  33
  34 static inline int PendingCall_Check (PyObject *o)
  35 {
  36     return (o->ob_type == &PendingCallType)
  37             || PyObject_IsInstance(o, (PyObject *)&PendingCallType);
  38 }
  39
  40 typedef struct {
  41     PyObject_HEAD
  42     DBusPendingCall *pc;
  43 } PendingCall;
  44
  45 PyDoc_STRVAR(PendingCall_cancel__doc__,
  46 "cancel()\n\n"
  47 "Cancel this pending call. Its reply will be ignored and the associated\n"
  48 "reply handler will never be called.\n");
  49 static PyObject *
  50 PendingCall_cancel(PendingCall *self, PyObject *unused UNUSED)
  51 {
  52     Py_BEGIN_ALLOW_THREADS
  53     dbus_pending_call_cancel(self->pc);
  54     Py_END_ALLOW_THREADS
  55     Py_RETURN_NONE;
  56 }
  57
  58 PyDoc_STRVAR(PendingCall_block__doc__,
  59 "block()\n\n"
  60 "Block until this pending call has completed and the associated\n"
  61 "reply handler has been called.\n"
  62 "\n"
  63 "This can lead to a deadlock, if the called method tries to make a\n"
  64 "synchronous call to a method in this application. As a result, it's\n"
  65 "probably a bad idea.\n");
  66 static PyObject *
  67 PendingCall_block(PendingCall *self, PyObject *unused UNUSED)
  68 {
  69     Py_BEGIN_ALLOW_THREADS
  70     dbus_pending_call_block(self->pc);
  71     Py_END_ALLOW_THREADS
  72     Py_RETURN_NONE;
  73 }
  74
  75 static void
  76 _pending_call_notify_function(DBusPendingCall *pc,
  77                               PyObject *list)
  78 {
  79     PyGILState_STATE gil = PyGILState_Ensure();
  80     /* BEGIN CRITICAL SECTION
  81      * While holding the GIL, make sure the callback only gets called once
  82      * by deleting it from the 1-item list that's held by libdbus.
  83      */
  84     PyObject *handler = PyList_GetItem(list, 0);
  85     DBusMessage *msg;
  86
  87     if (!handler) {
  88         PyErr_Print();
  89         goto release;
  90     }
  91     if (handler == Py_None) {
  92         /* We've already called (and thrown away) the callback */
  93         goto release;
  94     }
  95     Py_INCREF(handler);     /* previously borrowed from the list, now owned */
  96     Py_INCREF(Py_None);     /* take a ref so SetItem can steal it */
  97     PyList_SetItem(list, 0, Py_None);
  98     /* END CRITICAL SECTION */
  99
 100     msg = dbus_pending_call_steal_reply(pc);
 101
 102     if (!msg) {
 103         /* omg, what happened here? the notify should only get called
 104          * when we have a reply */
 105         PyErr_Warn(PyExc_UserWarning, "D-Bus notify function was called "
 106                    "for an incomplete pending call (shouldn't happen)");
 107     } else {
 108         PyObject *msg_obj = DBusPyMessage_ConsumeDBusMessage(msg);
 109
 110         if (msg_obj) {
 111             PyObject *ret = PyObject_CallFunctionObjArgs(handler, msg_obj, NULL);
 112
 113             if (!ret) {
 114                 PyErr_Print();
 115             }
 116             Py_XDECREF(ret);
 117         }
 118         /* else OOM has happened - not a lot we can do about that,
 119          * except possibly making it fatal (FIXME?) */
 120     }
 121
 122     Py_XDECREF(handler);
 123 release:
 124     PyGILState_Release(gil);
 125 }
 126
 127 PyDoc_STRVAR(PendingCall_get_completed__doc__,
 128 "get_completed() -> bool\n\n"
 129 "Return true if this pending call has completed.\n\n"
 130 "If so, its associated reply handler has been called and it is no\n"
 131 "longer meaningful to cancel it.\n");
 132 static PyObject *
 133 PendingCall_get_completed(PendingCall *self, PyObject *unused UNUSED)
 134 {
 135     dbus_bool_t ret;
 136
 137     Py_BEGIN_ALLOW_THREADS
 138     ret = dbus_pending_call_get_completed(self->pc);
 139     Py_END_ALLOW_THREADS
 140     return PyBool_FromLong(ret);
 141 }
 142
 143 /* Steals the reference to the pending call. */
 144 PyObject *
 145 DBusPyPendingCall_ConsumeDBusPendingCall(DBusPendingCall *pc,
 146                                          PyObject *callable)
 147 {
 148     dbus_bool_t ret;
 149     PyObject *list = PyList_New(1);
 150     PendingCall *self = PyObject_New(PendingCall, &PendingCallType);
 151
 152     if (!list || !self) {
 153         Py_XDECREF(list);
 154         Py_XDECREF(self);
 155         Py_BEGIN_ALLOW_THREADS
 156         dbus_pending_call_cancel(pc);
 157         dbus_pending_call_unref(pc);
 158         Py_END_ALLOW_THREADS
 159         return NULL;
 160     }
 161
 162     /* INCREF because SET_ITEM steals a ref */
 163     Py_INCREF(callable);
 164     PyList_SET_ITEM(list, 0, callable);
 165
 166     /* INCREF so we can give a ref to set_notify and still have one */
 167     Py_INCREF(list);
 168
 169     Py_BEGIN_ALLOW_THREADS
 170     ret = dbus_pending_call_set_notify(pc,
 171         (DBusPendingCallNotifyFunction)_pending_call_notify_function,
 172         (void *)list, (DBusFreeFunction)dbus_py_take_gil_and_xdecref);
 173     Py_END_ALLOW_THREADS
 174
 175     if (!ret) {
 176         PyErr_NoMemory();
 177         /* DECREF twice - one for the INCREF and one for the allocation */
 178         Py_DECREF(list);
 179         Py_DECREF(list);
 180         Py_DECREF(self);
 181         Py_BEGIN_ALLOW_THREADS
 182         dbus_pending_call_cancel(pc);
 183         dbus_pending_call_unref(pc);
 184         Py_END_ALLOW_THREADS
 185         return NULL;
 186     }
 187
 188     /* As Alexander Larsson pointed out on dbus@lists.fd.o on 2006-11-30,
 189      * the API has a race condition if set_notify runs in one thread and a
 190      * mail loop runs in another - if the reply gets in before set_notify
 191      * runs, the notify isn't called and there is no indication of error.
 192      *
 193      * The workaround is to check for completion immediately, but this also
 194      * has a race which might lead to getting the notify called twice if
 195      * we're unlucky. So I use the list to arrange for the notify to be
 196      * deleted before it's called for the second time. The GIL protects
 197      * the critical section in which I delete the callback from the list.
 198      */
 199     if (dbus_pending_call_get_completed(pc)) {
 200         /* the first race condition happened, so call the callable here.
 201          * FIXME: we ought to arrange for the callable to run from the
 202          * mainloop thread, like it would if the race hadn't happened...
 203          * this needs a better mainloop abstraction, though.
 204          */
 205         _pending_call_notify_function(pc, list);
 206     }
 207
 208     Py_DECREF(list);
 209     self->pc = pc;
 210     return (PyObject *)self;
 211 }
 212
 213 static void
 214 PendingCall_tp_dealloc (PendingCall *self)
 215 {
 216     if (self->pc) {
 217         Py_BEGIN_ALLOW_THREADS
 218         dbus_pending_call_unref(self->pc);
 219         Py_END_ALLOW_THREADS
 220     }
 221     PyObject_Del (self);
 222 }
 223
 224 static PyMethodDef PendingCall_tp_methods[] = {
 225     {"block", (PyCFunction)PendingCall_block, METH_NOARGS,
 226      PendingCall_block__doc__},
 227     {"cancel", (PyCFunction)PendingCall_cancel, METH_NOARGS,
 228      PendingCall_cancel__doc__},
 229     {"get_completed", (PyCFunction)PendingCall_get_completed, METH_NOARGS,
 230      PendingCall_get_completed__doc__},
 231     {NULL, NULL, 0, NULL}
 232 };
 233
 234 static PyTypeObject PendingCallType = {
 235     PyObject_HEAD_INIT(DEFERRED_ADDRESS(&PyType_Type))
 236     0,
 237     "dbus.lowlevel.PendingCall",
 238     sizeof(PendingCall),
 239     0,
 240     (destructor)PendingCall_tp_dealloc,     /* tp_dealloc */
 241     0,                                      /* tp_print */
 242     0,                                      /* tp_getattr */
 243     0,                                      /* tp_setattr */
 244     0,                                      /* tp_compare */
 245     0,                                      /* tp_repr */
 246     0,                                      /* tp_as_number */
 247     0,                                      /* tp_as_sequence */
 248     0,                                      /* tp_as_mapping */
 249     0,                                      /* tp_hash */
 250     0,                                      /* tp_call */
 251     0,                                      /* tp_str */
 252     0,                                      /* tp_getattro */
 253     0,                                      /* tp_setattro */
 254     0,                                      /* tp_as_buffer */
 255     Py_TPFLAGS_DEFAULT,                     /* tp_flags */
 256     PendingCall_tp_doc,                     /* tp_doc */
 257     0,                                      /* tp_traverse */
 258     0,                                      /* tp_clear */
 259     0,                                      /* tp_richcompare */
 260     0,                                      /* tp_weaklistoffset */
 261     0,                                      /* tp_iter */
 262     0,                                      /* tp_iternext */
 263     PendingCall_tp_methods,                 /* tp_methods */
 264     0,                                      /* tp_members */
 265     0,                                      /* tp_getset */
 266     0,                                      /* tp_base */
 267     0,                                      /* tp_dict */
 268     0,                                      /* tp_descr_get */
 269     0,                                      /* tp_descr_set */
 270     0,                                      /* tp_dictoffset */
 271     0,                                      /* tp_init */
 272     0,                                      /* tp_alloc */
 273     /* deliberately not callable! Use PendingCall_ConsumeDBusPendingCall */
 274     0,                                      /* tp_new */
 275 };
 276
 277 dbus_bool_t
 278 dbus_py_init_pending_call (void)
 279 {
 280     if (PyType_Ready (&PendingCallType) < 0) return 0;
 281     return 1;
 282 }
 283
 284 dbus_bool_t
 285 dbus_py_insert_pending_call (PyObject *this_module)
 286 {
 287     if (PyModule_AddObject (this_module, "PendingCall",
 288                             (PyObject *)&PendingCallType) < 0) return 0;
 289     return 1;
 290 }
 291
 292 /* vim:set ft=c cino< sw=4 sts=4 et: */