Package com.hazelcast.cardinality

Interface CardinalityEstimator

  • All Superinterfaces:
    DistributedObject
    public interface CardinalityEstimator
extends DistributedObject
    CardinalityEstimator is a redundant and highly available distributed data-structure used for probabilistic cardinality estimation purposes, on unique items, in significantly sized data cultures.

    CardinalityEstimator is internally based on a HyperLogLog++ data-structure, and uses P^2 byte registers for storage and computation. (Default P = 14)

    Supports split brain protection SplitBrainProtectionConfig since 3.10 in cluster versions 3.10 and higher.

    Asynchronous methods

    Asynchronous methods return a CompletionStage that can be used to chain further computation stages. Alternatively, a CompletableFuture can be obtained via CompletionStage.toCompletableFuture() to wait for the operation to complete in a blocking way.

    Actions supplied for dependent completions of default non-async methods and async methods without an explicit Executor argument are performed by the ForkJoinPool.commonPool() (unless it does not support a parallelism level of at least 2, in which case a new Thread is created per task).

    • Method Detail

      • add

        void add​(@Nonnull
         java.lang.Object obj)
        Add a new object in the estimation set. This is the method you want to use to feed objects into the estimator.

        Objects are considered identical if they are serialized into the same binary blob. In other words: It does not use Java equality.

        Parameters:
        obj - object to add in the estimation set.
        Throws:
        java.lang.NullPointerException - if obj is null
        Since:
        3.8

      • estimate

        long estimate()
        Estimates the cardinality of the aggregation so far. If it was previously estimated and never invalidated, then a cached version is used.
        Returns:
        a cached estimation or a newly computed one.
        Since:
        3.8

      • addAsync

        java.util.concurrent.CompletionStage<java.lang.Void> addAsync​(@Nonnull
                                                              java.lang.Object obj)
        Add a new object in the estimation set. This is the method you want to use to feed objects into the estimator.

        Objects are considered identical if they are serialized into the same binary blob. In other words: It does not use Java equality.

        This method will dispatch a request and return immediately a CompletionStage. The operations result can be obtained in a blocking way, or a callback can be provided for execution upon completion, as demonstrated in the following examples: 

             CompletionStage<Void> stage = estimator.addAsync();
     // do something else, then read the result
     Boolean result = stage.toCompletableFuture().get(); // this method will block until the result is available
 
             CompletionStage<Void> stage = estimator.addAsync();
     stage.whenCompleteAsync((response, throwable) -> {
          if (throwable == null) {
              // do something
          } else {
              // handle failure
          }
     });
        Parameters:
        obj - object to add in the estimation set.
        Returns:
        a CompletionStage API consumers can use to chain further computation stages
        Throws:
        java.lang.NullPointerException - if obj is null
        Since:
        3.8

      • estimateAsync

        java.util.concurrent.CompletionStage<java.lang.Long> estimateAsync()
        Estimates the cardinality of the aggregation so far. If it was previously estimated and never invalidated, then a cached version is used.

        This method will dispatch a request and return immediately a CompletionStage. The operations result can be obtained in a blocking way, or a callback can be provided for execution upon completion, as demonstrated in the following examples: 

             CompletionStage<Long> stage = estimator.estimateAsync();
     // do something else, then read the result
     Long result = stage.toCompletableFuture().get(); // this method will block until the result is available
 
             CompletionStage<Long> stage = estimator.estimateAsync();
     stage.whenCompleteAsync((response, throwable) -> {
          if (throwable == null) {
              // do something with the result
          } else {
              // handle failure
          }
     });
        Returns:
        CompletionStage bearing the response, the estimate.
        Since:
        3.8