1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang3.concurrent;
18
19 import java.util.concurrent.atomic.AtomicReference;
20
21 import org.apache.commons.lang3.function.FailableConsumer;
22 import org.apache.commons.lang3.function.FailableSupplier;
23
24 /**
25 * A specialized {@link ConcurrentInitializer} implementation which is similar
26 * to {@link AtomicInitializer}, but ensures that the {@link #initialize()}
27 * method is called only once.
28 *
29 * <p>
30 * As {@link AtomicInitializer} this class is based on atomic variables, so it
31 * can create an object under concurrent access without synchronization.
32 * However, it implements an additional check to guarantee that the
33 * {@link #initialize()} method which actually creates the object cannot be
34 * called multiple times.
35 * </p>
36 * <p>
37 * Because of this additional check this implementation is slightly less
38 * efficient than {@link AtomicInitializer}, but if the object creation in the
39 * {@code initialize()} method is expensive or if multiple invocations of
40 * {@code initialize()} are problematic, it is the better alternative.
41 * </p>
42 * <p>
43 * From its semantics this class has the same properties as
44 * {@link LazyInitializer}. It is a "save" implementation of the lazy
45 * initializer pattern. Comparing both classes in terms of efficiency is
46 * difficult because which one is faster depends on multiple factors. Because
47 * {@link AtomicSafeInitializer} does not use synchronization at all it probably
48 * outruns {@link LazyInitializer}, at least under low or moderate concurrent
49 * access. Developers should run their own benchmarks on the expected target
50 * platform to decide which implementation is suitable for their specific use
51 * case.
52 * </p>
53 *
54 * @since 3.0
55 * @param <T> the type of the object managed by this initializer class
56 */
57 public class AtomicSafeInitializer<T> extends AbstractConcurrentInitializer<T, ConcurrentException> {
58
59 /**
60 * Builds a new instance.
61 *
62 * @param <T> the type of the object managed by the initializer.
63 * @param <I> the type of the initializer managed by this builder.
64 * @since 3.14.0
65 */
66 public static class Builder<I extends AtomicSafeInitializer<T>, T> extends AbstractBuilder<I, T, Builder<I, T>, ConcurrentException> {
67
68 /**
69 * Constructs a new instance.
70 */
71 public Builder() {
72 // empty
73 }
74
75 @SuppressWarnings("unchecked")
76 @Override
77 public I get() {
78 return (I) new AtomicSafeInitializer(getInitializer(), getCloser());
79 }
80
81 }
82
83 private static final Object NO_INIT = new Object();
84
85 /**
86 * Creates a new builder.
87 *
88 * @param <T> the type of object to build.
89 * @return a new builder.
90 * @since 3.14.0
91 */
92 public static <T> Builder<AtomicSafeInitializer<T>, T> builder() {
93 return new Builder<>();
94 }
95
96 /** A guard which ensures that initialize() is called only once. */
97 private final AtomicReference<AtomicSafeInitializer<T>> factory = new AtomicReference<>();
98
99 /** Holds the reference to the managed object. */
100 private final AtomicReference<T> reference = new AtomicReference<>(getNoInit());
101
102 /**
103 * Constructs a new instance.
104 */
105 public AtomicSafeInitializer() {
106 // empty
107 }
108
109 /**
110 * Constructs a new instance.
111 *
112 * @param initializer the initializer supplier called by {@link #initialize()}.
113 * @param closer the closer consumer called by {@link #close()}.
114 */
115 private AtomicSafeInitializer(final FailableSupplier<T, ConcurrentException> initializer, final FailableConsumer<T, ConcurrentException> closer) {
116 super(initializer, closer);
117 }
118
119 /**
120 * Gets (and initialize, if not initialized yet) the required object
121 *
122 * @return lazily initialized object
123 * @throws ConcurrentException if the initialization of the object causes an
124 * exception
125 */
126 @Override
127 public final T get() throws ConcurrentException {
128 T result;
129
130 while ((result = reference.get()) == getNoInit()) {
131 if (factory.compareAndSet(null, this)) {
132 reference.set(initialize());
133 }
134 }
135
136 return result;
137 }
138
139 /** Gets the internal no-init object cast for this instance. */
140 @SuppressWarnings("unchecked")
141 private T getNoInit() {
142 return (T) NO_INIT;
143 }
144
145 /**
146 * {@inheritDoc}
147 */
148 @Override
149 protected ConcurrentException getTypedException(final Exception e) {
150 return new ConcurrentException(e);
151 }
152
153 /**
154 * Tests whether this instance is initialized. Once initialized, always returns true.
155 *
156 * @return whether this instance is initialized. Once initialized, always returns true.
157 * @since 3.14.0
158 */
159 @Override
160 public boolean isInitialized() {
161 return reference.get() != NO_INIT;
162 }
163 }