gdb/python/py-infthread.c

   1 /* Python interface to inferior threads.
   2
   3    Copyright (C) 2009-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   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 3 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, see <http://www.gnu.org/licenses/>.  */
  19
  20 #include "defs.h"
  21 #include "gdbthread.h"
  22 #include "inferior.h"
  23 #include "python-internal.h"
  24
  25 extern PyTypeObject thread_object_type
  26     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("thread_object");
  27
  28 /* Require that INFERIOR be a valid inferior ID.  */
  29 #define THPY_REQUIRE_VALID(Thread)                              \
  30   do {                                                          \
  31     if (!Thread->thread)                                        \
  32       {                                                         \
  33         PyErr_SetString (PyExc_RuntimeError,                    \
  34                          _("Thread no longer exists."));        \
  35         return NULL;                                            \
  36       }                                                         \
  37   } while (0)
  38
  39 gdbpy_ref<thread_object>
  40 create_thread_object (struct thread_info *tp)
  41 {
  42   gdbpy_ref<thread_object> thread_obj;
  43
  44   gdbpy_ref<inferior_object> inf_obj = inferior_to_inferior_object (tp->inf);
  45   if (inf_obj == NULL)
  46     return NULL;
  47
  48   thread_obj.reset (PyObject_New (thread_object, &thread_object_type));
  49   if (thread_obj == NULL)
  50     return NULL;
  51
  52   thread_obj->thread = tp;
  53   thread_obj->inf_obj = (PyObject *) inf_obj.release ();
  54   thread_obj->dict = PyDict_New ();
  55   if (thread_obj->dict == nullptr)
  56     return nullptr;
  57
  58   return thread_obj;
  59 }
  60
  61 static void
  62 thpy_dealloc (PyObject *self)
  63 {
  64   thread_object *thr_obj = (thread_object *) self;
  65
  66   gdb_assert (thr_obj->inf_obj != nullptr);
  67
  68   Py_DECREF (thr_obj->inf_obj);
  69   Py_XDECREF (thr_obj->dict);
  70
  71   Py_TYPE (self)->tp_free (self);
  72 }
  73
  74 static PyObject *
  75 thpy_get_name (PyObject *self, void *ignore)
  76 {
  77   thread_object *thread_obj = (thread_object *) self;
  78
  79   THPY_REQUIRE_VALID (thread_obj);
  80
  81   const char *name = thread_name (thread_obj->thread);
  82   if (name == NULL)
  83     Py_RETURN_NONE;
  84
  85   return PyUnicode_FromString (name);
  86 }
  87
  88 /* Return a string containing target specific additional information about
  89    the state of the thread, or None, if there is no such additional
  90    information.  */
  91
  92 static PyObject *
  93 thpy_get_details (PyObject *self, void *ignore)
  94 {
  95   thread_object *thread_obj = (thread_object *) self;
  96
  97   THPY_REQUIRE_VALID (thread_obj);
  98
  99   /* GCC can't tell that extra_info will always be assigned after the
 100      'catch', so initialize it.  */
 101   const char *extra_info = nullptr;
 102   try
 103     {
 104       extra_info = target_extra_thread_info (thread_obj->thread);
 105     }
 106   catch (const gdb_exception &except)
 107     {
 108       GDB_PY_HANDLE_EXCEPTION (except);
 109     }
 110   if (extra_info == nullptr)
 111     Py_RETURN_NONE;
 112
 113   return PyUnicode_FromString (extra_info);
 114 }
 115
 116 static int
 117 thpy_set_name (PyObject *self, PyObject *newvalue, void *ignore)
 118 {
 119   thread_object *thread_obj = (thread_object *) self;
 120   gdb::unique_xmalloc_ptr<char> name;
 121
 122   if (! thread_obj->thread)
 123     {
 124       PyErr_SetString (PyExc_RuntimeError, _("Thread no longer exists."));
 125       return -1;
 126     }
 127
 128   if (newvalue == NULL)
 129     {
 130       PyErr_SetString (PyExc_TypeError,
 131                        _("Cannot delete `name' attribute."));
 132       return -1;
 133     }
 134   else if (newvalue == Py_None)
 135     {
 136       /* Nothing.  */
 137     }
 138   else if (! gdbpy_is_string (newvalue))
 139     {
 140       PyErr_SetString (PyExc_TypeError,
 141                        _("The value of `name' must be a string."));
 142       return -1;
 143     }
 144   else
 145     {
 146       name = python_string_to_host_string (newvalue);
 147       if (! name)
 148         return -1;
 149     }
 150
 151   thread_obj->thread->set_name (std::move (name));
 152
 153   return 0;
 154 }
 155
 156 /* Getter for InferiorThread.num.  */
 157
 158 static PyObject *
 159 thpy_get_num (PyObject *self, void *closure)
 160 {
 161   thread_object *thread_obj = (thread_object *) self;
 162
 163   THPY_REQUIRE_VALID (thread_obj);
 164
 165   gdbpy_ref<> result
 166     = gdb_py_object_from_longest (thread_obj->thread->per_inf_num);
 167   return result.release ();
 168 }
 169
 170 /* Getter for InferiorThread.global_num.  */
 171
 172 static PyObject *
 173 thpy_get_global_num (PyObject *self, void *closure)
 174 {
 175   thread_object *thread_obj = (thread_object *) self;
 176
 177   THPY_REQUIRE_VALID (thread_obj);
 178
 179   gdbpy_ref<> result
 180     = gdb_py_object_from_longest (thread_obj->thread->global_num);
 181   return result.release ();
 182 }
 183
 184 /* Getter for InferiorThread.ptid  -> (pid, lwp, tid).
 185    Returns a tuple with the thread's ptid components.  */
 186
 187 static PyObject *
 188 thpy_get_ptid (PyObject *self, void *closure)
 189 {
 190   thread_object *thread_obj = (thread_object *) self;
 191
 192   THPY_REQUIRE_VALID (thread_obj);
 193
 194   return gdbpy_create_ptid_object (thread_obj->thread->ptid);
 195 }
 196
 197 /* Implement gdb.InferiorThread.ptid_string attribute.  */
 198
 199 static PyObject *
 200 thpy_get_ptid_string (PyObject *self, void *closure)
 201 {
 202   thread_object *thread_obj = (thread_object *) self;
 203   THPY_REQUIRE_VALID (thread_obj);
 204   ptid_t ptid = thread_obj->thread->ptid;
 205
 206   try
 207     {
 208       /* Select the correct inferior before calling a target_* function.  */
 209       scoped_restore_current_thread restore_thread;
 210       switch_to_inferior_no_thread (thread_obj->thread->inf);
 211       std::string ptid_str = target_pid_to_str (ptid);
 212       return PyUnicode_FromString (ptid_str.c_str ());
 213     }
 214   catch (const gdb_exception &except)
 215     {
 216       GDB_PY_HANDLE_EXCEPTION (except);
 217       return nullptr;
 218     }
 219 }
 220
 221 /* Getter for InferiorThread.inferior -> Inferior.  */
 222
 223 static PyObject *
 224 thpy_get_inferior (PyObject *self, void *ignore)
 225 {
 226   thread_object *thread_obj = (thread_object *) self;
 227
 228   THPY_REQUIRE_VALID (thread_obj);
 229   Py_INCREF (thread_obj->inf_obj);
 230
 231   return thread_obj->inf_obj;
 232 }
 233
 234 /* Implementation of InferiorThread.switch ().
 235    Makes this the GDB selected thread.  */
 236
 237 static PyObject *
 238 thpy_switch (PyObject *self, PyObject *args)
 239 {
 240   thread_object *thread_obj = (thread_object *) self;
 241
 242   THPY_REQUIRE_VALID (thread_obj);
 243
 244   try
 245     {
 246       switch_to_thread (thread_obj->thread);
 247     }
 248   catch (const gdb_exception &except)
 249     {
 250       GDB_PY_HANDLE_EXCEPTION (except);
 251     }
 252
 253   Py_RETURN_NONE;
 254 }
 255
 256 /* Implementation of InferiorThread.is_stopped () -> Boolean.
 257    Return whether the thread is stopped.  */
 258
 259 static PyObject *
 260 thpy_is_stopped (PyObject *self, PyObject *args)
 261 {
 262   thread_object *thread_obj = (thread_object *) self;
 263
 264   THPY_REQUIRE_VALID (thread_obj);
 265
 266   if (thread_obj->thread->state == THREAD_STOPPED)
 267     Py_RETURN_TRUE;
 268
 269   Py_RETURN_FALSE;
 270 }
 271
 272 /* Implementation of InferiorThread.is_running () -> Boolean.
 273    Return whether the thread is running.  */
 274
 275 static PyObject *
 276 thpy_is_running (PyObject *self, PyObject *args)
 277 {
 278   thread_object *thread_obj = (thread_object *) self;
 279
 280   THPY_REQUIRE_VALID (thread_obj);
 281
 282   if (thread_obj->thread->state == THREAD_RUNNING)
 283     Py_RETURN_TRUE;
 284
 285   Py_RETURN_FALSE;
 286 }
 287
 288 /* Implementation of InferiorThread.is_exited () -> Boolean.
 289    Return whether the thread is exited.  */
 290
 291 static PyObject *
 292 thpy_is_exited (PyObject *self, PyObject *args)
 293 {
 294   thread_object *thread_obj = (thread_object *) self;
 295
 296   THPY_REQUIRE_VALID (thread_obj);
 297
 298   if (thread_obj->thread->state == THREAD_EXITED)
 299     Py_RETURN_TRUE;
 300
 301   Py_RETURN_FALSE;
 302 }
 303
 304 /* Implementation of gdb.InfThread.is_valid (self) -> Boolean.
 305    Returns True if this inferior Thread object still exists
 306    in GDB.  */
 307
 308 static PyObject *
 309 thpy_is_valid (PyObject *self, PyObject *args)
 310 {
 311   thread_object *thread_obj = (thread_object *) self;
 312
 313   if (! thread_obj->thread)
 314     Py_RETURN_FALSE;
 315
 316   Py_RETURN_TRUE;
 317 }
 318
 319 /* Implementation of gdb.InferiorThread.handle (self) -> handle. */
 320
 321 static PyObject *
 322 thpy_thread_handle (PyObject *self, PyObject *args)
 323 {
 324   thread_object *thread_obj = (thread_object *) self;
 325   THPY_REQUIRE_VALID (thread_obj);
 326
 327   gdb::array_view<const gdb_byte> hv;
 328
 329   try
 330     {
 331       hv = target_thread_info_to_thread_handle (thread_obj->thread);
 332     }
 333   catch (const gdb_exception &except)
 334     {
 335       GDB_PY_HANDLE_EXCEPTION (except);
 336     }
 337
 338   if (hv.size () == 0)
 339     {
 340       PyErr_SetString (PyExc_RuntimeError, _("Thread handle not found."));
 341       return NULL;
 342     }
 343
 344   PyObject *object = PyBytes_FromStringAndSize ((const char *) hv.data (),
 345                                                 hv.size());
 346   return object;
 347 }
 348
 349 /* Implement repr() for gdb.InferiorThread.  */
 350
 351 static PyObject *
 352 thpy_repr (PyObject *self)
 353 {
 354   thread_object *thread_obj = (thread_object *) self;
 355
 356   if (thread_obj->thread == nullptr)
 357     return gdb_py_invalid_object_repr (self);
 358
 359   thread_info *thr = thread_obj->thread;
 360   return PyUnicode_FromFormat ("<%s id=%s target-id=\"%s\">",
 361                                Py_TYPE (self)->tp_name,
 362                                print_full_thread_id (thr),
 363                                target_pid_to_str (thr->ptid).c_str ());
 364 }
 365
 366 /* Return a reference to a new Python object representing a ptid_t.
 367    The object is a tuple containing (pid, lwp, tid). */
 368 PyObject *
 369 gdbpy_create_ptid_object (ptid_t ptid)
 370 {
 371   int pid;
 372   long lwp;
 373   ULONGEST tid;
 374   PyObject *ret;
 375
 376   ret = PyTuple_New (3);
 377   if (!ret)
 378     return NULL;
 379
 380   pid = ptid.pid ();
 381   lwp = ptid.lwp ();
 382   tid = ptid.tid ();
 383
 384   gdbpy_ref<> pid_obj = gdb_py_object_from_longest (pid);
 385   if (pid_obj == nullptr)
 386     return nullptr;
 387   gdbpy_ref<> lwp_obj = gdb_py_object_from_longest (lwp);
 388   if (lwp_obj == nullptr)
 389     return nullptr;
 390   gdbpy_ref<> tid_obj = gdb_py_object_from_ulongest (tid);
 391   if (tid_obj == nullptr)
 392     return nullptr;
 393
 394   /* Note that these steal references, hence the use of 'release'.  */
 395   PyTuple_SET_ITEM (ret, 0, pid_obj.release ());
 396   PyTuple_SET_ITEM (ret, 1, lwp_obj.release ());
 397   PyTuple_SET_ITEM (ret, 2, tid_obj.release ());
 398
 399   return ret;
 400 }
 401
 402 /* Implementation of gdb.selected_thread () -> gdb.InferiorThread.
 403    Returns the selected thread object.  */
 404
 405 PyObject *
 406 gdbpy_selected_thread (PyObject *self, PyObject *args)
 407 {
 408   if (inferior_ptid != null_ptid)
 409     return thread_to_thread_object (inferior_thread ()).release ();
 410
 411   Py_RETURN_NONE;
 412 }
 413
 414 static int CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
 415 gdbpy_initialize_thread (void)
 416 {
 417   if (PyType_Ready (&thread_object_type) < 0)
 418     return -1;
 419
 420   return gdb_pymodule_addobject (gdb_module, "InferiorThread",
 421                                  (PyObject *) &thread_object_type);
 422 }
 423
 424 GDBPY_INITIALIZE_FILE (gdbpy_initialize_thread);
 425
 426 \f
 427
 428 static gdb_PyGetSetDef thread_object_getset[] =
 429 {
 430   { "__dict__", gdb_py_generic_dict, nullptr,
 431     "The __dict__ for this thread.", &thread_object_type },
 432   { "name", thpy_get_name, thpy_set_name,
 433     "The name of the thread, as set by the user or the OS.", NULL },
 434   { "details", thpy_get_details, NULL,
 435     "A target specific string containing extra thread state details.",
 436     NULL },
 437   { "num", thpy_get_num, NULL,
 438     "Per-inferior number of the thread, as assigned by GDB.", NULL },
 439   { "global_num", thpy_get_global_num, NULL,
 440     "Global number of the thread, as assigned by GDB.", NULL },
 441   { "ptid", thpy_get_ptid, NULL, "ID of the thread, as assigned by the OS.",
 442     NULL },
 443   { "ptid_string", thpy_get_ptid_string, nullptr,
 444     "A string representing ptid, as used by, for example, 'info threads'.",
 445     nullptr },
 446   { "inferior", thpy_get_inferior, NULL,
 447     "The Inferior object this thread belongs to.", NULL },
 448
 449   { NULL }
 450 };
 451
 452 static PyMethodDef thread_object_methods[] =
 453 {
 454   { "is_valid", thpy_is_valid, METH_NOARGS,
 455     "is_valid () -> Boolean.\n\
 456 Return true if this inferior thread is valid, false if not." },
 457   { "switch", thpy_switch, METH_NOARGS,
 458     "switch ()\n\
 459 Makes this the GDB selected thread." },
 460   { "is_stopped", thpy_is_stopped, METH_NOARGS,
 461     "is_stopped () -> Boolean\n\
 462 Return whether the thread is stopped." },
 463   { "is_running", thpy_is_running, METH_NOARGS,
 464     "is_running () -> Boolean\n\
 465 Return whether the thread is running." },
 466   { "is_exited", thpy_is_exited, METH_NOARGS,
 467     "is_exited () -> Boolean\n\
 468 Return whether the thread is exited." },
 469   { "handle", thpy_thread_handle, METH_NOARGS,
 470     "handle  () -> handle\n\
 471 Return thread library specific handle for thread." },
 472
 473   { NULL }
 474 };
 475
 476 PyTypeObject thread_object_type =
 477 {
 478   PyVarObject_HEAD_INIT (NULL, 0)
 479   "gdb.InferiorThread",           /*tp_name*/
 480   sizeof (thread_object),         /*tp_basicsize*/
 481   0,                              /*tp_itemsize*/
 482   thpy_dealloc,                   /*tp_dealloc*/
 483   0,                              /*tp_print*/
 484   0,                              /*tp_getattr*/
 485   0,                              /*tp_setattr*/
 486   0,                              /*tp_compare*/
 487   thpy_repr,                      /*tp_repr*/
 488   0,                              /*tp_as_number*/
 489   0,                              /*tp_as_sequence*/
 490   0,                              /*tp_as_mapping*/
 491   0,                              /*tp_hash */
 492   0,                              /*tp_call*/
 493   0,                              /*tp_str*/
 494   0,                              /*tp_getattro*/
 495   0,                              /*tp_setattro*/
 496   0,                              /*tp_as_buffer*/
 497   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 498   "GDB thread object",            /* tp_doc */
 499   0,                              /* tp_traverse */
 500   0,                              /* tp_clear */
 501   0,                              /* tp_richcompare */
 502   0,                              /* tp_weaklistoffset */
 503   0,                              /* tp_iter */
 504   0,                              /* tp_iternext */
 505   thread_object_methods,          /* tp_methods */
 506   0,                              /* tp_members */
 507   thread_object_getset,           /* tp_getset */
 508   0,                              /* tp_base */
 509   0,                              /* tp_dict */
 510   0,                              /* tp_descr_get */
 511   0,                              /* tp_descr_set */
 512   offsetof (thread_object, dict), /* tp_dictoffset */
 513   0,                              /* tp_init */
 514   0                               /* tp_alloc */
 515 };