DO NOT REPLY [Bug 15777] - Thread safety of classes not documented

[bu...@apache.org]

DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG 
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15777>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND 
INSERTED IN THE BUG DATABASE.

http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15777

Thread safety of classes not documented

dfs@apache.org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED



------- Additional Comments From dfs@apache.org  2003-01-03 17:20 -------
Classes that perform some special form of synchronization or use thread-local
variables or somehow automatically handle concurrency issues require special
documentation.  By default, classes are assumed to not perform any special
concurrency handling.  Therefore I do not consider this a bug.  Nonetheless,
information regarding how to properly use the package used to be contained
in both a FAQ and a user's guide.  These are on the TODO list, so I'm marking
this bug with a resolution of LATER.

As a side note, Perl5Compiler and Perl5Matcher are in fact thread-safe.  You
just have to use a separate instance for each thread if you do not want
to manually synchronize accesses.  If you want to share Perl5Pattern
instances between concurrently executing instances of Perl5Matcher, you must
compile the patterns with Perl5Compiler.READ_ONLY_MASK.  The classes would
not be thread-safe if separate instances shared global state even when 
separate instances are used in each thread.  Thread-safe is a word that is
too often used to mean "doesn't do what I want it to do" rather than "cannot
be used in a program with concurrently executing threads without producing 
inconsistent/unexpected results."

This commentary in no way invalidates the general problem causing the bug 
reporter to file this problem report.  The library would be a lot easier to
use with a good user's guide and FAQ.  Because these won't be prepared in
time for the next version and to forestall further requests (under the
assumption that if one person finds this to be a problem, others will),
I'm actually going to contradict what I said in the first paragraph and
insert a few sentences in the API docs for Perl5Matcher and Perl5Compiler
and mark this bug as FIXED.

One last side, note.  When documentation problems are found, you are
greatly encouraged to submit a patch to the oro-dev mailing list.  The
project would have made a lot more progress on documentation if more users
would submit a paragraph here and a paragraph there detailing things that
they think should be more clear.  Before you know it, we'd have a user's guide!
Further discussion should occur on the mailing list.

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>