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