1 2 /* Thread module */ 3 /* Interface to Sjoerd's portable C thread library */ 4 5 #include "Python.h" 6 #include "structmember.h" /* offsetof */ 7 8 #ifndef WITH_THREAD 9 #error "Error! The rest of Python is not compiled with thread support." 10 #error "Rerun configure, adding a --with-threads option." 11 #error "Then run `make clean' followed by `make'." 12 #endif 13 14 #include "pythread.h" 15 16 static PyObject *ThreadError; 17 static PyObject *str_dict; 18 static long nb_threads = 0; 19 20 /* Lock objects */ 21 22 typedef struct { 23 PyObject_HEAD 24 PyThread_type_lock lock_lock; 25 PyObject *in_weakreflist; 26 } lockobject; 27 28 static void 29 lock_dealloc(lockobject *self) 30 { 31 if (self->in_weakreflist != NULL) 32 PyObject_ClearWeakRefs((PyObject *) self); 33 if (self->lock_lock != NULL) { 34 /* Unlock the lock so it's safe to free it */ 35 PyThread_acquire_lock(self->lock_lock, 0); 36 PyThread_release_lock(self->lock_lock); 37 38 PyThread_free_lock(self->lock_lock); 39 } 40 PyObject_Del(self); 41 } 42 43 static PyObject * 44 lock_PyThread_acquire_lock(lockobject *self, PyObject *args) 45 { 46 int i = 1; 47 48 if (!PyArg_ParseTuple(args, "|i:acquire", &i)) 49 return NULL; 50 51 Py_BEGIN_ALLOW_THREADS 52 i = PyThread_acquire_lock(self->lock_lock, i); 53 Py_END_ALLOW_THREADS 54 55 return PyBool_FromLong((long)i); 56 } 57 58 PyDoc_STRVAR(acquire_doc, 59 "acquire([wait]) -> None or bool\n\ 60 (acquire_lock() is an obsolete synonym)\n\ 61 \n\ 62 Lock the lock. Without argument, this blocks if the lock is already\n\ 63 locked (even by the same thread), waiting for another thread to release\n\ 64 the lock, and return None once the lock is acquired.\n\ 65 With an argument, this will only block if the argument is true,\n\ 66 and the return value reflects whether the lock is acquired.\n\ 67 The blocking operation is not interruptible."); 68 69 static PyObject * 70 lock_PyThread_release_lock(lockobject *self) 71 { 72 /* Sanity check: the lock must be locked */ 73 if (PyThread_acquire_lock(self->lock_lock, 0)) { 74 PyThread_release_lock(self->lock_lock); 75 PyErr_SetString(ThreadError, "release unlocked lock"); 76 return NULL; 77 } 78 79 PyThread_release_lock(self->lock_lock); 80 Py_INCREF(Py_None); 81 return Py_None; 82 } 83 84 PyDoc_STRVAR(release_doc, 85 "release()\n\ 86 (release_lock() is an obsolete synonym)\n\ 87 \n\ 88 Release the lock, allowing another thread that is blocked waiting for\n\ 89 the lock to acquire the lock. The lock must be in the locked state,\n\ 90 but it needn't be locked by the same thread that unlocks it."); 91 92 static PyObject * 93 lock_locked_lock(lockobject *self) 94 { 95 if (PyThread_acquire_lock(self->lock_lock, 0)) { 96 PyThread_release_lock(self->lock_lock); 97 return PyBool_FromLong(0L); 98 } 99 return PyBool_FromLong(1L); 100 } 101 102 PyDoc_STRVAR(locked_doc, 103 "locked() -> bool\n\ 104 (locked_lock() is an obsolete synonym)\n\ 105 \n\ 106 Return whether the lock is in the locked state."); 107 108 static PyMethodDef lock_methods[] = { 109 {"acquire_lock", (PyCFunction)lock_PyThread_acquire_lock, 110 METH_VARARGS, acquire_doc}, 111 {"acquire", (PyCFunction)lock_PyThread_acquire_lock, 112 METH_VARARGS, acquire_doc}, 113 {"release_lock", (PyCFunction)lock_PyThread_release_lock, 114 METH_NOARGS, release_doc}, 115 {"release", (PyCFunction)lock_PyThread_release_lock, 116 METH_NOARGS, release_doc}, 117 {"locked_lock", (PyCFunction)lock_locked_lock, 118 METH_NOARGS, locked_doc}, 119 {"locked", (PyCFunction)lock_locked_lock, 120 METH_NOARGS, locked_doc}, 121 {"__enter__", (PyCFunction)lock_PyThread_acquire_lock, 122 METH_VARARGS, acquire_doc}, 123 {"__exit__", (PyCFunction)lock_PyThread_release_lock, 124 METH_VARARGS, release_doc}, 125 {NULL} /* sentinel */ 126 }; 127 128 static PyTypeObject Locktype = { 129 PyVarObject_HEAD_INIT(&PyType_Type, 0) 130 "thread.lock", /*tp_name*/ 131 sizeof(lockobject), /*tp_size*/ 132 0, /*tp_itemsize*/ 133 /* methods */ 134 (destructor)lock_dealloc, /*tp_dealloc*/ 135 0, /*tp_print*/ 136 0, /*tp_getattr*/ 137 0, /*tp_setattr*/ 138 0, /*tp_compare*/ 139 0, /*tp_repr*/ 140 0, /* tp_as_number */ 141 0, /* tp_as_sequence */ 142 0, /* tp_as_mapping */ 143 0, /* tp_hash */ 144 0, /* tp_call */ 145 0, /* tp_str */ 146 0, /* tp_getattro */ 147 0, /* tp_setattro */ 148 0, /* tp_as_buffer */ 149 Py_TPFLAGS_HAVE_WEAKREFS, /* tp_flags */ 150 0, /* tp_doc */ 151 0, /* tp_traverse */ 152 0, /* tp_clear */ 153 0, /* tp_richcompare */ 154 offsetof(lockobject, in_weakreflist), /* tp_weaklistoffset */ 155 0, /* tp_iter */ 156 0, /* tp_iternext */ 157 lock_methods, /* tp_methods */ 158 }; 159 160 static lockobject * 161 newlockobject(void) 162 { 163 lockobject *self; 164 self = PyObject_New(lockobject, &Locktype); 165 if (self == NULL) 166 return NULL; 167 self->lock_lock = PyThread_allocate_lock(); 168 self->in_weakreflist = NULL; 169 if (self->lock_lock == NULL) { 170 Py_DECREF(self); 171 PyErr_SetString(ThreadError, "can't allocate lock"); 172 return NULL; 173 } 174 return self; 175 } 176 177 /* Thread-local objects */ 178 179 #include "structmember.h" 180 181 /* Quick overview: 182 183 We need to be able to reclaim reference cycles as soon as possible 184 (both when a thread is being terminated, or a thread-local object 185 becomes unreachable from user data). Constraints: 186 - it must not be possible for thread-state dicts to be involved in 187 reference cycles (otherwise the cyclic GC will refuse to consider 188 objects referenced from a reachable thread-state dict, even though 189 local_dealloc would clear them) 190 - the death of a thread-state dict must still imply destruction of the 191 corresponding local dicts in all thread-local objects. 192 193 Our implementation uses small "localdummy" objects in order to break 194 the reference chain. These trivial objects are hashable (using the 195 default scheme of identity hashing) and weakrefable. 196 Each thread-state holds a separate localdummy for each local object 197 (as a /strong reference/), 198 and each thread-local object holds a dict mapping /weak references/ 199 of localdummies to local dicts. 200 201 Therefore: 202 - only the thread-state dict holds a strong reference to the dummies 203 - only the thread-local object holds a strong reference to the local dicts 204 - only outside objects (application- or library-level) hold strong 205 references to the thread-local objects 206 - as soon as a thread-state dict is destroyed, the weakref callbacks of all 207 dummies attached to that thread are called, and destroy the corresponding 208 local dicts from thread-local objects 209 - as soon as a thread-local object is destroyed, its local dicts are 210 destroyed and its dummies are manually removed from all thread states 211 - the GC can do its work correctly when a thread-local object is dangling, 212 without any interference from the thread-state dicts 213 214 As an additional optimization, each localdummy holds a borrowed reference 215 to the corresponding localdict. This borrowed reference is only used 216 by the thread-local object which has created the localdummy, which should 217 guarantee that the localdict still exists when accessed. 218 */ 219 220 typedef struct { 221 PyObject_HEAD 222 PyObject *localdict; /* Borrowed reference! */ 223 PyObject *weakreflist; /* List of weak references to self */ 224 } localdummyobject; 225 226 static void 227 localdummy_dealloc(localdummyobject *self) 228 { 229 if (self->weakreflist != NULL) 230 PyObject_ClearWeakRefs((PyObject *) self); 231 Py_TYPE(self)->tp_free((PyObject*)self); 232 } 233 234 static PyTypeObject localdummytype = { 235 PyVarObject_HEAD_INIT(NULL, 0) 236 /* tp_name */ "_thread._localdummy", 237 /* tp_basicsize */ sizeof(localdummyobject), 238 /* tp_itemsize */ 0, 239 /* tp_dealloc */ (destructor)localdummy_dealloc, 240 /* tp_print */ 0, 241 /* tp_getattr */ 0, 242 /* tp_setattr */ 0, 243 /* tp_reserved */ 0, 244 /* tp_repr */ 0, 245 /* tp_as_number */ 0, 246 /* tp_as_sequence */ 0, 247 /* tp_as_mapping */ 0, 248 /* tp_hash */ 0, 249 /* tp_call */ 0, 250 /* tp_str */ 0, 251 /* tp_getattro */ 0, 252 /* tp_setattro */ 0, 253 /* tp_as_buffer */ 0, 254 /* tp_flags */ Py_TPFLAGS_DEFAULT, 255 /* tp_doc */ "Thread-local dummy", 256 /* tp_traverse */ 0, 257 /* tp_clear */ 0, 258 /* tp_richcompare */ 0, 259 /* tp_weaklistoffset */ offsetof(localdummyobject, weakreflist) 260 }; 261 262 263 typedef struct { 264 PyObject_HEAD 265 PyObject *key; 266 PyObject *args; 267 PyObject *kw; 268 PyObject *weakreflist; /* List of weak references to self */ 269 /* A {localdummy weakref -> localdict} dict */ 270 PyObject *dummies; 271 /* The callback for weakrefs to localdummies */ 272 PyObject *wr_callback; 273 } localobject; 274 275 /* Forward declaration */ 276 static PyObject *_ldict(localobject *self); 277 static PyObject *_localdummy_destroyed(PyObject *meth_self, PyObject *dummyweakref); 278 279 /* Create and register the dummy for the current thread. 280 Returns a borrowed reference of the corresponding local dict */ 281 static PyObject * 282 _local_create_dummy(localobject *self) 283 { 284 PyObject *tdict, *ldict = NULL, *wr = NULL; 285 localdummyobject *dummy = NULL; 286 int r; 287 288 tdict = PyThreadState_GetDict(); 289 if (tdict == NULL) { 290 PyErr_SetString(PyExc_SystemError, 291 "Couldn't get thread-state dictionary"); 292 goto err; 293 } 294 295 ldict = PyDict_New(); 296 if (ldict == NULL) 297 goto err; 298 dummy = (localdummyobject *) localdummytype.tp_alloc(&localdummytype, 0); 299 if (dummy == NULL) 300 goto err; 301 dummy->localdict = ldict; 302 wr = PyWeakref_NewRef((PyObject *) dummy, self->wr_callback); 303 if (wr == NULL) 304 goto err; 305 306 /* As a side-effect, this will cache the weakref's hash before the 307 dummy gets deleted */ 308 r = PyDict_SetItem(self->dummies, wr, ldict); 309 if (r < 0) 310 goto err; 311 Py_CLEAR(wr); 312 r = PyDict_SetItem(tdict, self->key, (PyObject *) dummy); 313 if (r < 0) 314 goto err; 315 Py_CLEAR(dummy); 316 317 Py_DECREF(ldict); 318 return ldict; 319 320 err: 321 Py_XDECREF(ldict); 322 Py_XDECREF(wr); 323 Py_XDECREF(dummy); 324 return NULL; 325 } 326 327 static PyObject * 328 local_new(PyTypeObject *type, PyObject *args, PyObject *kw) 329 { 330 localobject *self; 331 PyObject *wr; 332 static PyMethodDef wr_callback_def = { 333 "_localdummy_destroyed", (PyCFunction) _localdummy_destroyed, METH_O 334 }; 335 336 if (type->tp_init == PyBaseObject_Type.tp_init 337 && ((args && PyObject_IsTrue(args)) 338 || (kw && PyObject_IsTrue(kw)))) { 339 PyErr_SetString(PyExc_TypeError, 340 "Initialization arguments are not supported"); 341 return NULL; 342 } 343 344 self = (localobject *)type->tp_alloc(type, 0); 345 if (self == NULL) 346 return NULL; 347 348 Py_XINCREF(args); 349 self->args = args; 350 Py_XINCREF(kw); 351 self->kw = kw; 352 self->key = PyString_FromFormat("thread.local.%p", self); 353 if (self->key == NULL) 354 goto err; 355 356 self->dummies = PyDict_New(); 357 if (self->dummies == NULL) 358 goto err; 359 360 /* We use a weak reference to self in the callback closure 361 in order to avoid spurious reference cycles */ 362 wr = PyWeakref_NewRef((PyObject *) self, NULL); 363 if (wr == NULL) 364 goto err; 365 self->wr_callback = PyCFunction_New(&wr_callback_def, wr); 366 Py_DECREF(wr); 367 if (self->wr_callback == NULL) 368 goto err; 369 370 if (_local_create_dummy(self) == NULL) 371 goto err; 372 373 return (PyObject *)self; 374 375 err: 376 Py_DECREF(self); 377 return NULL; 378 } 379 380 static int 381 local_traverse(localobject *self, visitproc visit, void *arg) 382 { 383 Py_VISIT(self->args); 384 Py_VISIT(self->kw); 385 Py_VISIT(self->dummies); 386 return 0; 387 } 388 389 static int 390 local_clear(localobject *self) 391 { 392 PyThreadState *tstate; 393 Py_CLEAR(self->args); 394 Py_CLEAR(self->kw); 395 Py_CLEAR(self->dummies); 396 Py_CLEAR(self->wr_callback); 397 /* Remove all strong references to dummies from the thread states */ 398 if (self->key 399 && (tstate = PyThreadState_Get()) 400 && tstate->interp) { 401 for(tstate = PyInterpreterState_ThreadHead(tstate->interp); 402 tstate; 403 tstate = PyThreadState_Next(tstate)) 404 if (tstate->dict && 405 PyDict_GetItem(tstate->dict, self->key)) 406 PyDict_DelItem(tstate->dict, self->key); 407 } 408 return 0; 409 } 410 411 static void 412 local_dealloc(localobject *self) 413 { 414 /* Weakrefs must be invalidated right now, otherwise they can be used 415 from code called below, which is very dangerous since Py_REFCNT(self) == 0 */ 416 if (self->weakreflist != NULL) 417 PyObject_ClearWeakRefs((PyObject *) self); 418 419 PyObject_GC_UnTrack(self); 420 421 local_clear(self); 422 Py_XDECREF(self->key); 423 Py_TYPE(self)->tp_free((PyObject*)self); 424 } 425 426 /* Returns a borrowed reference to the local dict, creating it if necessary */ 427 static PyObject * 428 _ldict(localobject *self) 429 { 430 PyObject *tdict, *ldict, *dummy; 431 432 tdict = PyThreadState_GetDict(); 433 if (tdict == NULL) { 434 PyErr_SetString(PyExc_SystemError, 435 "Couldn't get thread-state dictionary"); 436 return NULL; 437 } 438 439 dummy = PyDict_GetItem(tdict, self->key); 440 if (dummy == NULL) { 441 ldict = _local_create_dummy(self); 442 if (ldict == NULL) 443 return NULL; 444 445 if (Py_TYPE(self)->tp_init != PyBaseObject_Type.tp_init && 446 Py_TYPE(self)->tp_init((PyObject*)self, 447 self->args, self->kw) < 0) { 448 /* we need to get rid of ldict from thread so 449 we create a new one the next time we do an attr 450 access */ 451 PyDict_DelItem(tdict, self->key); 452 return NULL; 453 } 454 } 455 else { 456 assert(Py_TYPE(dummy) == &localdummytype); 457 ldict = ((localdummyobject *) dummy)->localdict; 458 } 459 460 return ldict; 461 } 462 463 static int 464 local_setattro(localobject *self, PyObject *name, PyObject *v) 465 { 466 PyObject *ldict; 467 int r; 468 469 ldict = _ldict(self); 470 if (ldict == NULL) 471 return -1; 472 473 r = PyObject_RichCompareBool(name, str_dict, Py_EQ); 474 if (r == 1) { 475 PyErr_Format(PyExc_AttributeError, 476 "'%.50s' object attribute '__dict__' is read-only", 477 Py_TYPE(self)->tp_name); 478 return -1; 479 } 480 if (r == -1) 481 return -1; 482 483 return _PyObject_GenericSetAttrWithDict((PyObject *)self, name, v, ldict); 484 } 485 486 static PyObject *local_getattro(localobject *, PyObject *); 487 488 static PyTypeObject localtype = { 489 PyVarObject_HEAD_INIT(NULL, 0) 490 /* tp_name */ "thread._local", 491 /* tp_basicsize */ sizeof(localobject), 492 /* tp_itemsize */ 0, 493 /* tp_dealloc */ (destructor)local_dealloc, 494 /* tp_print */ 0, 495 /* tp_getattr */ 0, 496 /* tp_setattr */ 0, 497 /* tp_compare */ 0, 498 /* tp_repr */ 0, 499 /* tp_as_number */ 0, 500 /* tp_as_sequence */ 0, 501 /* tp_as_mapping */ 0, 502 /* tp_hash */ 0, 503 /* tp_call */ 0, 504 /* tp_str */ 0, 505 /* tp_getattro */ (getattrofunc)local_getattro, 506 /* tp_setattro */ (setattrofunc)local_setattro, 507 /* tp_as_buffer */ 0, 508 /* tp_flags */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE 509 | Py_TPFLAGS_HAVE_GC, 510 /* tp_doc */ "Thread-local data", 511 /* tp_traverse */ (traverseproc)local_traverse, 512 /* tp_clear */ (inquiry)local_clear, 513 /* tp_richcompare */ 0, 514 /* tp_weaklistoffset */ offsetof(localobject, weakreflist), 515 /* tp_iter */ 0, 516 /* tp_iternext */ 0, 517 /* tp_methods */ 0, 518 /* tp_members */ 0, 519 /* tp_getset */ 0, 520 /* tp_base */ 0, 521 /* tp_dict */ 0, /* internal use */ 522 /* tp_descr_get */ 0, 523 /* tp_descr_set */ 0, 524 /* tp_dictoffset */ 0, 525 /* tp_init */ 0, 526 /* tp_alloc */ 0, 527 /* tp_new */ local_new, 528 /* tp_free */ 0, /* Low-level free-mem routine */ 529 /* tp_is_gc */ 0, /* For PyObject_IS_GC */ 530 }; 531 532 static PyObject * 533 local_getattro(localobject *self, PyObject *name) 534 { 535 PyObject *ldict, *value; 536 int r; 537 538 ldict = _ldict(self); 539 if (ldict == NULL) 540 return NULL; 541 542 r = PyObject_RichCompareBool(name, str_dict, Py_EQ); 543 if (r == 1) { 544 Py_INCREF(ldict); 545 return ldict; 546 } 547 if (r == -1) 548 return NULL; 549 550 if (Py_TYPE(self) != &localtype) 551 /* use generic lookup for subtypes */ 552 return _PyObject_GenericGetAttrWithDict((PyObject *)self, name, ldict); 553 554 /* Optimization: just look in dict ourselves */ 555 value = PyDict_GetItem(ldict, name); 556 if (value == NULL) 557 /* Fall back on generic to get __class__ and __dict__ */ 558 return _PyObject_GenericGetAttrWithDict((PyObject *)self, name, ldict); 559 560 Py_INCREF(value); 561 return value; 562 } 563 564 /* Called when a dummy is destroyed. */ 565 static PyObject * 566 _localdummy_destroyed(PyObject *localweakref, PyObject *dummyweakref) 567 { 568 PyObject *obj; 569 localobject *self; 570 assert(PyWeakref_CheckRef(localweakref)); 571 obj = PyWeakref_GET_OBJECT(localweakref); 572 if (obj == Py_None) 573 Py_RETURN_NONE; 574 Py_INCREF(obj); 575 assert(PyObject_TypeCheck(obj, &localtype)); 576 /* If the thread-local object is still alive and not being cleared, 577 remove the corresponding local dict */ 578 self = (localobject *) obj; 579 if (self->dummies != NULL) { 580 PyObject *ldict; 581 ldict = PyDict_GetItem(self->dummies, dummyweakref); 582 if (ldict != NULL) { 583 PyDict_DelItem(self->dummies, dummyweakref); 584 } 585 if (PyErr_Occurred()) 586 PyErr_WriteUnraisable(obj); 587 } 588 Py_DECREF(obj); 589 Py_RETURN_NONE; 590 } 591 592 /* Module functions */ 593 594 struct bootstate { 595 PyInterpreterState *interp; 596 PyObject *func; 597 PyObject *args; 598 PyObject *keyw; 599 PyThreadState *tstate; 600 }; 601 602 static void 603 t_bootstrap(void *boot_raw) 604 { 605 struct bootstate *boot = (struct bootstate *) boot_raw; 606 PyThreadState *tstate; 607 PyObject *res; 608 609 tstate = boot->tstate; 610 tstate->thread_id = PyThread_get_thread_ident(); 611 _PyThreadState_Init(tstate); 612 PyEval_AcquireThread(tstate); 613 nb_threads++; 614 res = PyEval_CallObjectWithKeywords( 615 boot->func, boot->args, boot->keyw); 616 if (res == NULL) { 617 if (PyErr_ExceptionMatches(PyExc_SystemExit)) 618 PyErr_Clear(); 619 else { 620 PyObject *file; 621 PySys_WriteStderr( 622 "Unhandled exception in thread started by "); 623 file = PySys_GetObject("stderr"); 624 if (file) 625 PyFile_WriteObject(boot->func, file, 0); 626 else 627 PyObject_Print(boot->func, stderr, 0); 628 PySys_WriteStderr("\n"); 629 PyErr_PrintEx(0); 630 } 631 } 632 else 633 Py_DECREF(res); 634 Py_DECREF(boot->func); 635 Py_DECREF(boot->args); 636 Py_XDECREF(boot->keyw); 637 PyMem_DEL(boot_raw); 638 nb_threads--; 639 PyThreadState_Clear(tstate); 640 PyThreadState_DeleteCurrent(); 641 PyThread_exit_thread(); 642 } 643 644 static PyObject * 645 thread_PyThread_start_new_thread(PyObject *self, PyObject *fargs) 646 { 647 PyObject *func, *args, *keyw = NULL; 648 struct bootstate *boot; 649 long ident; 650 651 if (!PyArg_UnpackTuple(fargs, "start_new_thread", 2, 3, 652 &func, &args, &keyw)) 653 return NULL; 654 if (!PyCallable_Check(func)) { 655 PyErr_SetString(PyExc_TypeError, 656 "first arg must be callable"); 657 return NULL; 658 } 659 if (!PyTuple_Check(args)) { 660 PyErr_SetString(PyExc_TypeError, 661 "2nd arg must be a tuple"); 662 return NULL; 663 } 664 if (keyw != NULL && !PyDict_Check(keyw)) { 665 PyErr_SetString(PyExc_TypeError, 666 "optional 3rd arg must be a dictionary"); 667 return NULL; 668 } 669 boot = PyMem_NEW(struct bootstate, 1); 670 if (boot == NULL) 671 return PyErr_NoMemory(); 672 boot->interp = PyThreadState_GET()->interp; 673 boot->func = func; 674 boot->args = args; 675 boot->keyw = keyw; 676 boot->tstate = _PyThreadState_Prealloc(boot->interp); 677 if (boot->tstate == NULL) { 678 PyMem_DEL(boot); 679 return PyErr_NoMemory(); 680 } 681 Py_INCREF(func); 682 Py_INCREF(args); 683 Py_XINCREF(keyw); 684 PyEval_InitThreads(); /* Start the interpreter's thread-awareness */ 685 ident = PyThread_start_new_thread(t_bootstrap, (void*) boot); 686 if (ident == -1) { 687 PyErr_SetString(ThreadError, "can't start new thread"); 688 Py_DECREF(func); 689 Py_DECREF(args); 690 Py_XDECREF(keyw); 691 PyThreadState_Clear(boot->tstate); 692 PyMem_DEL(boot); 693 return NULL; 694 } 695 return PyInt_FromLong(ident); 696 } 697 698 PyDoc_STRVAR(start_new_doc, 699 "start_new_thread(function, args[, kwargs])\n\ 700 (start_new() is an obsolete synonym)\n\ 701 \n\ 702 Start a new thread and return its identifier. The thread will call the\n\ 703 function with positional arguments from the tuple args and keyword arguments\n\ 704 taken from the optional dictionary kwargs. The thread exits when the\n\ 705 function returns; the return value is ignored. The thread will also exit\n\ 706 when the function raises an unhandled exception; a stack trace will be\n\ 707 printed unless the exception is SystemExit.\n"); 708 709 static PyObject * 710 thread_PyThread_exit_thread(PyObject *self) 711 { 712 PyErr_SetNone(PyExc_SystemExit); 713 return NULL; 714 } 715 716 PyDoc_STRVAR(exit_doc, 717 "exit()\n\ 718 (PyThread_exit_thread() is an obsolete synonym)\n\ 719 \n\ 720 This is synonymous to ``raise SystemExit''. It will cause the current\n\ 721 thread to exit silently unless the exception is caught."); 722 723 static PyObject * 724 thread_PyThread_interrupt_main(PyObject * self) 725 { 726 PyErr_SetInterrupt(); 727 Py_INCREF(Py_None); 728 return Py_None; 729 } 730 731 PyDoc_STRVAR(interrupt_doc, 732 "interrupt_main()\n\ 733 \n\ 734 Raise a KeyboardInterrupt in the main thread.\n\ 735 A subthread can use this function to interrupt the main thread." 736 ); 737 738 static lockobject *newlockobject(void); 739 740 static PyObject * 741 thread_PyThread_allocate_lock(PyObject *self) 742 { 743 return (PyObject *) newlockobject(); 744 } 745 746 PyDoc_STRVAR(allocate_doc, 747 "allocate_lock() -> lock object\n\ 748 (allocate() is an obsolete synonym)\n\ 749 \n\ 750 Create a new lock object. See help(LockType) for information about locks."); 751 752 static PyObject * 753 thread_get_ident(PyObject *self) 754 { 755 long ident; 756 ident = PyThread_get_thread_ident(); 757 if (ident == -1) { 758 PyErr_SetString(ThreadError, "no current thread ident"); 759 return NULL; 760 } 761 return PyInt_FromLong(ident); 762 } 763 764 PyDoc_STRVAR(get_ident_doc, 765 "get_ident() -> integer\n\ 766 \n\ 767 Return a non-zero integer that uniquely identifies the current thread\n\ 768 amongst other threads that exist simultaneously.\n\ 769 This may be used to identify per-thread resources.\n\ 770 Even though on some platforms threads identities may appear to be\n\ 771 allocated consecutive numbers starting at 1, this behavior should not\n\ 772 be relied upon, and the number should be seen purely as a magic cookie.\n\ 773 A thread's identity may be reused for another thread after it exits."); 774 775 static PyObject * 776 thread__count(PyObject *self) 777 { 778 return PyInt_FromLong(nb_threads); 779 } 780 781 PyDoc_STRVAR(_count_doc, 782 "_count() -> integer\n\ 783 \n\ 784 \ 785 Return the number of currently running Python threads, excluding \n\ 786 the main thread. The returned number comprises all threads created\n\ 787 through `start_new_thread()` as well as `threading.Thread`, and not\n\ 788 yet finished.\n\ 789 \n\ 790 This function is meant for internal and specialized purposes only.\n\ 791 In most applications `threading.enumerate()` should be used instead."); 792 793 static PyObject * 794 thread_stack_size(PyObject *self, PyObject *args) 795 { 796 size_t old_size; 797 Py_ssize_t new_size = 0; 798 int rc; 799 800 if (!PyArg_ParseTuple(args, "|n:stack_size", &new_size)) 801 return NULL; 802 803 if (new_size < 0) { 804 PyErr_SetString(PyExc_ValueError, 805 "size must be 0 or a positive value"); 806 return NULL; 807 } 808 809 old_size = PyThread_get_stacksize(); 810 811 rc = PyThread_set_stacksize((size_t) new_size); 812 if (rc == -1) { 813 PyErr_Format(PyExc_ValueError, 814 "size not valid: %zd bytes", 815 new_size); 816 return NULL; 817 } 818 if (rc == -2) { 819 PyErr_SetString(ThreadError, 820 "setting stack size not supported"); 821 return NULL; 822 } 823 824 return PyInt_FromSsize_t((Py_ssize_t) old_size); 825 } 826 827 PyDoc_STRVAR(stack_size_doc, 828 "stack_size([size]) -> size\n\ 829 \n\ 830 Return the thread stack size used when creating new threads. The\n\ 831 optional size argument specifies the stack size (in bytes) to be used\n\ 832 for subsequently created threads, and must be 0 (use platform or\n\ 833 configured default) or a positive integer value of at least 32,768 (32k).\n\ 834 If changing the thread stack size is unsupported, a ThreadError\n\ 835 exception is raised. If the specified size is invalid, a ValueError\n\ 836 exception is raised, and the stack size is unmodified. 32k bytes\n\ 837 currently the minimum supported stack size value to guarantee\n\ 838 sufficient stack space for the interpreter itself.\n\ 839 \n\ 840 Note that some platforms may have particular restrictions on values for\n\ 841 the stack size, such as requiring a minimum stack size larger than 32kB or\n\ 842 requiring allocation in multiples of the system memory page size\n\ 843 - platform documentation should be referred to for more information\n\ 844 (4kB pages are common; using multiples of 4096 for the stack size is\n\ 845 the suggested approach in the absence of more specific information)."); 846 847 static PyMethodDef thread_methods[] = { 848 {"start_new_thread", (PyCFunction)thread_PyThread_start_new_thread, 849 METH_VARARGS, 850 start_new_doc}, 851 {"start_new", (PyCFunction)thread_PyThread_start_new_thread, 852 METH_VARARGS, 853 start_new_doc}, 854 {"allocate_lock", (PyCFunction)thread_PyThread_allocate_lock, 855 METH_NOARGS, allocate_doc}, 856 {"allocate", (PyCFunction)thread_PyThread_allocate_lock, 857 METH_NOARGS, allocate_doc}, 858 {"exit_thread", (PyCFunction)thread_PyThread_exit_thread, 859 METH_NOARGS, exit_doc}, 860 {"exit", (PyCFunction)thread_PyThread_exit_thread, 861 METH_NOARGS, exit_doc}, 862 {"interrupt_main", (PyCFunction)thread_PyThread_interrupt_main, 863 METH_NOARGS, interrupt_doc}, 864 {"get_ident", (PyCFunction)thread_get_ident, 865 METH_NOARGS, get_ident_doc}, 866 {"_count", (PyCFunction)thread__count, 867 METH_NOARGS, _count_doc}, 868 {"stack_size", (PyCFunction)thread_stack_size, 869 METH_VARARGS, 870 stack_size_doc}, 871 {NULL, NULL} /* sentinel */ 872 }; 873 874 875 /* Initialization function */ 876 877 PyDoc_STRVAR(thread_doc, 878 "This module provides primitive operations to write multi-threaded programs.\n\ 879 The 'threading' module provides a more convenient interface."); 880 881 PyDoc_STRVAR(lock_doc, 882 "A lock object is a synchronization primitive. To create a lock,\n\ 883 call the PyThread_allocate_lock() function. Methods are:\n\ 884 \n\ 885 acquire() -- lock the lock, possibly blocking until it can be obtained\n\ 886 release() -- unlock of the lock\n\ 887 locked() -- test whether the lock is currently locked\n\ 888 \n\ 889 A lock is not owned by the thread that locked it; another thread may\n\ 890 unlock it. A thread attempting to lock a lock that it has already locked\n\ 891 will block until another thread unlocks it. Deadlocks may ensue."); 892 893 PyMODINIT_FUNC 894 initthread(void) 895 { 896 PyObject *m, *d; 897 898 /* Initialize types: */ 899 if (PyType_Ready(&localdummytype) < 0) 900 return; 901 if (PyType_Ready(&localtype) < 0) 902 return; 903 904 /* Create the module and add the functions */ 905 m = Py_InitModule3("thread", thread_methods, thread_doc); 906 if (m == NULL) 907 return; 908 909 /* Add a symbolic constant */ 910 d = PyModule_GetDict(m); 911 ThreadError = PyErr_NewException("thread.error", NULL, NULL); 912 PyDict_SetItemString(d, "error", ThreadError); 913 Locktype.tp_doc = lock_doc; 914 if (PyType_Ready(&Locktype) < 0) 915 return; 916 Py_INCREF(&Locktype); 917 PyDict_SetItemString(d, "LockType", (PyObject *)&Locktype); 918 919 Py_INCREF(&localtype); 920 if (PyModule_AddObject(m, "_local", (PyObject *)&localtype) < 0) 921 return; 922 923 nb_threads = 0; 924 925 str_dict = PyString_InternFromString("__dict__"); 926 if (str_dict == NULL) 927 return; 928 929 /* Initialize the C thread library */ 930 PyThread_init_thread(); 931 } 932
