If this sketch is already in compact form this operation returns this. + * + * @return this sketch as an ordered CompactSketch on the Java heap. + */ + public abstract CompactSketch compact(); + + /** + * Convert this sketch to a CompactSketch in the chosen form. + * + *
If this sketch is already in compact form this operation returns this. + * + *
Otherwise, this compacting process converts the hash table form of an UpdateSketch to + * a simple list of the valid hash values from the hash table. Any hash values equal to or + * greater than theta will be discarded. The number of valid values remaining in the + * Compact Sketch depends on a number of factors, but may be larger or smaller than + * Nominal Entries (or k). It will never exceed 2k. If it is critical + * to always limit the size to no more than k, then rebuild() should be called + * on the UpdateSketch prior to this. + * + * @param dstOrdered + * See Destination Ordered + * + * @param dstMem + * See Destination Memory. + * + * @return this sketch as a CompactSketch in the chosen form + */ + public abstract CompactSketch compact(final boolean dstOrdered, final WritableMemory dstMem); + /** * Gets the number of hash values less than the given theta. * @param theta the given theta as a double between zero and one. diff --git a/src/main/java/com/yahoo/sketches/theta/UnionImpl.java b/src/main/java/com/yahoo/sketches/theta/UnionImpl.java index 13674bc53..939936745 100644 --- a/src/main/java/com/yahoo/sketches/theta/UnionImpl.java +++ b/src/main/java/com/yahoo/sketches/theta/UnionImpl.java @@ -37,6 +37,15 @@ * @author Kevin Lang */ final class UnionImpl extends Union { + /** + * Although the gadget object is initially an UpdateSketch, in the context of a Union it is used + * as a specialized buffer that happens to leverage much of the machinery of an UpdateSketch. + * However, in this context some of the key invariants of the sketch algorithm are intentionally + * violated as an optimization. As a result this object can not be considered as an UpdateSketch + * and should never be exported as an UpdateSketch. It's internal state is not necessarily + * finalized and may contain garbage. Also its internal concept of "nominal entries" or "k" can + * be meaningless. It is private for very good reasons. + */ private final UpdateSketch gadget_; private final short seedHash_; //eliminates having to compute the seedHash on every update. private long unionThetaLong_; //when on-heap, this is the only copy diff --git a/src/main/java/com/yahoo/sketches/theta/UpdateSketch.java b/src/main/java/com/yahoo/sketches/theta/UpdateSketch.java index e1b943ced..ef8a8f7c3 100644 --- a/src/main/java/com/yahoo/sketches/theta/UpdateSketch.java +++ b/src/main/java/com/yahoo/sketches/theta/UpdateSketch.java @@ -115,50 +115,11 @@ public static UpdateSketch heapify(final Memory srcMem, final long seed) { //Sketch interface @Override - public boolean isCompact() { - return false; + public CompactSketch compact() { + return compact(true, null); } @Override - public boolean isOrdered() { - return false; - } - - //UpdateSketch interface - - /** - * Returns a new builder - * - * @return a new builder - */ - public static final UpdateSketchBuilder builder() { - return new UpdateSketchBuilder(); - } - - /** - * Resets this sketch back to a virgin empty state. - */ - public abstract void reset(); - - /** - * Convert this UpdateSketch to a CompactSketch in the chosen form. - * - *
This compacting process converts the hash table form of an UpdateSketch to - * a simple list of the valid hash values from the hash table. Any hash values equal to or - * greater than theta will be discarded. The number of valid values remaining in the - * Compact Sketch depends on a number of factors, but may be larger or smaller than - * Nominal Entries (or k). It will never exceed 2k. If it is critical - * to always limit the size to no more than k, then rebuild() should be called - * on the UpdateSketch prior to this. - * - * @param dstOrdered - * See Destination Ordered - * - * @param dstMem - * See Destination Memory. - * - * @return this sketch as a CompactSketch in the chosen form - */ public CompactSketch compact(final boolean dstOrdered, final WritableMemory dstMem) { CompactSketch sketchOut = null; final int sw = (dstOrdered ? 2 : 0) | ((dstMem != null) ? 1 : 0); @@ -184,14 +145,32 @@ public CompactSketch compact(final boolean dstOrdered, final WritableMemory dstM return sketchOut; } + @Override + public boolean isCompact() { + return false; + } + + @Override + public boolean isOrdered() { + return false; + } + + //UpdateSketch interface + /** - * Converts this UpdateSketch to an ordered CompactSketch on the Java heap. - * @return this sketch as an ordered CompactSketch on the Java heap. + * Returns a new builder + * + * @return a new builder */ - public CompactSketch compact() { - return compact(true, null); + public static final UpdateSketchBuilder builder() { + return new UpdateSketchBuilder(); } + /** + * Resets this sketch back to a virgin empty state. + */ + public abstract void reset(); + /** * Rebuilds the hash table to remove dirty values or to reduce the size * to nominal entries. diff --git a/src/test/java/com/yahoo/sketches/theta/CompactSketchTest.java b/src/test/java/com/yahoo/sketches/theta/CompactSketchTest.java index 1ea5d0c89..f137d89a1 100644 --- a/src/test/java/com/yahoo/sketches/theta/CompactSketchTest.java +++ b/src/test/java/com/yahoo/sketches/theta/CompactSketchTest.java @@ -241,6 +241,8 @@ public void checkDirectCompactSingleItemSketch() { sk.update(1); csk = sk.compact(true, WritableMemory.allocate(16)); assertEquals(csk.getCurrentBytes(true), 16); + assertTrue(csk == csk.compact()); + assertTrue(csk == csk.compact(true, null)); } @Test