From 525b3d6ff083bc9d38d53ca0f574c8f828818795 Mon Sep 17 00:00:00 2001 From: Lee Rhodes Date: Thu, 12 Nov 2026 12:22:16 -0800 Subject: [PATCH] t-digest: allocate storage on first use and grow it; add ensureCapacity() A new TDigestDouble no longer allocates its centroid and buffer storage in the constructor. The buffer is allocated on the first update and grows geometrically (8, 16, ...) up to its full size; the centroid storage is allocated at the first compression or merge and grows as needed up to its full size. A heapified t-Digest is sized to its image. Compression happens at the same points as before, so results and the serialized form are unchanged. ensureCapacity() allocates the full storage up front. merge() now allocates everything before it widens min and max, so an OutOfMemoryError leaves the t-Digest unchanged. This follows the lazy allocation convention agreed on dev@. Co-Authored-By: Claude Opus 5.5 --- .../datasketches/tdigest/TDigestDouble.java | 108 ++++++++++--- .../tdigest/TDigestLazyAllocationTest.java | 153 ++++++++++++++++++ 2 files changed, 240 insertions(+), 21 deletions(-) create mode 100644 src/test/java/org/apache/datasketches/tdigest/TDigestLazyAllocationTest.java diff --git a/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java b/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java index 145c5a151..067bcda6e 100644 --- a/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java +++ b/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java @@ -47,6 +47,14 @@ * by weight ascending. This makes each merge independent of how the centroids are arranged * before sorting, so that the same sequence of updates and merges always produces the same * sketch. It does not make the sketch independent of the order of the input values.

+ * + *

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()); + } +}