You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.rst
+39-43Lines changed: 39 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,13 @@
2
2
Timed Threads
3
3
==============
4
4
5
-
Adds the ability to set absolute time deadlines on asynchronous threads, and allows one thread to stop
6
-
another by means of raising an exception.
5
+
Adds the ability to set relative elapsed time deadlines on asynchronous threads, and allows one thread to stop another by means of raising an exception.
6
+
7
+
Note that due to the GIL lock in Python 3.14, this does not give us any more concurrency.
8
+
9
+
It is hoped that in the future, in conjunction with an implementation of Python that does not have a global GIL lock there can be and implementation that improves concurrency of hardware threads.
10
+
11
+
The main motivation of this module is to support TimedConstraint in the open-source implementation of Mathematica, called Mathics3.
7
12
8
13
9
14
Overview
@@ -18,7 +23,7 @@ This module provides:
18
23
19
24
- decorators that may stop its decorated callables on timeout.
20
25
21
-
Developed and tested with CPython 3.9+ using Python's threading model.
26
+
Developed and tested with CPython 3.10+ using Python's threading model.
22
27
23
28
.. note::
24
29
@@ -29,45 +34,35 @@ Developed and tested with CPython 3.9+ using Python's threading model.
29
34
Installation
30
35
============
31
36
32
-
Using ``stopit`` in your application
33
-
------------------------------------
34
-
35
-
Both work identically:
36
-
37
37
.. code:: bash
38
38
39
-
pip install -e .
39
+
pip install Timed-Threads
40
40
41
-
Developing ``stopit``
42
-
---------------------
41
+
42
+
To install from source:
43
43
44
44
.. code:: bash
45
45
46
-
# You should prefer forking if you have a Github account
47
-
git clone https://github.com/glenfant/stopit.git
48
-
cd stopit
49
-
python setup.py develop
46
+
pip install -e .
50
47
51
-
# Does it work for you ?
52
-
python setup.py test
53
48
54
49
Public API
55
50
==========
56
51
57
52
Exception
58
53
---------
59
54
60
-
``stopit.TimeoutException``
55
+
``timed_threads.TimeoutException``
61
56
...........................
62
57
63
-
A ``stopit.TimeoutException`` may be raised in a timeout context manager
58
+
A ``timed_threads.TimeoutException`` may be raised in a timeout context manager
64
59
controlled block.
65
60
66
61
This exception may be propagated in your application at the end of execution
67
62
of the context manager controlled block, see the ``swallow_ex`` parameter of
68
63
the context managers.
69
64
70
-
Note that the ``stopit.TimeoutException`` is always swallowed after the
65
+
Note that the ``timed_threads.TimeoutException`` is always swallowed after the
71
66
execution of functions decorated with ``xxx_timeoutable(...)``. Anyway, you
72
67
may catch this exception **within** the decorated function.
73
68
@@ -85,7 +80,7 @@ Threading based resources
85
80
executing a ``time.sleep(20)``, the asynchronous exception is effective
86
81
**after** its execution.
87
82
88
-
``stopit.async_raise``
83
+
``timed_threads.async_raise``
89
84
......................
90
85
91
86
A function that raises an arbitrary exception in another thread
@@ -98,7 +93,7 @@ A function that raises an arbitrary exception in another thread
98
93
99
94
- ``exception`` is the exception class or object to raise in the thread.
100
95
101
-
``stopit.ThreadingTimeout``
96
+
``timed_threads.ThreadingTimeout``
102
97
...........................
103
98
104
99
A context manager that "kills" its inner block execution that exceeds the
@@ -109,13 +104,13 @@ provided time.
109
104
- ``seconds`` is the number of seconds allowed to the execution of the context
110
105
managed block.
111
106
112
-
- ``swallow_exc`` : if ``False``, the possible ``stopit.TimeoutException`` will
107
+
- ``swallow_exc`` : if ``False``, the possible ``timed_threads.TimeoutException`` will
113
108
be re-raised when quitting the context managed block. **Attention**: a
114
109
``True`` value does not swallow other potential exceptions.
115
110
116
111
**Methods and attributes**
117
112
118
-
of a ``stopit.ThreadingTimeout`` context manager.
113
+
of a ``timed_threads.ThreadingTimeout`` context manager.
119
114
120
115
.. list-table::
121
116
:header-rows: 1
@@ -150,7 +145,7 @@ of a ``stopit.ThreadingTimeout`` context manager.
150
145
151
146
* - ``.INTERRUPTED``
152
147
- The code under timeout control may itself raise explicit
153
-
``stopit.TimeoutException`` for any application logic reason that may
148
+
``timed_threads.TimeoutException`` for any application logic reason that may
154
149
occur. This intentional exit can be spotted from outside the timeout
155
150
controlled block with this state value.
156
151
@@ -164,9 +159,9 @@ A typical usage:
164
159
165
160
.. code:: python
166
161
167
-
importstopit
162
+
importtimed_threads
168
163
# ...
169
-
withstopit.ThreadingTimeout(10) as to_ctx_mgr:
164
+
withtimed_threads.ThreadingTimeout(10) as to_ctx_mgr:
170
165
assert to_ctx_mgr.state == to_ctx_mgr.EXECUTING
171
166
# Something potentially very long but which
172
167
# ...
@@ -195,13 +190,13 @@ indicating (if ``True``) that the block executed normally:
195
190
# Yes, the code under timeout control completed
196
191
# Objects it created or changed may be considered consistent
197
192
198
-
``stopit.threading_timeoutable``
193
+
``timed_threads.threading_timeoutable``
199
194
................................
200
195
201
196
A decorator that kills the function or method it decorates, if it does not
0 commit comments