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