[ python-Bugs-904498 ] threading docs, start error should be specified

[SourceForge.net]

Bugs item #904498, was opened at 2004-02-25 12:00
Message generated for change (Comment added) made by reowen
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=904498&group_id=5470

Category: Documentation
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Russell Owen (reowen)
Assigned to: Nobody/Anonymous (nobody)
Summary: threading docs, start error should be specified

Initial Comment:
The docs say it is an error to start a threading thread more than once, but they do not specify exactly what exception will be raised.

Apparently it is always AssertionError (though an expert should verify this).

It would be very helpful to document the exception because there is no other documented way to tell if a threading thread has been started than to try to start it.

I posted to the dev group on 2003-02-24 about this and Aahz asked me to file a doc bug. So here it is.

I suggest the info go in the Thread object docs, in the documentation for "start".

----------------------------------------------------------------------

>Comment By: Russell Owen (reowen)
Date: 2005-01-24 11:47

Message:
Logged In: YES 
user_id=431773

There is still the problem that the threading module presents no reasonable 
way to tell if a thread is safe to start (i.e. whether or not it has already been 
started).

A standard documented exception is one way to handle this (AssertionError 
is clearly not the best choice). A method or attribute would be even better, 
but would require a change in interface.

Right now one has to keep a separate state flag, which is risky.

----------------------------------------------------------------------

Comment By: Alan Green (alanvgreen)
Date: 2005-01-22 02:30

Message:
Logged In: YES 
user_id=1174944

The actual wording in the documentation is: "This must be
called at most once per thread object." To me this implies
that the effect of calling start() twice is not defined. 

There is an assert statement in the implementation of
Thread.start(), but - like all assert statements - its
behaviour is dependent upon the value of the builtin
__debug__ variable.

Looking through the rest of the threading module, the
documentation could be tightened up, particularly with
respect to which behaviours are and aren't defined.


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=904498&group_id=5470