|
Javadoc comments should describe how the responsibilities for ensuring correct multi-threaded behaviour are shared between a class and its caller. This is equivalent to stating the circumstances, if any, in which the caller must explicitly obtain some lock before performing certain operations. The central question to be answered by the documentation is :
"When do these objects require external synchronization?"
Here, "operations" on an object come in two flavours :
- single-call operations, where only a single method is called
- multiple-call operations, where more than one method is called, and they are treated as a single unit ; the classic example is iteration over a collection
Documentation of thread safety is simplest when the responsibility for ensuring correct multi-threaded behaviour rests entirely with one party, and is not shared between the class and its caller :
immutable - the caller never needs to obtain a lock explicitly before performing any operation, either single-call or multiple-call. Since immutable objects never change state after construction, ensuring data integrity during multi-threaded use is not an issue. Here, all responsibility for correct multi-threaded behaviour rests with the class itself.
thread-compatible - the caller always needs to obtain a lock explicitly before performing any operation, either single-call or multiple-call. An example would be a class whose internals do not perform any synchronization whatsoever, such as ArrayList. Here, all responsibility for correct multi-threaded behaviour rests with the caller.
thread-hostile - operations cannot be performed safely in a multi-threaded environment, even when a lock is always obtained explicitly. This is a rare pathological case.
Documentation of thread-safety is more challenging in the following cases, where responsibility for correct behaviour is shared between a class and its caller :
thread-safe - the caller never needs to obtain a lock explicitly for single-call operations, but does need to obtain a lock during multiple-call operations. An example is a mutable class whose implementation performs all necessary synchronization for each individual method, but is being used in a multiple-call operation. Here, the responsibility for correct multi-threaded behaviour is shared between the class and its caller.
conditionally thread-safe - same as thread-safe, with the added distinction that there is at least one method whose sole use is as part of a multiple-call operation. The caller must always obtain a lock explicitly before using such a method. Again, the responsibility for correct multi-threaded behaviour is shared between the class and its caller.
(Note that javadoc 1.4 includes the -tag option, whereby simple custom tags may be defined. One might define a @needs.External.Synch tag, for example, to document thread safety issues.)
In typical business applications, most classes will likely be either
immutable or thread-compatible.