<commit_before>
/*
 * Copyright (C) 2015 <NAME>. All rights reserved.
 */

package org.jsimpledb.util;

import com.google.common.base.Preconditions;

import java.io.Closeable;
import java.lang.ref.ReferenceQueue;
import java.lang.ref.WeakReference;
import java.util.ArrayList;
import java.util.HashSet;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * Keeps track of {@link Closeable} objects (termed <i>items</i>) that must be reliably {@linkplain Closeable#close closed}
 * prior to shutting down some associated context, but that also must not be closed prior to becoming unreachable, when
 * the straightforward strategy of just storing them until context shutdown would require too much memory. In a
 * typical scenario, these items are returned (indirectly by reference from some associated <i>holder</i> object) from some
 * method to callers who cannot be expected to reliably close them. Following the simple strategy of just storing all unclosed
 * items until context shutdown means unbounded memory use can occur; this class solves that problem.
 *
 * <p>
 * For each such context, an instance of this class may be used to register and track the associated items,
 * guaranteeing that they will always eventually be closed, but doing so in a way that avoids memory leaks:
 * For each item, there must be a corresponding <i>holder</i> object containing a reference to it. The holder objects are
 * then tracked by this class using weak references. When a holder object is no longer strongly referenced, the corresponding
 * item is closed. With this scheme, no memory leak occurs due to this tracking, even when arbitrarily many items are created.
 * This of course assumes that when a holder object is no longer referenced, the associated item may be safely closed.
 *
 * <p>
 * A registered {@link Closeable} item is closed at the first occurrence of any of the following:
 * <ul>
 *  <li>
 *  <li>The application itself invokes {@link Closeable#close Closeable.close()} on the item</li>
 *  <li>The associated holder object is no longer strongly referenced, and then {@link #poll} is invoked</li>
 *  <li>{@link CloseableTracker#close} is invoked</li>
 *  <li>{@link CloseableTracker#finalize} is invoked (i.e., this instance is garbage collected)</li>
 * </ul>
 *
 * <p>
 * Note that {@link Closeable#close Closeable.close()} is required to be idempotent, so application usage
 * that results in eager closing of items is appropriate and encouraged. Use of this class may occasionally
 * result in {@link Closeable#close Closeable.close()} being invoked more than once for registered items.
 *
 * <p>
 * Instances of this class are thread safe.
 */
public class CloseableTracker implements Closeable {

    protected final Logger log = LoggerFactory.getLogger(this.getClass());

    private HashSet<HolderRef> unclosedItems;
    private ReferenceQueue<Object> queue;

// Constructors

    /**
     * Constructor.
     */
    public CloseableTracker() {<commit_msg>Javadoc fix.<commit_after>
/*
 * Copyright (C) 2015 <NAME>. All rights reserved.
 */

package org.jsimpledb.util;

import com.google.common.base.Preconditions;

import java.io.Closeable;
import java.lang.ref.ReferenceQueue;
import java.lang.ref.WeakReference;
import java.util.ArrayList;
import java.util.HashSet;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * Keeps track of {@link Closeable} objects (termed <i>items</i>) that must be reliably {@linkplain Closeable#close closed}
 * prior to shutting down some associated context, but that also must not be closed prior to becoming unreachable, when
 * the straightforward strategy of just storing them until context shutdown would require too much memory. In a
 * typical scenario, these items are returned (indirectly by reference from some associated <i>holder</i> object) from some
 * method to callers who cannot be expected to reliably close them. Following the simple strategy of just storing all unclosed
 * items until context shutdown means unbounded memory use can occur; this class solves that problem.
 *
 * <p>
 * For each such context, an instance of this class may be used to register and track the associated items,
 * guaranteeing that they will always eventually be closed, but doing so in a way that avoids memory leaks:
 * For each item, there must be a corresponding <i>holder</i> object containing a reference to it. The holder objects are
 * then tracked by this class using weak references. When a holder object is no longer strongly referenced, the corresponding
 * item is closed. With this scheme, no memory leak occurs due to this tracking, even when arbitrarily many items are created.
 * This of course assumes that when a holder object is no longer referenced, the associated item may be safely closed.
 *
 * <p>
 * A registered {@link Closeable} item is closed at the first occurrence of any of the following:
 * <ul>
 *  <li>The application itself invokes {@link Closeable#close Closeable.close()} on the item</li>
 *  <li>The associated holder object is no longer strongly referenced, and then {@link #poll} is invoked</li>
 *  <li>{@link CloseableTracker#close} is invoked</li>
 *  <li>{@link CloseableTracker#finalize} is invoked (i.e., this instance is garbage collected)</li>
 * </ul>
 *
 * <p>
 * Note that {@link Closeable#close Closeable.close()} is required to be idempotent, so application usage
 * that results in eager closing of items is appropriate and encouraged. Use of this class may occasionally
 * result in {@link Closeable#close Closeable.close()} being invoked more than once for registered items.
 *
 * <p>
 * Instances of this class are thread safe.
 */
public class CloseableTracker implements Closeable {

    protected final Logger log = LoggerFactory.getLogger(this.getClass());

    private HashSet<HolderRef> unclosedItems;
    private ReferenceQueue<Object> queue;

// Constructors

    /**
     * Constructor.
     */
    public CloseableTracker() {
{'fraction_non_alphanumeric': 0.07923771313941826, 'fraction_numerical': 0.0020060180541624875, 'mean_word_length': 4.375561545372866, 'pattern_counts': {'":': 0, '<': 50, '<?xml version=': 0, '>': 50, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2277520', 'n_tokens_mistral': 1567, 'n_tokens_neox': 1523, 'n_words': 754}