From 0e43f0b1611bc71de68874a61dd6fb86b3ad59a2 Mon Sep 17 00:00:00 2001 From: Tim Savannah Date: Sun, 4 Jun 2017 04:44:20 -0400 Subject: [PATCH] pydoc --- doc/func_timeout.StoppableThread.html | 64 +++++++++++++++------------ 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/doc/func_timeout.StoppableThread.html b/doc/func_timeout.StoppableThread.html index 74167b9..bae94a8 100644 --- a/doc/func_timeout.StoppableThread.html +++ b/doc/func_timeout.StoppableThread.html @@ -19,10 +19,8 @@ LICENSE, otherwise it is available at https://gith        
ctypes
-os
-		sys
-threading
-		time
+		os
+		threading

@@ -46,7 +44,12 @@ LICENSE, otherwise it is available at https://gith class JoinThread(threading.Thread) - + - +
   JoinThread - The workhouse that stops the StoppableThread
 
JoinThread - The workhouse that stops the StoppableThread.
+ 
+    Takes an exception, and upon being started immediately raises that exception in the current context
+      of the thread's execution (so next line of python gets it, or next call to a python api function in C code ).
+ 
+    @see StoppableThread for more details
 
 
Method resolution order:
JoinThread
@@ -55,32 +58,18 @@ LICENSE, otherwise it is available at https://gith
Methods defined here:
-
__init__(self, otherThread, exception, repeatEvery=2.0)
This constructor should always be called with keyword arguments. Arguments are:
+
__init__(self, otherThread, exception, repeatEvery=2.0)
__init__ - Create a JoinThread (don't forget to call .start() ! )
 
-*group* should be None; reserved for future extension when a ThreadGroup
-class is implemented.
+    @param otherThread <threading.Thread> - A thread
 
-*target* is the callable object to be invoked by the run()
-method. Defaults to None, meaning nothing is called.
+    @param exception <BaseException> - An exception. Should be a BaseException, to prevent "catch Exception as e: continue" type code
+      from never being terminated. If such code is unavoidable, you can try setting #repeatEvery to a very low number, like .00001,
+      and it will hopefully raise within the context of the catch, and be able to break free.
 
-*name* is the thread name. By default, a unique name is constructed of
-the form "Thread-N" where N is a small decimal number.
- 
-*args* is the argument tuple for the target invocation. Defaults to ().
- 
-*kwargs* is a dictionary of keyword arguments for the target
-invocation. Defaults to {}.
- 
-If a subclass overrides the constructor, it must make sure to invoke
-the base class constructor (Thread.__init__()) before doing anything
-else to the thread.
+    @param repeatEvery <float> Default 2.0 - After starting, the given exception is immediately raised. Then, every #repeatEvery seconds,
+      it is raised again, until the thread terminates.
-
run(self)
Method representing the thread's activity.
- 
-You may override this method in a subclass. The standard run() method
-invokes the callable object passed to the object's constructor as the
-target argument, if any, with sequential and keyword arguments taken
-from the args and kwargs arguments, respectively.
+
run(self)
run - The thread main. Will attempt to stop and join the attached thread.
Methods inherited from threading.Thread:
@@ -175,7 +164,24 @@ initial name is set by the constructor. class StoppableThread(threading.Thread)
   StoppableThread - A thread that can be stopped by forcing an exception in the execution context.
 
StoppableThread - A thread that can be stopped by forcing an exception in the execution context.
+ 
+  This works both to interrupt code that is in C or in python code, at either the next call to a python function,
+   or the next line in python code.
+ 
+It is recommended that if you call stop ( @see StoppableThread.stop ) that you use an exception that inherits BaseException, to ensure it likely isn't caught.
+ 
+ Also, beware unmarked exception handlers in your code. Code like this:
+ 
+    while True:
+        try:
+            doSomething()
+        except:
+            continue
+ 
+will never be able to abort, because the exception you raise is immediately caught.
+ 
+The exception is raised over and over, with a specifed delay (default 2.0 seconds)
 
 
Method resolution order:
StoppableThread
@@ -184,7 +190,7 @@ initial name is set by the constructor.
Methods defined here:
-
stop(self, exception)
Stops the thread by raising a given exception.
+
stop(self, exception, raiseEvery=2.0)
Stops the thread by raising a given exception.
 
@param exception <Exception> - Exception to throw. Likely, you want to use something
  that inherits from BaseException (so except Exception as e: continue; isn't a problem)