@woosh/meep-engine/src/core/cache/FrequencySketch.d.ts

Pure JavaScript game engine. Fully featured and production ready.

/**
 * A probabilistic multiset for estimating the popularity of an element within a time window. The
 * maximum frequency of an element is limited to 15 (4-bits) and an aging process periodically
 * halves the popularity of all elements.
 *
 *
 * This class maintains a 4-bit CountMinSketch [1] with periodic aging to provide the popularity
 * history for the TinyLfu admission policy [2]. The time and space efficiency of the sketch
 * allows it to cheaply estimate the frequency of an entry in a stream of cache access events.
 *
 * The counter matrix is represented as a single dimensional array holding 16 counters per slot. A
 * fixed depth of four balances the accuracy and cost, resulting in a width of four times the
 * length of the array. To retain an accurate estimation the array's length equals the maximum
 * number of entries in the cache, increased to the closest power-of-two to exploit more efficient
 * bit masking. This configuration results in a confidence of 93.75% and error bound of e / width.
 *
 * The frequency of all entries is aged periodically using a sampling window based on the maximum
 * number of entries in the cache. This is referred to as the reset operation by TinyLfu and keeps
 * the sketch fresh by dividing all counters by two and subtracting based on the number of odd
 * counters found. The O(n) cost of aging is amortized, ideal for hardware prefetching, and uses
 * inexpensive bit manipulations per array location.
 *
 * [1] An Improved Data Stream Summary: The Count-Min Sketch and its Applications
 * http://dimacs.rutgers.edu/~graham/pubs/papers/cm-full.pdf
 * [2] TinyLFU: A Highly Efficient Cache Admission Policy
 * https://dl.acm.org/citation.cfm?id=3149371
 *
 * NOTE: ported from "caffeine"
 * @see https://github.com/ben-manes/caffeine/blob/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/FrequencySketch.java
 *
 * @author ben.manes@gmail.com (Ben Manes)
 * @author Alex Goldring 2021/04/08
 * @template T
 */
export class FrequencySketch<T> {
    /**
     *
     * @type {number}
     */
    sampleSize: number;
    /**
     *
     * @type {number}
     */
    tableMask: number;
    /**
     *
     * @type {Uint32Array|null}
     */
    table: Uint32Array | null;
    /**
     *
     * @type {number}
     */
    size: number;
    /**
     * Initializes and increases the capacity of this <tt>FrequencySketch</tt> instance, if necessary,
     * to ensure that it can accurately estimate the popularity of elements given the maximum size of
     * the cache. This operation forgets all previous counts when resizing.
     *
     * @param {number} maximumSize the maximum size of the cache
     */
    ensureCapacity(maximumSize: number): void;
    /**
     * Returns if the sketch has not yet been initialized, requiring that {@link #ensureCapacity} is
     * called before it begins to track frequencies.
     *
     * @returns {boolean}
     */
    isNotInitialized(): boolean;
    /**
     * Returns the estimated number of occurrences of an element, up to the maximum (15).
     *
     * @param {number} input_hash the element to count occurrences of
     * @returns {number} the estimated number of occurrences of the element; possibly zero but never negative
     */
    frequency(input_hash: number): number;
    /**
     *
     * Increments the popularity of the element if it does not exceed the maximum (15). The popularity
     * of all elements will be periodically down sampled when the observed events exceeds a threshold.
     * This process provides a frequency aging to allow expired long term entries to fade away.
     *
     * @param {number} input_hash the element to add
     */
    increment(input_hash: number): void;
    /**
     * Increments the specified counter by 1 if it is not already at the maximum value (15).
     *
     * @param {number} i the table index (8 counters)
     * @param {number} j the counter to increment
     * @returns {boolean} if incremented
     */
    incrementAt(i: number, j: number): boolean;
    /**
     * Reduces every counter by half of its original value.
     */
    reset(): void;
    /**
     * Returns the table index for the counter at the specified depth.
     * @param {number} item the element's hash
     * @param {number} i the counter depth
     * @returns {number} the table index
     */
    indexOf(item: number, i: number): number;
    /**
     * Applies a supplemental hash function to a given hash code, which defends against poor quality
     * @param {number} v
     * @returns {number}
     */
    spread(v: number): number;
}
//# sourceMappingURL=FrequencySketch.d.ts.map