From 525b3d6ff083bc9d38d53ca0f574c8f828818795 Mon Sep 17 00:00:00 2001
From: Lee Rhodes
Memory allocation. A new t-Digest does not allocate storage for centroids or buffered values + * up front. The storage is allocated on first use and grows as values arrive, up to its full size. + * A t-Digest that stays small never allocates the full storage. An {@link OutOfMemoryError} while + * growing the storage therefore happens in {@link #update(double)} or {@link #merge(TDigestDouble)}, + * not in the constructor; if it happens, the t-Digest is unchanged. Call {@link #ensureCapacity()} right + * after construction to allocate the full storage up front instead. Results and the serialized form + * are the same either way.
*/ public final class TDigestDouble { @@ -59,13 +67,17 @@ public final class TDigestDouble { private double maxValue_; private final int centroidsCapacity_; private int numCentroids_; - private final double[] centroidMeans_; - private final long[] centroidWeights_; + // the storage arrays grow as they fill, up to their full size; see ensureCapacity() + private double[] centroidMeans_; + private long[] centroidWeights_; private long centroidsWeight_; private int numBuffered_; - private final double[] bufferValues_; + private double[] bufferValues_; private static final int BUFFER_MULTIPLIER = 4; + private static final int MIN_BUFFER_GROWTH = 8; + private static final double[] NO_VALUES = new double[0]; + private static final long[] NO_WEIGHTS = new long[0]; private static final byte PREAMBLE_LONGS_EMPTY_OR_SINGLE = 1; private static final byte PREAMBLE_LONGS_MULTIPLE = 2; @@ -77,14 +89,16 @@ public final class TDigestDouble { private enum Flags { IS_EMPTY, IS_SINGLE_VALUE, REVERSE_MERGE } /** - * Constructor with the default K + * Constructor with the default K. + * Storage is allocated on first use; see {@link #ensureCapacity()}. */ public TDigestDouble() { this(DEFAULT_K); } /** - * Constructor + * Constructor. + * Storage is allocated on first use; see {@link #ensureCapacity()}. * @param k affects the size of TDigest and its estimation error */ public TDigestDouble(final short k) { @@ -108,7 +122,8 @@ public short getK() { public void update(final double value) { if (!Double.isFinite(value)) { return; } Math.addExact(getTotalWeight(), 1); - if (numBuffered_ >= (centroidsCapacity_ * BUFFER_MULTIPLIER)) { compress(); } + if (numBuffered_ >= getFullBufferSize()) { compress(); } + else if (numBuffered_ == bufferValues_.length) { growBuffer(); } //allocates before anything changes bufferValues_[numBuffered_] = value; numBuffered_++; minValue_ = Math.min(minValue_, value); @@ -123,12 +138,14 @@ public void update(final double value) { public void merge(final TDigestDouble other) { if (other.isEmpty()) { return; } Math.addExact(getTotalWeight(), other.getTotalWeight()); - // Extreme centroid means are not the true min/max when those centroids have weight > 1. - minValue_ = Math.min(minValue_, other.minValue_); - maxValue_ = Math.max(maxValue_, other.maxValue_); + // allocate everything before changing anything, so that an OutOfMemoryError leaves this t-Digest unchanged final int num = numCentroids_ + numBuffered_ + other.numCentroids_ + other.numBuffered_; + ensureCentroidCapacity(num); final double[] values = new double[num]; final long[] weights = new long[num]; + // Extreme centroid means are not the true min/max when those centroids have weight > 1. + minValue_ = Math.min(minValue_, other.minValue_); + maxValue_ = Math.max(maxValue_, other.maxValue_); System.arraycopy(bufferValues_, 0, values, 0, numBuffered_); Arrays.fill(weights, 0, numBuffered_, 1); System.arraycopy(other.bufferValues_, 0, values, numBuffered_, other.numBuffered_); @@ -144,6 +161,7 @@ public void merge(final TDigestDouble other) { private void compress() { if (numBuffered_ == 0) { return; } final int num = numBuffered_ + numCentroids_; + ensureCentroidCapacity(num); final double[] values = new double[num]; final long[] weights = new long[num]; System.arraycopy(bufferValues_, 0, values, 0, numBuffered_); @@ -613,8 +631,10 @@ public String toString(final boolean printCentroids) { .append(" Compression: ").append(k_).append(LS) .append(" Centroids: ").append(numCentroids_).append(LS) .append(" Buffered: ").append(numBuffered_).append(LS) - .append(" Centroids Capacity: ").append(centroidMeans_.length).append(LS) - .append(" Buffer Capacity: ").append(bufferValues_.length).append(LS) + .append(" Centroids Capacity: ").append(centroidsCapacity_) + .append(" (allocated ").append(centroidMeans_.length).append(")").append(LS) + .append(" Buffer Capacity: ").append(getFullBufferSize()) + .append(" (allocated ").append(bufferValues_.length).append(")").append(LS) .append("Centroids Weight: ").append(centroidsWeight_).append(LS) .append(" Total Weight: ").append(getTotalWeight()).append(LS) .append(" Reverse Merge: ").append(reverseMerge_).append(LS); @@ -649,25 +669,71 @@ private TDigestDouble(final boolean reverseMerge, final short k, final double mi final int fudge = k < 30 ? 30 : 10; centroidsCapacity_ = (k * 2) + fudge; // Compression thresholds are local sizing choices, not serialization limits. - final int centroidSlots = Math.max(centroidsCapacity_, means == null ? 0 : means.length); - final int bufferSlots = Math.max(centroidsCapacity_ * BUFFER_MULTIPLIER, buffer == null ? 0 : buffer.length); - centroidMeans_ = new double[centroidSlots]; - centroidWeights_ = new long[centroidSlots]; - bufferValues_ = new double[bufferSlots]; - numCentroids_ = 0; - numBuffered_ = 0; + // Storage is sized to the given data and grows as needed; a new t-Digest allocates none. centroidsWeight_ = weight; if ((means != null) && (weights != null)) { - System.arraycopy(means, 0, centroidMeans_, 0, means.length); - System.arraycopy(weights, 0, centroidWeights_, 0, weights.length); + centroidMeans_ = Arrays.copyOf(means, means.length); + centroidWeights_ = Arrays.copyOf(weights, weights.length); numCentroids_ = means.length; + } else { + centroidMeans_ = NO_VALUES; + centroidWeights_ = NO_WEIGHTS; + numCentroids_ = 0; } if (buffer != null) { - System.arraycopy(buffer, 0, bufferValues_, 0, buffer.length); + bufferValues_ = Arrays.copyOf(buffer, buffer.length); numBuffered_ = buffer.length; + } else { + bufferValues_ = NO_VALUES; + numBuffered_ = 0; } } + /** + * Allocates the full storage for centroids and buffered values now, rather than as values arrive. + * Call this right after construction to move an {@link OutOfMemoryError} from {@link #update(double)} + * or {@link #merge(TDigestDouble)} to this call, or so that updates do not pay for growing the storage. + * It has no effect on storage that is already at its full size, and it does not change the contents. + */ + public void ensureCapacity() { + final int fullBuffer = getFullBufferSize(); + final double[] buffer = (bufferValues_.length < fullBuffer) ? Arrays.copyOf(bufferValues_, fullBuffer) : null; + ensureCentroidCapacity(centroidsCapacity_); + if (buffer != null) { bufferValues_ = buffer; } + } + + /** Returns the full size of the buffer, at which buffered values are compressed into centroids. */ + private int getFullBufferSize() { + return centroidsCapacity_ * BUFFER_MULTIPLIER; + } + + /** Grows the buffer geometrically, up to its full size. */ + private void growBuffer() { + final int newLength = Math.min(Math.max(2 * bufferValues_.length, MIN_BUFFER_GROWTH), getFullBufferSize()); + bufferValues_ = Arrays.copyOf(bufferValues_, newLength); + } + + /** + * Grows the centroid storage, if needed, so that it holds the given number of centroids, up to its full size. + * Both arrays are allocated before either is replaced. + */ + private void ensureCentroidCapacity(final int num) { + final int target = Math.min(num, centroidsCapacity_); + final int length = centroidMeans_.length; + if (length >= target) { return; } + final int newLength = Math.max(target, Math.min(2 * length, centroidsCapacity_)); + final double[] means = Arrays.copyOf(centroidMeans_, newLength); + final long[] weights = Arrays.copyOf(centroidWeights_, newLength); + centroidMeans_ = means; + centroidWeights_ = weights; + } + + /** Returns the number of centroids the allocated storage holds. For tests. */ + int getAllocatedCentroids() { return centroidMeans_.length; } + + /** Returns the number of values the allocated buffer holds. For tests. */ + int getAllocatedBuffer() { return bufferValues_.length; } + private static void checkK(final short k) { if (k < 10) { throw new SketchesArgumentException("k must be at least 10"); } } diff --git a/src/test/java/org/apache/datasketches/tdigest/TDigestLazyAllocationTest.java b/src/test/java/org/apache/datasketches/tdigest/TDigestLazyAllocationTest.java new file mode 100644 index 000000000..121434576 --- /dev/null +++ b/src/test/java/org/apache/datasketches/tdigest/TDigestLazyAllocationTest.java @@ -0,0 +1,153 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + + +package org.apache.datasketches.tdigest; + +import static org.testng.Assert.assertEquals; +import static org.testng.Assert.assertTrue; + +import java.lang.foreign.MemorySegment; + +import org.testng.annotations.Test; + +/** + * Checks that a t-Digest allocates its storage on first use and grows it as values arrive, + * or allocates it up front with ensureCapacity(), with the same results either way. + */ +public class TDigestLazyAllocationTest { + private static final short K = 100; + private static final int FULL_CENTROIDS = (2 * K) + 10; + private static final int FULL_BUFFER = 4 * FULL_CENTROIDS; + + private static double value(final int i) { return (i * 7919) % 100_003; } //not sorted, deterministic + + private static void assertAllocated(final TDigestDouble td, final int centroids, final int buffer) { + assertEquals(td.getAllocatedCentroids(), centroids, "centroids"); + assertEquals(td.getAllocatedBuffer(), buffer, "buffer"); + } + + @Test + public void emptyDigestHoldsNoStorage() { + final TDigestDouble td = new TDigestDouble(K); + assertAllocated(td, 0, 0); + td.update(Double.NaN); //ignored, so not a first use + td.update(Double.POSITIVE_INFINITY); + td.merge(new TDigestDouble(K)); //merging an empty t-Digest is not a first use + assertTrue(td.isEmpty()); + td.toString(true); + final TDigestDouble reserved = new TDigestDouble(K); + reserved.ensureCapacity(); + assertEquals(td.toByteArray(), reserved.toByteArray()); + assertAllocated(td, 0, 0); + final TDigestDouble copy = TDigestDouble.heapify(MemorySegment.ofArray(td.toByteArray())); + assertAllocated(copy, 0, 0); + } + + @Test + public void bufferGrowsGeometrically() { + final TDigestDouble td = new TDigestDouble(K); + td.update(1); + assertAllocated(td, 0, 8); + for (int i = 2; i <= 9; i++) { td.update(i); } + assertAllocated(td, 0, 16); + for (int i = 10; i <= FULL_BUFFER; i++) { td.update(i); } + assertEquals(td.getAllocatedBuffer(), FULL_BUFFER); //capped at the full size + assertEquals(td.getAllocatedCentroids(), 0); //nothing compressed yet + td.update(0); //the buffer is full, so this compresses + assertEquals(td.getAllocatedBuffer(), FULL_BUFFER); + assertTrue(td.getAllocatedCentroids() > 0); + assertTrue(td.getAllocatedCentroids() <= FULL_CENTROIDS); + } + + @Test + public void smallDigestNeverAllocatesFullStorage() { + final TDigestDouble td = new TDigestDouble(K); + for (int i = 0; i < 100; i++) { td.update(value(i)); } + assertEquals(td.getAllocatedBuffer(), 128); + td.getRank(50_000); //compresses + assertTrue(td.getAllocatedCentroids() <= 100, "centroids " + td.getAllocatedCentroids()); + assertTrue(td.getAllocatedCentroids() < FULL_CENTROIDS); + } + + @Test + public void ensureCapacityAllocatesFullStorage() { + final TDigestDouble td = new TDigestDouble(K); + td.ensureCapacity(); + assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER); + td.ensureCapacity(); //no effect once allocated + assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER); + final TDigestDouble lazy = new TDigestDouble(K); + for (int i = 0; i < 100_000; i++) { td.update(value(i)); lazy.update(value(i)); } + assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER); //the storage never grew + assertEquals(td.toByteArray(), lazy.toByteArray()); + assertEquals(td.getQuantile(0.5), lazy.getQuantile(0.5)); + } + + @Test + public void ensureCapacityAfterUpdatesKeepsContents() { + final TDigestDouble td = new TDigestDouble(K); + final TDigestDouble ref = new TDigestDouble(K); + for (int i = 0; i < 1000; i++) { td.update(value(i)); ref.update(value(i)); } + final String before = td.toString(true).replaceAll("\\(allocated \\d+\\)", ""); + td.ensureCapacity(); + assertEquals(td.toString(true).replaceAll("\\(allocated \\d+\\)", ""), before); //buffered values included + assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER); + for (int i = 1000; i < 50_000; i++) { td.update(value(i)); ref.update(value(i)); } + assertEquals(td.toByteArray(), ref.toByteArray()); + } + + @Test + public void mergeIntoNewDigest() { + final TDigestDouble other = new TDigestDouble(K); + for (int i = 0; i < 10_000; i++) { other.update(value(i)); } + final TDigestDouble lazy = new TDigestDouble(K); + final TDigestDouble reserved = new TDigestDouble(K); + reserved.ensureCapacity(); + lazy.merge(other); + reserved.merge(other); + assertTrue(lazy.getAllocatedCentroids() > 0); + assertEquals(lazy.getAllocatedBuffer(), 0); //a merge does not need the buffer + assertEquals(lazy.toByteArray(), reserved.toByteArray()); + assertEquals(lazy.getMinValue(), other.getMinValue()); + assertEquals(lazy.getMaxValue(), other.getMaxValue()); + + final TDigestDouble single = new TDigestDouble(K); + single.update(42); + final TDigestDouble fromSingle = new TDigestDouble(K); + fromSingle.merge(single); + assertEquals(fromSingle.toByteArray(), single.toByteArray()); + } + + @Test + public void heapifiedDigestIsSizedToItsImage() { + final TDigestDouble src = new TDigestDouble(K); + for (int i = 0; i < 10_000; i++) { src.update(value(i)); } + final byte[] image = src.toByteArray(); + final TDigestDouble td = TDigestDouble.heapify(MemorySegment.ofArray(image)); + final TDigestDouble reserved = TDigestDouble.heapify(MemorySegment.ofArray(image)); + reserved.ensureCapacity(); + assertEquals(td.getAllocatedBuffer(), 0); + assertTrue(td.getAllocatedCentroids() < FULL_CENTROIDS); + for (int i = 0; i < 20_000; i++) { td.update(value(i) + 0.5); reserved.update(value(i) + 0.5); } + td.merge(src); + reserved.merge(src); + assertEquals(td.toByteArray(), reserved.toByteArray()); + } +}