[logback-user] logback and thread safety?

[Boyer, Brent B]

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 (brian at quiotix.com), 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.