12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.ref;
27
28 import jdk.internal.ref.CleanerImpl;
29
30 import java.util.Objects;
31 import java.util.concurrent.ThreadFactory;
32 import java.util.function.Function;
33
34 /**
35 * {@code Cleaner} manages a set of object references and corresponding cleaning actions.
36 * <p>
37 * Cleaning actions are {@link #register(Object object, Runnable action) registered}
38 * to run after the cleaner is notified that the object has become
39 * phantom reachable.
40 * The cleaner uses {@link PhantomReference} and {@link ReferenceQueue} to be
41 * notified when the <a href="package-summary.html#reachability">reachability</a>
42 * changes.
43 * <p>
44 * Each cleaner operates independently, managing the pending cleaning actions
45 * and handling threading and termination when the cleaner is no longer in use.
46 * Registering an object reference and corresponding cleaning action returns
47 * a {@link Cleanable Cleanable}. The most efficient use is to explicitly invoke
48 * the {@link Cleanable#clean clean} method when the object is closed or
49 * no longer needed.
50 * The cleaning action is a {@link Runnable} to be invoked at most once when
51 * the object has become phantom reachable unless it has already been explicitly cleaned.
52 * Note that the cleaning action must not refer to the object being registered.
217 public Cleanable register(Object obj, Runnable action) {
218 Objects.requireNonNull(obj, "obj");
219 Objects.requireNonNull(action, "action");
220 return new CleanerImpl.PhantomCleanableRef(obj, this, action);
221 }
222
223 /**
224 * {@code Cleanable} represents an object and a
225 * cleaning action registered in a {@code Cleaner}.
226 * @since 9
227 */
228 public interface Cleanable {
229 /**
230 * Unregisters the cleanable and invokes the cleaning action.
231 * The cleanable's cleaning action is invoked at most once
232 * regardless of the number of calls to {@code clean}.
233 */
234 void clean();
235 }
236
237 }
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.ref;
27
28 import jdk.internal.ref.CleanerImpl;
29
30 import java.util.Objects;
31 import java.util.concurrent.ThreadFactory;
32 import java.util.function.Consumer;
33 import java.util.function.Function;
34 import java.util.function.LongConsumer;
35 import java.util.function.LongSupplier;
36 import java.util.function.Supplier;
37
38 /**
39 * {@code Cleaner} manages a set of object references and corresponding cleaning actions.
40 * <p>
41 * Cleaning actions are {@link #register(Object object, Runnable action) registered}
42 * to run after the cleaner is notified that the object has become
43 * phantom reachable.
44 * The cleaner uses {@link PhantomReference} and {@link ReferenceQueue} to be
45 * notified when the <a href="package-summary.html#reachability">reachability</a>
46 * changes.
47 * <p>
48 * Each cleaner operates independently, managing the pending cleaning actions
49 * and handling threading and termination when the cleaner is no longer in use.
50 * Registering an object reference and corresponding cleaning action returns
51 * a {@link Cleanable Cleanable}. The most efficient use is to explicitly invoke
52 * the {@link Cleanable#clean clean} method when the object is closed or
53 * no longer needed.
54 * The cleaning action is a {@link Runnable} to be invoked at most once when
55 * the object has become phantom reachable unless it has already been explicitly cleaned.
56 * Note that the cleaning action must not refer to the object being registered.
221 public Cleanable register(Object obj, Runnable action) {
222 Objects.requireNonNull(obj, "obj");
223 Objects.requireNonNull(action, "action");
224 return new CleanerImpl.PhantomCleanableRef(obj, this, action);
225 }
226
227 /**
228 * {@code Cleanable} represents an object and a
229 * cleaning action registered in a {@code Cleaner}.
230 * @since 9
231 */
232 public interface Cleanable {
233 /**
234 * Unregisters the cleanable and invokes the cleaning action.
235 * The cleanable's cleaning action is invoked at most once
236 * regardless of the number of calls to {@code clean}.
237 */
238 void clean();
239 }
240
241 /**
242 * 1st registers an object then allocates a reference-valued resource by
243 * invoking resource allocator function and associates it with de-allocator
244 * function which will be called with the resource as cleaning action when
245 * the registered object becomes phantom reachable.<p>
246 * Using this method (when applicable) is preferable to using
247 * {@link #register(Object, Runnable)}, because it ensures correct
248 * order of actions - 1st register the object, then allocate the resource -
249 * which prevents resource leaks in rare circumstances when registration fails
250 * because of insufficient heap memory. The resource allocator function still
251 * bares all the responsibility for either returning normally with the
252 * allocated resource or throwing an unchecked exception in which case the
253 * resource should not be allocated or should already be de-allocated, because
254 * in such case, the de-allocator function is not called.
255 * Refer to the <a href="#compatible-cleaners">API Note</a> above for
256 * cautions about the behavior of cleaning actions.
257 *
258 * @param obj the object to monitor
259 * @param resourceAllocator the resource allocator function
260 * @param resourceDeallocator the resource de-allocator function, invoked as
261 * cleaning action with the allocated resource
262 * @param <T> the type of resource
263 * @return a {@link CleanableResource} instance holding the allocated resource
264 * with associated de-allocator function as cleaning action
265 * @since 10
266 */
267 public <T> CleanableResource<T> createResource(
268 Object obj,
269 Supplier<? extends T> resourceAllocator,
270 Consumer<? super T> resourceDeallocator)
271 {
272 Objects.requireNonNull(obj, "obj");
273 Objects.requireNonNull(resourceAllocator, "resourceConstructor");
274 Objects.requireNonNull(resourceDeallocator, "resourceDestructor");
275 return new CleanerImpl.PhantomCleanableResource<>(obj, this, resourceAllocator, resourceDeallocator);
276 }
277
278 /**
279 * {@code CleanableResource} represents an object holding some reference
280 * valued resource and a cleaning action for the resource registered in a
281 * {@code Cleaner}.
282 *
283 * @since 10
284 *
285 * @param <T> the type of allocated resource
286 */
287 public interface CleanableResource<T> extends Cleanable {
288 /**
289 * Obtains the allocated resource.
290 *
291 * @return the allocated resource
292 * @throws IllegalStateException if the resource has already been
293 * {@link #clean() cleaned}
294 */
295 T value();
296 }
297
298 /**
299 * 1st registers an object then allocates a {@code long}-valued resource by
300 * invoking resource allocator function and associates it with de-allocator
301 * function which will be called with the resource as cleaning action when
302 * the registered object becomes phantom reachable.<p>
303 * Using this method (when applicable) is preferable to using
304 * {@link #register(Object, Runnable)}, because it ensures correct
305 * order of actions - 1st register the object, then allocate the resource -
306 * which prevents resource leaks in rare circumstances when registration fails
307 * because of insufficient heap memory. The resource allocator function still
308 * bares all the responsibility for either returning normally with the
309 * allocated resource or throwing an unchecked exception in which case the
310 * resource should not be allocated or should already be de-allocated, because
311 * in such case, the de-allocator function is not called.
312 * Refer to the <a href="#compatible-cleaners">API Note</a> above for
313 * cautions about the behavior of cleaning actions.
314 *
315 * @param obj the object to monitor
316 * @param resourceAllocator the resource allocator function
317 * @param resourceDeallocator the resource de-allocator function, invoked as
318 * cleaning action with the allocated resource
319 * @return a {@link LongCleanableResource} instance holding the allocated resource
320 * with associated de-allocator function as cleaning action
321 * @since 10
322 */
323 public LongCleanableResource createLongResource(
324 Object obj,
325 LongSupplier resourceAllocator,
326 LongConsumer resourceDeallocator)
327 {
328 Objects.requireNonNull(obj, "obj");
329 Objects.requireNonNull(resourceAllocator, "resourceConstructor");
330 Objects.requireNonNull(resourceDeallocator, "resourceDestructor");
331 return new CleanerImpl.PhantomLongCleanableResource(obj, this, resourceAllocator, resourceDeallocator);
332 }
333
334 /**
335 * {@code LongCleanableResource} represents an object holding some {@code long}
336 * valued resource and a cleaning action for the resource registered in a
337 * {@code Cleaner}.
338 *
339 * @since 10
340 */
341 public interface LongCleanableResource extends Cleanable {
342 /**
343 * Obtains the allocated resource.
344 *
345 * @return the allocated resource
346 * @throws IllegalStateException if the resource has already been
347 * {@link #clean() cleaned}
348 */
349 long value();
350 }
351 }
|