diff --git a/src/site/xdoc/userguide.xml b/src/site/xdoc/userguide.xml index f372bcdea..517c022ec 100644 --- a/src/site/xdoc/userguide.xml +++ b/src/site/xdoc/userguide.xml @@ -345,10 +345,37 @@ public class ServerThread implements Runnable { possible that the initialize() method is invoked multiple times. The class guarantees that get() always returns the same object though; so objects created accidently are immideately discarded. - As a rule of thumb, AtomicInitializer is preferrable if the - probability of a simultaneous access to the initializer is low, e.g. if - there are not too many concurrent threads. LazyInitializer is - the safer variant, but it has some overhead due to synchronization. +

+

+ With AtomicSafeInitializer there is yet another variant + implementing the lazy initializing pattern. Its implementation is close to + AtomicInitializer; it also uses atomic variables internally + and therefore does not need synchronization. The name "Safe" is + derived from the fact that it implements an additional check which guarantees + that the initialize() method is called only once. So it + behaves exactly in the same way as LazyInitializer. +

+

+ Now, which one of the lazy initializer implementations should you use? + First of all we have to state that is is problematic to give general + recommendations regarding the performance of these classes. The initializers + make use of low-level functionality whose efficiency depends on multiple + factors including the target platform and the number of concurrent threads. + So developers should make their own benchmarks in scenarios close to their + specific use cases. The following statements are rules of thumb which have + to be verified in practice. +

+

+ AtomicInitializer is probably the most efficient implementation + due to its lack of synchronization and further checks. Its main drawback is + that the initialize() method can be called multiple + times. In cases where this is not an issue AtomicInitializer is + a good choice. AtomicSafeInitializer and + LazyInitializer both guarantee that the initialization method + is called only once. Because AtomicSafeInitializer does not + use synchronization it is probably slightly more efficient than + LazyInitializer, but the concrete numbers might depend on the + level of concurrency.

Another implementation of the ConcurrentInitializer interface