[Python-Dev] should a module's thread safety be documented?

[uche.ogbuji@fourthought.com]

> > A bit late for 2.1alpha1, but it just occurred to me that perhaps there
> > should be an annotation in the documentation that indicates whether or not a
> > module is thread-safe.  For example, many functions in fileinput rely on a
> > module global called _state.  It strikes me that this module is not likely
> > to be thread-safe, yet the documentation doesn't appear to mention this,
> > certainly not in an obvious fashion.
> > 
> > Anyone for adding \notthreadsafe{} and \threadsafe{} macros to the litany of
> > LaTex macros in Fred's arsenal?  This would make documenting these
> > properties both easy and consistent across modules.
> 
> It's hard to say whether a *whole module* is threadsafe.  E.g. in the
> fileinput example, there's the clear implication that if you use this
> in multiple threads, you should instantiate your own FileInput
> instances, and then you're totally thread-safe.  Clearly the semantics
> of the module-global functions are thread-unsafe though.

Perhaps what is needed rather is a prose annotation for thread-safety issues.

My TeX is rusty, but in Docbook, with the use of role attributes, one could 
have, taking your FileInput example

<sect1 role="thread-safety"><para>
  The module-global functions are not safe, but if you instantiate your own 
FileInput instances, they will be totally thread-safe.
</para></sect>

That way the MT issues could be styled differently on rendering, gathered into 
separate documentation, stripped by those who don't care, etc.  I imagine this 
is also possible in TeX.


-- 
Uche Ogbuji                               Principal Consultant
uche.ogbuji@fourthought.com               +1 303 583 9900 x 101
Fourthought, Inc.                         http://Fourthought.com 
4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA
Software-engineering, knowledge-management, XML, CORBA, Linux, Python