Ralph,
Thanks for your feedback.
>I don't know that it is necessary to include a comment on thread safety when
>every class is intended to be thread safe. It would make more sense to mention
>thread safety when a class is not.
I prefer to see every class explicitly mention this. For example, I think that
it is a disgrace that Sun's JDK classes do not always document their thread
safety.
If a class is not MT safe, the javadoc can, in general, be very brief ("This
class is not multi thread safe"). If most logback classes are thread safe,
then classes which are not should briefly mention why, since as you note that
is unusual.
For classes that are MT safe, it is always good both to say they are and WHY
they are. (See the end of this email--the standard MT safety techniques can
have short javadocs too.) You need to state WHY so programmers coming after
you do not need to do a research project figuring out your strategy, and can
hold your code accountable and verify correctness. This is critically
important when you do something funky like use multiple locks, or exotic locks,
or something.
It is debatable whether you put the WHY discussion in the class javadocs versus
some other code comment. On the one hand, it is an implementation detail that
maybe the class's contract need not specify, which favors a code comment.
Nevertheless, I favor putting it in the class javadocs because
a) while an implementation detail, it may affects subclasses, so the public
really does need to see it
b) it is good to have the MT discussion all in one place; scatter it all over
the place, and it is easily missed
>Yes, Logback is thread-safe.
Great.
>However, some appenders still use AppenderBase which assumes the Appender is
>not thread safe and so locks every call to format and write out the event.
So, those appenders are still thread safe, but the locking is overly coarse,
which presumably affects performance (unnecessarily reduces concurrency)?
Brent
p.s. below are some notes of mine on what I try to practice in my own code
--------------------------------------------------
Canonical multithread javadoc method contracts
--------------------------------------------------
* This class is not multithread safe.
--subcase for gui code:
* Like typical Java GUI code, this class is not multithread
safe:
* it expects to only be called by {@link EventQueue}'s {@link
EventQueue#isDispatchThread dispatch thread}.
* This threading limitation is checked in every public method.
* This class is not itself multithread safe, but it can only be accessed thru
protected (e.g. synchronized) code paths.
* This class is multithread safe: it is stateless.
* This class is multithread safe: it is <a
href="http://www.ibm.com/developerworks/java/library/j-jtp02183.html";>immutable</a>.
* In particular, it is always <a
href="http://www.ibm.com/developerworks/java/library/j-jtp0618.html";>properly
constructed</a>,
* all of its fields are final,
* and none of their state can be changed after construction.
* See p. 53 of <a href="http://www.javaconcurrencyinpractice.com";>Java
Concurrency In Practice</a> for more discussion.
* This class is multithread safe: the types of its state are individually
multithread safe, and are used such that only their individual multithread
safety matters.
* This class is multithread safe: all methods are synchronized.
--subcase:
* This class is multithread safe: all public methods are
synchronized.
* Note: subclasses which use protected methods must ensure that
they are used in a multithread safe manner.
--may wish to add more details on the synchronization lock used, like:
* These are all instance methods, and each synchronizes on the
instance itself.
or
* These are all static methods, and each synchronizes on the
Class object.
--some custom contract, especially if
--use multiple locks
--the static state/methods differ in nature from the instance
state/methods
--quote:
"In his book, Effective Java Programming Language Guide (see
Resources), Josh Bloch offers a useful taxonomy for documenting the degrees of
thread safety of a class. Classes can be categorized into one of the following
groups, in order of decreasing thread safety: immutable, thread-safe,
conditionally thread-safe, thread-compatible, and thread-hostile."
Java theory and practice: I have to document THAT?
Brian Goetz ([email protected]), Principal Consultant, Quiotix Corp
01 Aug 2002
http://64.233.179.104/search?q=cache:_EL1hWLbX1oJ:www.ibm.com/developerworks/library/j-jtp0821.html+javadoc+reference+%22package.html%22&hl=en&gl=us&ct=clnk&cd=16
see also:
http://www.javapractices.com/topic/TopicAction.do;jsessionid=78540C591DB8AACB4A6C126CF6221EAF?Id=48
--do not forget to discuss thread interruption checking, if relevant; here is a
typical contract:
* This class checks for thread interruption only before major blocking
operations
* in order to achieve a reasonable balance between cancellation
responsiveness and program performance
* (see Doug Lea <cite>Concurrent Programming in Java Second
Edition</cite> p. 170).
This communication is for informational purposes only. It is not
intended as an offer or solicitation for the purchase or sale of
any financial instrument or as an official confirmation of any
transaction. All market prices, data and other information are not
warranted as to completeness or accuracy and are subject to change
without notice. Any comments or statements made herein do not
necessarily reflect those of JPMorgan Chase & Co., its subsidiaries
and affiliates.
This transmission may contain information that is privileged,
confidential, legally privileged, and/or exempt from disclosure
under applicable law. If you are not the intended recipient, you
are hereby notified that any disclosure, copying, distribution, or
use of the information contained herein (including any reliance
thereon) is STRICTLY PROHIBITED. Although this transmission and any
attachments are believed to be free of any virus or other defect
that might affect any computer system into which it is received and
opened, it is the responsibility of the recipient to ensure that it
is virus free and no responsibility is accepted by JPMorgan Chase &
Co., its subsidiaries and affiliates, as applicable, for any loss
or damage arising in any way from its use. If you received this
transmission in error, please immediately contact the sender and
destroy the material in its entirety, whether in electronic or hard
copy format. Thank you.
Please refer to http://www.jpmorgan.com/pages/disclosures for
disclosures relating to European legal entities.
_______________________________________________
Logback-user mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-user
