3 /* Interface to Sjoerd's portable C thread library */
6 #include "structmember.h" /* offsetof */
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'."
16 static PyObject *ThreadError;
17 static PyObject *str_dict;
18 static long nb_threads = 0;
24 PyThread_type_lock lock_lock;
25 PyObject *in_weakreflist;
29 lock_dealloc(lockobject *self)
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);
38 PyThread_free_lock(self->lock_lock);
44 lock_PyThread_acquire_lock(lockobject *self, PyObject *args)
48 if (!PyArg_ParseTuple(args, "|i:acquire", &i))
51 Py_BEGIN_ALLOW_THREADS
52 i = PyThread_acquire_lock(self->lock_lock, i);
55 return PyBool_FromLong((long)i);
58 PyDoc_STRVAR(acquire_doc,
59 "acquire([wait]) -> None or bool\n\
60 (acquire_lock() is an obsolete synonym)\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.");
70 lock_PyThread_release_lock(lockobject *self)
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");
79 PyThread_release_lock(self->lock_lock);
84 PyDoc_STRVAR(release_doc,
86 (release_lock() is an obsolete synonym)\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.");
93 lock_locked_lock(lockobject *self)
95 if (PyThread_acquire_lock(self->lock_lock, 0)) {
96 PyThread_release_lock(self->lock_lock);
97 return PyBool_FromLong(0L);
99 return PyBool_FromLong(1L);
102 PyDoc_STRVAR(locked_doc,
104 (locked_lock() is an obsolete synonym)\n\
106 Return whether the lock is in the locked state.");
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 */
128 static PyTypeObject Locktype = {
129 PyVarObject_HEAD_INIT(&PyType_Type, 0)
130 "thread.lock", /*tp_name*/
131 sizeof(lockobject), /*tp_size*/
134 (destructor)lock_dealloc, /*tp_dealloc*/
140 0, /* tp_as_number */
141 0, /* tp_as_sequence */
142 0, /* tp_as_mapping */
148 0, /* tp_as_buffer */
149 Py_TPFLAGS_HAVE_WEAKREFS, /* tp_flags */
153 0, /* tp_richcompare */
154 offsetof(lockobject, in_weakreflist), /* tp_weaklistoffset */
157 lock_methods, /* tp_methods */
164 self = PyObject_New(lockobject, &Locktype);
167 self->lock_lock = PyThread_allocate_lock();
168 self->in_weakreflist = NULL;
169 if (self->lock_lock == NULL) {
171 PyErr_SetString(ThreadError, "can't allocate lock");
177 /* Thread-local objects */
179 #include "structmember.h"
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.
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.
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
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.
222 PyObject *localdict; /* Borrowed reference! */
223 PyObject *weakreflist; /* List of weak references to self */
227 localdummy_dealloc(localdummyobject *self)
229 if (self->weakreflist != NULL)
230 PyObject_ClearWeakRefs((PyObject *) self);
231 Py_TYPE(self)->tp_free((PyObject*)self);
234 static PyTypeObject localdummytype = {
235 PyVarObject_HEAD_INIT(NULL, 0)
236 /* tp_name */ "_thread._localdummy",
237 /* tp_basicsize */ sizeof(localdummyobject),
239 /* tp_dealloc */ (destructor)localdummy_dealloc,
245 /* tp_as_number */ 0,
246 /* tp_as_sequence */ 0,
247 /* tp_as_mapping */ 0,
253 /* tp_as_buffer */ 0,
254 /* tp_flags */ Py_TPFLAGS_DEFAULT,
255 /* tp_doc */ "Thread-local dummy",
258 /* tp_richcompare */ 0,
259 /* tp_weaklistoffset */ offsetof(localdummyobject, weakreflist)
268 PyObject *weakreflist; /* List of weak references to self */
269 /* A {localdummy weakref -> localdict} dict */
271 /* The callback for weakrefs to localdummies */
272 PyObject *wr_callback;
275 /* Forward declaration */
276 static PyObject *_ldict(localobject *self);
277 static PyObject *_localdummy_destroyed(PyObject *meth_self, PyObject *dummyweakref);
279 /* Create and register the dummy for the current thread.
280 Returns a borrowed reference of the corresponding local dict */
282 _local_create_dummy(localobject *self)
284 PyObject *tdict, *ldict = NULL, *wr = NULL;
285 localdummyobject *dummy = NULL;
288 tdict = PyThreadState_GetDict();
290 PyErr_SetString(PyExc_SystemError,
291 "Couldn't get thread-state dictionary");
295 ldict = PyDict_New();
298 dummy = (localdummyobject *) localdummytype.tp_alloc(&localdummytype, 0);
301 dummy->localdict = ldict;
302 wr = PyWeakref_NewRef((PyObject *) dummy, self->wr_callback);
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);
312 r = PyDict_SetItem(tdict, self->key, (PyObject *) dummy);
328 local_new(PyTypeObject *type, PyObject *args, PyObject *kw)
332 static PyMethodDef wr_callback_def = {
333 "_localdummy_destroyed", (PyCFunction) _localdummy_destroyed, METH_O
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");
344 self = (localobject *)type->tp_alloc(type, 0);
352 self->key = PyString_FromFormat("thread.local.%p", self);
353 if (self->key == NULL)
356 self->dummies = PyDict_New();
357 if (self->dummies == NULL)
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);
365 self->wr_callback = PyCFunction_New(&wr_callback_def, wr);
367 if (self->wr_callback == NULL)
370 if (_local_create_dummy(self) == NULL)
373 return (PyObject *)self;
381 local_traverse(localobject *self, visitproc visit, void *arg)
383 Py_VISIT(self->args);
385 Py_VISIT(self->dummies);
390 local_clear(localobject *self)
392 PyThreadState *tstate;
393 Py_CLEAR(self->args);
395 Py_CLEAR(self->dummies);
396 Py_CLEAR(self->wr_callback);
397 /* Remove all strong references to dummies from the thread states */
399 && (tstate = PyThreadState_Get())
401 for(tstate = PyInterpreterState_ThreadHead(tstate->interp);
403 tstate = PyThreadState_Next(tstate))
405 PyDict_GetItem(tstate->dict, self->key))
406 PyDict_DelItem(tstate->dict, self->key);
412 local_dealloc(localobject *self)
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);
419 PyObject_GC_UnTrack(self);
422 Py_XDECREF(self->key);
423 Py_TYPE(self)->tp_free((PyObject*)self);
426 /* Returns a borrowed reference to the local dict, creating it if necessary */
428 _ldict(localobject *self)
430 PyObject *tdict, *ldict, *dummy;
432 tdict = PyThreadState_GetDict();
434 PyErr_SetString(PyExc_SystemError,
435 "Couldn't get thread-state dictionary");
439 dummy = PyDict_GetItem(tdict, self->key);
441 ldict = _local_create_dummy(self);
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
451 PyDict_DelItem(tdict, self->key);
456 assert(Py_TYPE(dummy) == &localdummytype);
457 ldict = ((localdummyobject *) dummy)->localdict;
464 local_setattro(localobject *self, PyObject *name, PyObject *v)
469 ldict = _ldict(self);
473 r = PyObject_RichCompareBool(name, str_dict, Py_EQ);
475 PyErr_Format(PyExc_AttributeError,
476 "'%.50s' object attribute '__dict__' is read-only",
477 Py_TYPE(self)->tp_name);
483 return _PyObject_GenericSetAttrWithDict((PyObject *)self, name, v, ldict);
486 static PyObject *local_getattro(localobject *, PyObject *);
488 static PyTypeObject localtype = {
489 PyVarObject_HEAD_INIT(NULL, 0)
490 /* tp_name */ "thread._local",
491 /* tp_basicsize */ sizeof(localobject),
493 /* tp_dealloc */ (destructor)local_dealloc,
499 /* tp_as_number */ 0,
500 /* tp_as_sequence */ 0,
501 /* tp_as_mapping */ 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),
521 /* tp_dict */ 0, /* internal use */
522 /* tp_descr_get */ 0,
523 /* tp_descr_set */ 0,
524 /* tp_dictoffset */ 0,
527 /* tp_new */ local_new,
528 /* tp_free */ 0, /* Low-level free-mem routine */
529 /* tp_is_gc */ 0, /* For PyObject_IS_GC */
533 local_getattro(localobject *self, PyObject *name)
535 PyObject *ldict, *value;
538 ldict = _ldict(self);
542 r = PyObject_RichCompareBool(name, str_dict, Py_EQ);
550 if (Py_TYPE(self) != &localtype)
551 /* use generic lookup for subtypes */
552 return _PyObject_GenericGetAttrWithDict((PyObject *)self, name, ldict);
554 /* Optimization: just look in dict ourselves */
555 value = PyDict_GetItem(ldict, name);
557 /* Fall back on generic to get __class__ and __dict__ */
558 return _PyObject_GenericGetAttrWithDict((PyObject *)self, name, ldict);
564 /* Called when a dummy is destroyed. */
566 _localdummy_destroyed(PyObject *localweakref, PyObject *dummyweakref)
570 assert(PyWeakref_CheckRef(localweakref));
571 obj = PyWeakref_GET_OBJECT(localweakref);
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) {
581 ldict = PyDict_GetItem(self->dummies, dummyweakref);
583 PyDict_DelItem(self->dummies, dummyweakref);
585 if (PyErr_Occurred())
586 PyErr_WriteUnraisable(obj);
592 /* Module functions */
595 PyInterpreterState *interp;
599 PyThreadState *tstate;
603 t_bootstrap(void *boot_raw)
605 struct bootstate *boot = (struct bootstate *) boot_raw;
606 PyThreadState *tstate;
609 tstate = boot->tstate;
610 tstate->thread_id = PyThread_get_thread_ident();
611 _PyThreadState_Init(tstate);
612 PyEval_AcquireThread(tstate);
614 res = PyEval_CallObjectWithKeywords(
615 boot->func, boot->args, boot->keyw);
617 if (PyErr_ExceptionMatches(PyExc_SystemExit))
622 "Unhandled exception in thread started by ");
623 file = PySys_GetObject("stderr");
625 PyFile_WriteObject(boot->func, file, 0);
627 PyObject_Print(boot->func, stderr, 0);
628 PySys_WriteStderr("\n");
634 Py_DECREF(boot->func);
635 Py_DECREF(boot->args);
636 Py_XDECREF(boot->keyw);
639 PyThreadState_Clear(tstate);
640 PyThreadState_DeleteCurrent();
641 PyThread_exit_thread();
645 thread_PyThread_start_new_thread(PyObject *self, PyObject *fargs)
647 PyObject *func, *args, *keyw = NULL;
648 struct bootstate *boot;
651 if (!PyArg_UnpackTuple(fargs, "start_new_thread", 2, 3,
652 &func, &args, &keyw))
654 if (!PyCallable_Check(func)) {
655 PyErr_SetString(PyExc_TypeError,
656 "first arg must be callable");
659 if (!PyTuple_Check(args)) {
660 PyErr_SetString(PyExc_TypeError,
661 "2nd arg must be a tuple");
664 if (keyw != NULL && !PyDict_Check(keyw)) {
665 PyErr_SetString(PyExc_TypeError,
666 "optional 3rd arg must be a dictionary");
669 boot = PyMem_NEW(struct bootstate, 1);
671 return PyErr_NoMemory();
672 boot->interp = PyThreadState_GET()->interp;
676 boot->tstate = _PyThreadState_Prealloc(boot->interp);
677 if (boot->tstate == NULL) {
679 return PyErr_NoMemory();
684 PyEval_InitThreads(); /* Start the interpreter's thread-awareness */
685 ident = PyThread_start_new_thread(t_bootstrap, (void*) boot);
687 PyErr_SetString(ThreadError, "can't start new thread");
691 PyThreadState_Clear(boot->tstate);
695 return PyInt_FromLong(ident);
698 PyDoc_STRVAR(start_new_doc,
699 "start_new_thread(function, args[, kwargs])\n\
700 (start_new() is an obsolete synonym)\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");
710 thread_PyThread_exit_thread(PyObject *self)
712 PyErr_SetNone(PyExc_SystemExit);
716 PyDoc_STRVAR(exit_doc,
718 (PyThread_exit_thread() is an obsolete synonym)\n\
720 This is synonymous to ``raise SystemExit''. It will cause the current\n\
721 thread to exit silently unless the exception is caught.");
724 thread_PyThread_interrupt_main(PyObject * self)
726 PyErr_SetInterrupt();
731 PyDoc_STRVAR(interrupt_doc,
734 Raise a KeyboardInterrupt in the main thread.\n\
735 A subthread can use this function to interrupt the main thread."
738 static lockobject *newlockobject(void);
741 thread_PyThread_allocate_lock(PyObject *self)
743 return (PyObject *) newlockobject();
746 PyDoc_STRVAR(allocate_doc,
747 "allocate_lock() -> lock object\n\
748 (allocate() is an obsolete synonym)\n\
750 Create a new lock object. See help(LockType) for information about locks.");
753 thread_get_ident(PyObject *self)
756 ident = PyThread_get_thread_ident();
758 PyErr_SetString(ThreadError, "no current thread ident");
761 return PyInt_FromLong(ident);
764 PyDoc_STRVAR(get_ident_doc,
765 "get_ident() -> integer\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.");
776 thread__count(PyObject *self)
778 return PyInt_FromLong(nb_threads);
781 PyDoc_STRVAR(_count_doc,
782 "_count() -> integer\n\
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\
790 This function is meant for internal and specialized purposes only.\n\
791 In most applications `threading.enumerate()` should be used instead.");
794 thread_stack_size(PyObject *self, PyObject *args)
797 Py_ssize_t new_size = 0;
800 if (!PyArg_ParseTuple(args, "|n:stack_size", &new_size))
804 PyErr_SetString(PyExc_ValueError,
805 "size must be 0 or a positive value");
809 old_size = PyThread_get_stacksize();
811 rc = PyThread_set_stacksize((size_t) new_size);
813 PyErr_Format(PyExc_ValueError,
814 "size not valid: %zd bytes",
819 PyErr_SetString(ThreadError,
820 "setting stack size not supported");
824 return PyInt_FromSsize_t((Py_ssize_t) old_size);
827 PyDoc_STRVAR(stack_size_doc,
828 "stack_size([size]) -> size\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\
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).");
847 static PyMethodDef thread_methods[] = {
848 {"start_new_thread", (PyCFunction)thread_PyThread_start_new_thread,
851 {"start_new", (PyCFunction)thread_PyThread_start_new_thread,
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,
871 {NULL, NULL} /* sentinel */
875 /* Initialization function */
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.");
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\
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\
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.");
898 /* Initialize types: */
899 if (PyType_Ready(&localdummytype) < 0)
901 if (PyType_Ready(&localtype) < 0)
904 /* Create the module and add the functions */
905 m = Py_InitModule3("thread", thread_methods, thread_doc);
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)
916 Py_INCREF(&Locktype);
917 PyDict_SetItemString(d, "LockType", (PyObject *)&Locktype);
919 Py_INCREF(&localtype);
920 if (PyModule_AddObject(m, "_local", (PyObject *)&localtype) < 0)
925 str_dict = PyString_InternFromString("__dict__");
926 if (str_dict == NULL)
929 /* Initialize the C thread library */
930 PyThread_init_thread();