diff options
| -rw-r--r-- | Doc/library/_dummy_thread.rst | 17 | ||||
| -rw-r--r-- | Doc/library/_thread.rst | 10 | ||||
| -rw-r--r-- | Doc/library/concurrency.rst | 2 | ||||
| -rw-r--r-- | Doc/library/dummy_threading.rst | 17 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 4 | ||||
| -rw-r--r-- | Lib/_dummy_thread.py | 163 | ||||
| -rw-r--r-- | Lib/dummy_threading.py | 78 | ||||
| -rw-r--r-- | Lib/test/test_dummy_thread.py | 255 | ||||
| -rw-r--r-- | Lib/test/test_dummy_threading.py | 60 |
9 files changed, 575 insertions, 31 deletions
diff --git a/Doc/library/_dummy_thread.rst b/Doc/library/_dummy_thread.rst index ebce74d..7dccbc5 100644 --- a/Doc/library/_dummy_thread.rst +++ b/Doc/library/_dummy_thread.rst @@ -6,18 +6,15 @@ **Source code:** :source:`Lib/_dummy_thread.py` --------------- - -This module provides a duplicate interface to the :mod:`_thread` module. It is -meant to be imported when the :mod:`_thread` module is not provided on a -platform. +.. deprecated:: 3.7 + Python now always has threading enabled. Please use :mod:`_thread` + (or, better, :mod:`threading`) instead. -Suggested usage is:: +-------------- - try: - import _thread - except ImportError: - import _dummy_thread as _thread +This module provides a duplicate interface to the :mod:`_thread` module. +It was meant to be imported when the :mod:`_thread` module was not provided +on a platform. Be careful to not use this module where deadlock might occur from a thread being created that blocks waiting for another thread to be created. This often occurs diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst index 0d2d818..67cb709 100644 --- a/Doc/library/_thread.rst +++ b/Doc/library/_thread.rst @@ -23,14 +23,10 @@ threading API built on top of this module. single: pthreads pair: threads; POSIX -The module is optional. It is supported on Windows, Linux, SGI IRIX, Solaris -2.x, as well as on systems that have a POSIX thread (a.k.a. "pthread") -implementation. For systems lacking the :mod:`_thread` module, the -:mod:`_dummy_thread` module is available. It duplicates this module's interface -and can be used as a drop-in replacement. - -It defines the following constants and functions: +.. versionchanged:: 3.7 + This module used to be optional, it is now always available. +This module defines the following constants and functions: .. exception:: error diff --git a/Doc/library/concurrency.rst b/Doc/library/concurrency.rst index 0de281b..826bf86 100644 --- a/Doc/library/concurrency.rst +++ b/Doc/library/concurrency.rst @@ -26,6 +26,6 @@ The following are support modules for some of the above services: .. toctree:: - dummy_threading.rst _thread.rst _dummy_thread.rst + dummy_threading.rst diff --git a/Doc/library/dummy_threading.rst b/Doc/library/dummy_threading.rst index 30a3ebb..dfc3289 100644 --- a/Doc/library/dummy_threading.rst +++ b/Doc/library/dummy_threading.rst @@ -6,20 +6,15 @@ **Source code:** :source:`Lib/dummy_threading.py` --------------- - -This module provides a duplicate interface to the :mod:`threading` module. It -is meant to be imported when the :mod:`_thread` module is not provided on a -platform. +.. deprecated:: 3.7 + Python now always has threading enabled. Please use :mod:`threading` instead. -Suggested usage is:: +-------------- - try: - import threading - except ImportError: - import dummy_threading as threading +This module provides a duplicate interface to the :mod:`threading` module. +It was meant to be imported when the :mod:`_thread` module was not provided +on a platform. Be careful to not use this module where deadlock might occur from a thread being created that blocks waiting for another thread to be created. This often occurs with blocking I/O. - diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 021e29e..8c3a2cd 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -11,8 +11,8 @@ This module constructs higher-level threading interfaces on top of the lower level :mod:`_thread` module. See also the :mod:`queue` module. -The :mod:`dummy_threading` module is provided for situations where -:mod:`threading` cannot be used because :mod:`_thread` is missing. +.. versionchanged:: 3.7 + This module used to be optional, it is now always available. .. note:: diff --git a/Lib/_dummy_thread.py b/Lib/_dummy_thread.py new file mode 100644 index 0000000..a2cae54 --- /dev/null +++ b/Lib/_dummy_thread.py @@ -0,0 +1,163 @@ +"""Drop-in replacement for the thread module. + +Meant to be used as a brain-dead substitute so that threaded code does +not need to be rewritten for when the thread module is not present. + +Suggested usage is:: + + try: + import _thread + except ImportError: + import _dummy_thread as _thread + +""" +# Exports only things specified by thread documentation; +# skipping obsolete synonyms allocate(), start_new(), exit_thread(). +__all__ = ['error', 'start_new_thread', 'exit', 'get_ident', 'allocate_lock', + 'interrupt_main', 'LockType'] + +# A dummy value +TIMEOUT_MAX = 2**31 + +# NOTE: this module can be imported early in the extension building process, +# and so top level imports of other modules should be avoided. Instead, all +# imports are done when needed on a function-by-function basis. Since threads +# are disabled, the import lock should not be an issue anyway (??). + +error = RuntimeError + +def start_new_thread(function, args, kwargs={}): + """Dummy implementation of _thread.start_new_thread(). + + Compatibility is maintained by making sure that ``args`` is a + tuple and ``kwargs`` is a dictionary. If an exception is raised + and it is SystemExit (which can be done by _thread.exit()) it is + caught and nothing is done; all other exceptions are printed out + by using traceback.print_exc(). + + If the executed function calls interrupt_main the KeyboardInterrupt will be + raised when the function returns. + + """ + if type(args) != type(tuple()): + raise TypeError("2nd arg must be a tuple") + if type(kwargs) != type(dict()): + raise TypeError("3rd arg must be a dict") + global _main + _main = False + try: + function(*args, **kwargs) + except SystemExit: + pass + except: + import traceback + traceback.print_exc() + _main = True + global _interrupt + if _interrupt: + _interrupt = False + raise KeyboardInterrupt + +def exit(): + """Dummy implementation of _thread.exit().""" + raise SystemExit + +def get_ident(): + """Dummy implementation of _thread.get_ident(). + + Since this module should only be used when _threadmodule is not + available, it is safe to assume that the current process is the + only thread. Thus a constant can be safely returned. + """ + return 1 + +def allocate_lock(): + """Dummy implementation of _thread.allocate_lock().""" + return LockType() + +def stack_size(size=None): + """Dummy implementation of _thread.stack_size().""" + if size is not None: + raise error("setting thread stack size not supported") + return 0 + +def _set_sentinel(): + """Dummy implementation of _thread._set_sentinel().""" + return LockType() + +class LockType(object): + """Class implementing dummy implementation of _thread.LockType. + + Compatibility is maintained by maintaining self.locked_status + which is a boolean that stores the state of the lock. Pickling of + the lock, though, should not be done since if the _thread module is + then used with an unpickled ``lock()`` from here problems could + occur from this class not having atomic methods. + + """ + + def __init__(self): + self.locked_status = False + + def acquire(self, waitflag=None, timeout=-1): + """Dummy implementation of acquire(). + + For blocking calls, self.locked_status is automatically set to + True and returned appropriately based on value of + ``waitflag``. If it is non-blocking, then the value is + actually checked and not set if it is already acquired. This + is all done so that threading.Condition's assert statements + aren't triggered and throw a little fit. + + """ + if waitflag is None or waitflag: + self.locked_status = True + return True + else: + if not self.locked_status: + self.locked_status = True + return True + else: + if timeout > 0: + import time + time.sleep(timeout) + return False + + __enter__ = acquire + + def __exit__(self, typ, val, tb): + self.release() + + def release(self): + """Release the dummy lock.""" + # XXX Perhaps shouldn't actually bother to test? Could lead + # to problems for complex, threaded code. + if not self.locked_status: + raise error + self.locked_status = False + return True + + def locked(self): + return self.locked_status + + def __repr__(self): + return "<%s %s.%s object at %s>" % ( + "locked" if self.locked_status else "unlocked", + self.__class__.__module__, + self.__class__.__qualname__, + hex(id(self)) + ) + +# Used to signal that interrupt_main was called in a "thread" +_interrupt = False +# True when not executing in a "thread" +_main = True + +def interrupt_main(): + """Set _interrupt flag to True to have start_new_thread raise + KeyboardInterrupt upon exiting.""" + if _main: + raise KeyboardInterrupt + else: + global _interrupt + _interrupt = True diff --git a/Lib/dummy_threading.py b/Lib/dummy_threading.py new file mode 100644 index 0000000..1bb7eee --- /dev/null +++ b/Lib/dummy_threading.py @@ -0,0 +1,78 @@ +"""Faux ``threading`` version using ``dummy_thread`` instead of ``thread``. + +The module ``_dummy_threading`` is added to ``sys.modules`` in order +to not have ``threading`` considered imported. Had ``threading`` been +directly imported it would have made all subsequent imports succeed +regardless of whether ``_thread`` was available which is not desired. + +""" +from sys import modules as sys_modules + +import _dummy_thread + +# Declaring now so as to not have to nest ``try``s to get proper clean-up. +holding_thread = False +holding_threading = False +holding__threading_local = False + +try: + # Could have checked if ``_thread`` was not in sys.modules and gone + # a different route, but decided to mirror technique used with + # ``threading`` below. + if '_thread' in sys_modules: + held_thread = sys_modules['_thread'] + holding_thread = True + # Must have some module named ``_thread`` that implements its API + # in order to initially import ``threading``. + sys_modules['_thread'] = sys_modules['_dummy_thread'] + + if 'threading' in sys_modules: + # If ``threading`` is already imported, might as well prevent + # trying to import it more than needed by saving it if it is + # already imported before deleting it. + held_threading = sys_modules['threading'] + holding_threading = True + del sys_modules['threading'] + + if '_threading_local' in sys_modules: + # If ``_threading_local`` is already imported, might as well prevent + # trying to import it more than needed by saving it if it is + # already imported before deleting it. + held__threading_local = sys_modules['_threading_local'] + holding__threading_local = True + del sys_modules['_threading_local'] + + import threading + # Need a copy of the code kept somewhere... + sys_modules['_dummy_threading'] = sys_modules['threading'] + del sys_modules['threading'] + sys_modules['_dummy__threading_local'] = sys_modules['_threading_local'] + del sys_modules['_threading_local'] + from _dummy_threading import * + from _dummy_threading import __all__ + +finally: + # Put back ``threading`` if we overwrote earlier + + if holding_threading: + sys_modules['threading'] = held_threading + del held_threading + del holding_threading + + # Put back ``_threading_local`` if we overwrote earlier + + if holding__threading_local: + sys_modules['_threading_local'] = held__threading_local + del held__threading_local + del holding__threading_local + + # Put back ``thread`` if we overwrote, else del the entry we made + if holding_thread: + sys_modules['_thread'] = held_thread + del held_thread + else: + del sys_modules['_thread'] + del holding_thread + + del _dummy_thread + del sys_modules diff --git a/Lib/test/test_dummy_thread.py b/Lib/test/test_dummy_thread.py new file mode 100644 index 0000000..0840be6 --- /dev/null +++ b/Lib/test/test_dummy_thread.py @@ -0,0 +1,255 @@ +import _dummy_thread as _thread +import time +import queue +import random +import unittest +from test import support +from unittest import mock + +DELAY = 0 + + +class LockTests(unittest.TestCase): + """Test lock objects.""" + + def setUp(self): + # Create a lock + self.lock = _thread.allocate_lock() + + def test_initlock(self): + #Make sure locks start locked + self.assertFalse(self.lock.locked(), + "Lock object is not initialized unlocked.") + + def test_release(self): + # Test self.lock.release() + self.lock.acquire() + self.lock.release() + self.assertFalse(self.lock.locked(), + "Lock object did not release properly.") + + def test_LockType_context_manager(self): + with _thread.LockType(): + pass + self.assertFalse(self.lock.locked(), + "Acquired Lock was not released") + + def test_improper_release(self): + #Make sure release of an unlocked thread raises RuntimeError + self.assertRaises(RuntimeError, self.lock.release) + + def test_cond_acquire_success(self): + #Make sure the conditional acquiring of the lock works. + self.assertTrue(self.lock.acquire(0), + "Conditional acquiring of the lock failed.") + + def test_cond_acquire_fail(self): + #Test acquiring locked lock returns False + self.lock.acquire(0) + self.assertFalse(self.lock.acquire(0), + "Conditional acquiring of a locked lock incorrectly " + "succeeded.") + + def test_uncond_acquire_success(self): + #Make sure unconditional acquiring of a lock works. + self.lock.acquire() + self.assertTrue(self.lock.locked(), + "Uncondional locking failed.") + + def test_uncond_acquire_return_val(self): + #Make sure that an unconditional locking returns True. + self.assertIs(self.lock.acquire(1), True, + "Unconditional locking did not return True.") + self.assertIs(self.lock.acquire(), True) + + def test_uncond_acquire_blocking(self): + #Make sure that unconditional acquiring of a locked lock blocks. + def delay_unlock(to_unlock, delay): + """Hold on to lock for a set amount of time before unlocking.""" + time.sleep(delay) + to_unlock.release() + + self.lock.acquire() + start_time = int(time.time()) + _thread.start_new_thread(delay_unlock,(self.lock, DELAY)) + if support.verbose: + print() + print("*** Waiting for thread to release the lock "\ + "(approx. %s sec.) ***" % DELAY) + self.lock.acquire() + end_time = int(time.time()) + if support.verbose: + print("done") + self.assertGreaterEqual(end_time - start_time, DELAY, + "Blocking by unconditional acquiring failed.") + + @mock.patch('time.sleep') + def test_acquire_timeout(self, mock_sleep): + """Test invoking acquire() with a positive timeout when the lock is + already acquired. Ensure that time.sleep() is invoked with the given + timeout and that False is returned.""" + + self.lock.acquire() + retval = self.lock.acquire(waitflag=0, timeout=1) + self.assertTrue(mock_sleep.called) + mock_sleep.assert_called_once_with(1) + self.assertEqual(retval, False) + + def test_lock_representation(self): + self.lock.acquire() + self.assertIn("locked", repr(self.lock)) + self.lock.release() + self.assertIn("unlocked", repr(self.lock)) + + +class MiscTests(unittest.TestCase): + """Miscellaneous tests.""" + + def test_exit(self): + self.assertRaises(SystemExit, _thread.exit) + + def test_ident(self): + self.assertIsInstance(_thread.get_ident(), int, + "_thread.get_ident() returned a non-integer") + self.assertGreater(_thread.get_ident(), 0) + + def test_LockType(self): + self.assertIsInstance(_thread.allocate_lock(), _thread.LockType, + "_thread.LockType is not an instance of what " + "is returned by _thread.allocate_lock()") + + def test_set_sentinel(self): + self.assertIsInstance(_thread._set_sentinel(), _thread.LockType, + "_thread._set_sentinel() did not return a " + "LockType instance.") + + def test_interrupt_main(self): + #Calling start_new_thread with a function that executes interrupt_main + # should raise KeyboardInterrupt upon completion. + def call_interrupt(): + _thread.interrupt_main() + + self.assertRaises(KeyboardInterrupt, + _thread.start_new_thread, + call_interrupt, + tuple()) + + def test_interrupt_in_main(self): + self.assertRaises(KeyboardInterrupt, _thread.interrupt_main) + + def test_stack_size_None(self): + retval = _thread.stack_size(None) + self.assertEqual(retval, 0) + + def test_stack_size_not_None(self): + with self.assertRaises(_thread.error) as cm: + _thread.stack_size("") + self.assertEqual(cm.exception.args[0], + "setting thread stack size not supported") + + +class ThreadTests(unittest.TestCase): + """Test thread creation.""" + + def test_arg_passing(self): + #Make sure that parameter passing works. + def arg_tester(queue, arg1=False, arg2=False): + """Use to test _thread.start_new_thread() passes args properly.""" + queue.put((arg1, arg2)) + + testing_queue = queue.Queue(1) + _thread.start_new_thread(arg_tester, (testing_queue, True, True)) + result = testing_queue.get() + self.assertTrue(result[0] and result[1], + "Argument passing for thread creation " + "using tuple failed") + + _thread.start_new_thread( + arg_tester, + tuple(), + {'queue':testing_queue, 'arg1':True, 'arg2':True}) + + result = testing_queue.get() + self.assertTrue(result[0] and result[1], + "Argument passing for thread creation " + "using kwargs failed") + + _thread.start_new_thread( + arg_tester, + (testing_queue, True), + {'arg2':True}) + + result = testing_queue.get() + self.assertTrue(result[0] and result[1], + "Argument passing for thread creation using both tuple" + " and kwargs failed") + + def test_multi_thread_creation(self): + def queue_mark(queue, delay): + time.sleep(delay) + queue.put(_thread.get_ident()) + + thread_count = 5 + testing_queue = queue.Queue(thread_count) + + if support.verbose: + print() + print("*** Testing multiple thread creation " + "(will take approx. %s to %s sec.) ***" % ( + DELAY, thread_count)) + + for count in range(thread_count): + if DELAY: + local_delay = round(random.random(), 1) + else: + local_delay = 0 + _thread.start_new_thread(queue_mark, + (testing_queue, local_delay)) + time.sleep(DELAY) + if support.verbose: + print('done') + self.assertEqual(testing_queue.qsize(), thread_count, + "Not all %s threads executed properly " + "after %s sec." % (thread_count, DELAY)) + + def test_args_not_tuple(self): + """ + Test invoking start_new_thread() with a non-tuple value for "args". + Expect TypeError with a meaningful error message to be raised. + """ + with self.assertRaises(TypeError) as cm: + _thread.start_new_thread(mock.Mock(), []) + self.assertEqual(cm.exception.args[0], "2nd arg must be a tuple") + + def test_kwargs_not_dict(self): + """ + Test invoking start_new_thread() with a non-dict value for "kwargs". + Expect TypeError with a meaningful error message to be raised. + """ + with self.assertRaises(TypeError) as cm: + _thread.start_new_thread(mock.Mock(), tuple(), kwargs=[]) + self.assertEqual(cm.exception.args[0], "3rd arg must be a dict") + + def test_SystemExit(self): + """ + Test invoking start_new_thread() with a function that raises + SystemExit. + The exception should be discarded. + """ + func = mock.Mock(side_effect=SystemExit()) + try: + _thread.start_new_thread(func, tuple()) + except SystemExit: + self.fail("start_new_thread raised SystemExit.") + + @mock.patch('traceback.print_exc') + def test_RaiseException(self, mock_print_exc): + """ + Test invoking start_new_thread() with a function that raises exception. + + The exception should be discarded and the traceback should be printed + via traceback.print_exc() + """ + func = mock.Mock(side_effect=Exception) + _thread.start_new_thread(func, tuple()) + self.assertTrue(mock_print_exc.called) diff --git a/Lib/test/test_dummy_threading.py b/Lib/test/test_dummy_threading.py new file mode 100644 index 0000000..a0c2972 --- /dev/null +++ b/Lib/test/test_dummy_threading.py @@ -0,0 +1,60 @@ +from test import support +import unittest +import dummy_threading as _threading +import time + +class DummyThreadingTestCase(unittest.TestCase): + + class TestThread(_threading.Thread): + + def run(self): + global running + global sema + global mutex + # Uncomment if testing another module, such as the real 'threading' + # module. + #delay = random.random() * 2 + delay = 0 + if support.verbose: + print('task', self.name, 'will run for', delay, 'sec') + sema.acquire() + mutex.acquire() + running += 1 + if support.verbose: + print(running, 'tasks are running') + mutex.release() + time.sleep(delay) + if support.verbose: + print('task', self.name, 'done') + mutex.acquire() + running -= 1 + if support.verbose: + print(self.name, 'is finished.', running, 'tasks are running') + mutex.release() + sema.release() + + def setUp(self): + self.numtasks = 10 + global sema + sema = _threading.BoundedSemaphore(value=3) + global mutex + mutex = _threading.RLock() + global running + running = 0 + self.threads = [] + + def test_tasks(self): + for i in range(self.numtasks): + t = self.TestThread(name="<thread %d>"%i) + self.threads.append(t) + t.start() + + if support.verbose: + print('waiting for all tasks to complete') + for t in self.threads: + t.join() + if support.verbose: + print('all tasks done') + +if __name__ == '__main__': + unittest.main() |