Package org.apache.datasketches.theta

Class UpdateSketchBuilder

  • public class UpdateSketchBuilder
extends Object
    For building a new UpdateSketch.
    Author:
    Lee Rhodes

    • Constructor Detail

      • UpdateSketchBuilder

        public UpdateSketchBuilder()
        Constructor for building a new UpdateSketch. The default configuration is
        • Nominal Entries: 4096
        • Seed: 9001L
        • Input Sampling Probability: 1.0
        • Family: Family.QUICKSELECT
        • Resize Factor: The default for sketches on the Java heap is ResizeFactor.X8. For direct sketches, which are targeted for native memory off the Java heap, this value will be fixed at either ResizeFactor.X1 or ResizeFactor.X2.
        • MemoryRequestServer (Direct only): DefaultMemoryRequestServer.
        Parameters unique to the concurrent sketches only:
        • Number of local Nominal Entries: 4
        • Concurrent NumPoolThreads: 3
        • Concurrent PropagateOrderedCompact: true
        • Concurrent MaxConcurrencyError: 0

    • Method Detail

      • setNominalEntries

        public UpdateSketchBuilder setNominalEntries​(int nomEntries)
        Sets the Nominal Entries for this sketch. This value is also used for building a shared concurrent sketch. The minimum value is 16 (2^4) and the maximum value is 67,108,864 (2^26). Be aware that sketches as large as this maximum value may not have been thoroughly tested or characterized for performance.
        Parameters:
        nomEntries - Nominal Entries This will become the ceiling power of 2 if the given value is not.
        Returns:
        this UpdateSketchBuilder

      • setLogNominalEntries

        public UpdateSketchBuilder setLogNominalEntries​(int lgNomEntries)
        Alternative method of setting the Nominal Entries for this sketch from the log_base2 value. This value is also used for building a shared concurrent sketch. The minimum value is 4 and the maximum value is 26. Be aware that sketches as large as this maximum value may not have been thoroughly characterized for performance.
        Parameters:
        lgNomEntries - the Log Nominal Entries. Also for the concurrent shared sketch
        Returns:
        this UpdateSketchBuilder

      • getLgNominalEntries

        public int getLgNominalEntries()
        Returns Log-base 2 Nominal Entries
        Returns:
        Log-base 2 Nominal Entries

      • setLocalNominalEntries

        public UpdateSketchBuilder setLocalNominalEntries​(int nomEntries)
        Sets the Nominal Entries for the concurrent local sketch. The minimum value is 16 and the maximum value is 67,108,864, which is 2^26. Be aware that sketches as large as this maximum value have not been thoroughly tested or characterized for performance.
        Parameters:
        nomEntries - Nominal Entries This will become the ceiling power of 2 if it is not.
        Returns:
        this UpdateSketchBuilder

      • setLocalLogNominalEntries

        public UpdateSketchBuilder setLocalLogNominalEntries​(int lgNomEntries)
        Alternative method of setting the Nominal Entries for a local concurrent sketch from the log_base2 value. The minimum value is 4 and the maximum value is 26. Be aware that sketches as large as this maximum value have not been thoroughly tested or characterized for performance.
        Parameters:
        lgNomEntries - the Log Nominal Entries for a concurrent local sketch
        Returns:
        this UpdateSketchBuilder

      • getLocalLgNominalEntries

        public int getLocalLgNominalEntries()
        Returns Log-base 2 Nominal Entries for the concurrent local sketch
        Returns:
        Log-base 2 Nominal Entries for the concurrent local sketch

      • setSeed

        public UpdateSketchBuilder setSeed​(long seed)
        Sets the long seed value that is required by the hashing function.
        Parameters:
        seed - See seed
        Returns:
        this UpdateSketchBuilder

      • getSeed

        public long getSeed()
        Returns the seed
        Returns:
        the seed

      • getP

        public float getP()
        Returns the pre-sampling probability p
        Returns:
        the pre-sampling probability p

      • getResizeFactor

        public ResizeFactor getResizeFactor()
        Returns the Resize Factor
        Returns:
        the Resize Factor

      • setFamily

        public UpdateSketchBuilder setFamily​(Family family)
        Set the Family.
        Parameters:
        family - the family for this builder
        Returns:
        this UpdateSketchBuilder

      • getFamily

        public Family getFamily()
        Returns the Family
        Returns:
        the Family

      • setMemoryRequestServer

        public UpdateSketchBuilder setMemoryRequestServer​(org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
        Set the MemoryRequestServer
        Parameters:
        memReqSvr - the given MemoryRequestServer
        Returns:
        this UpdateSketchBuilder

      • getMemoryRequestServer

        public org.apache.datasketches.memory.MemoryRequestServer getMemoryRequestServer()
        Returns the MemoryRequestServer
        Returns:
        the MemoryRequestServer

      • setNumPoolThreads

        public void setNumPoolThreads​(int numPoolThreads)
        Sets the number of pool threads used for background propagation in the concurrent sketches.
        Parameters:
        numPoolThreads - the given number of pool threads

      • getNumPoolThreads

        public int getNumPoolThreads()
        Gets the number of background pool threads used for propagation in the concurrent sketches.
        Returns:
        the number of background pool threads

      • setPropagateOrderedCompact

        public UpdateSketchBuilder setPropagateOrderedCompact​(boolean prop)
        Sets the Propagate Ordered Compact flag to the given value. Used with concurrent sketches.
        Parameters:
        prop - the given value
        Returns:
        this UpdateSketchBuilder

      • getPropagateOrderedCompact

        public boolean getPropagateOrderedCompact()
        Gets the Propagate Ordered Compact flag used with concurrent sketches.
        Returns:
        the Propagate Ordered Compact flag

      • setMaxConcurrencyError

        public void setMaxConcurrencyError​(double maxConcurrencyError)
        Sets the Maximum Concurrency Error.
        Parameters:
        maxConcurrencyError - the given Maximum Concurrency Error.

      • getMaxConcurrencyError

        public double getMaxConcurrencyError()
        Gets the Maximum Concurrency Error
        Returns:
        the Maximum Concurrency Error

      • setMaxNumLocalThreads

        public void setMaxNumLocalThreads​(int maxNumLocalThreads)
        Sets the Maximum Number of Local Threads. This is used to set the size of the local concurrent buffers.
        Parameters:
        maxNumLocalThreads - the given Maximum Number of Local Threads

      • getMaxNumLocalThreads

        public int getMaxNumLocalThreads()
        Gets the Maximum Number of Local Threads.
        Returns:
        the Maximum Number of Local Threads.

      • build

        public UpdateSketch build()
        Returns an UpdateSketch with the current configuration of this Builder.
        Returns:
        an UpdateSketch

      • build

        public UpdateSketch build​(org.apache.datasketches.memory.WritableMemory dstMem)
        Returns an UpdateSketch with the current configuration of this Builder with the specified backing destination Memory store. Note: this cannot be used with the Alpha Family of sketches.
        Parameters:
        dstMem - The destination Memory.
        Returns:
        an UpdateSketch

      • buildShared

        public UpdateSketch buildShared()
        Returns an on-heap concurrent shared UpdateSketch with the current configuration of the Builder.

        The parameters unique to the shared concurrent sketch are:

        • Number of Pool Threads (default is 3)
        • Maximum Concurrency Error

        Key parameters that are in common with other Theta sketches:

        • Nominal Entries or Log Nominal Entries (for the shared concurrent sketch)
        Returns:
        an on-heap concurrent UpdateSketch with the current configuration of the Builder.

      • buildShared

        public UpdateSketch buildShared​(org.apache.datasketches.memory.WritableMemory dstMem)
        Returns a direct (potentially off-heap) concurrent shared UpdateSketch with the current configuration of the Builder and the given destination WritableMemory. If the destination WritableMemory is null, this defaults to an on-heap concurrent shared UpdateSketch.

        The parameters unique to the shared concurrent sketch are:

        • Number of Pool Threads (default is 3)
        • Maximum Concurrency Error

        Key parameters that are in common with other Theta sketches:

        • Nominal Entries or Log Nominal Entries (for the shared concurrent sketch)
        • Destination Writable Memory (if not null, returned sketch is Direct. Default is null.)
        Parameters:
        dstMem - the given WritableMemory for Direct, otherwise null.
        Returns:
        a concurrent UpdateSketch with the current configuration of the Builder and the given destination WritableMemory.

      • buildSharedFromSketch

        public UpdateSketch buildSharedFromSketch​(UpdateSketch sketch,
                                          org.apache.datasketches.memory.WritableMemory dstMem)
        Returns a direct (potentially off-heap) concurrent shared UpdateSketch with the current configuration of the Builder, the data from the given sketch, and the given destination WritableMemory. If the destination WritableMemory is null, this defaults to an on-heap concurrent shared UpdateSketch.

        The parameters unique to the shared concurrent sketch are:

        • Number of Pool Threads (default is 3)
        • Maximum Concurrency Error

        Key parameters that are in common with other Theta sketches:

        • Nominal Entries or Log Nominal Entries (for the shared concurrent sketch)
        • Destination Writable Memory (if not null, returned sketch is Direct. Default is null.)
        Parameters:
        sketch - a given UpdateSketch from which the data is used to initialize the returned shared sketch.
        dstMem - the given WritableMemory for Direct, otherwise null.
        Returns:
        a concurrent UpdateSketch with the current configuration of the Builder and the given destination WritableMemory.

      • buildLocal

        public UpdateSketch buildLocal​(UpdateSketch shared)
        Returns a local, on-heap, concurrent UpdateSketch to be used as a per-thread local buffer along with the given concurrent shared UpdateSketch and the current configuration of this Builder.

        The parameters unique to the local concurrent sketch are:

        • Local Nominal Entries or Local Log Nominal Entries
        • Propagate Ordered Compact flag
        Parameters:
        shared - the concurrent shared sketch to be accessed via the concurrent local sketch.
        Returns:
        an UpdateSketch to be used as a per-thread local buffer.