001/*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.hash;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019
020import com.google.common.annotations.Beta;
021import com.google.common.annotations.VisibleForTesting;
022import com.google.common.base.Preconditions;
023import com.google.common.hash.BloomFilterStrategies.BitArray;
024
025import java.io.Serializable;
026
027/**
028 * A Bloom filter for instances of {@code T}. A Bloom filter offers an approximate containment test
029 * with one-sided error: if it claims that an element is contained in it, this might be in error,
030 * but if it claims that an element is <i>not</i> contained in it, then this is definitely true.
031 *
032 * <p>If you are unfamiliar with Bloom filters, this nice
033 * <a href="http://llimllib.github.com/bloomfilter-tutorial/">tutorial</a> may help you understand
034 * how they work.
035 *
036 *
037 * @param <T> the type of instances that the {@code BloomFilter} accepts
038 * @author Dimitris Andreou
039 * @author Kevin Bourrillion
040 * @since 11.0
041 */
042@Beta
043public final class BloomFilter<T> implements Serializable {
044  /**
045   * A strategy to translate T instances, to {@code numHashFunctions} bit indexes.
046   *
047   * <p>Implementations should be collections of pure functions (i.e. stateless).
048   */
049  interface Strategy extends java.io.Serializable {
050
051    /**
052     * Sets {@code numHashFunctions} bits of the given bit array, by hashing a user element.
053     *
054     * <p>Returns whether any bits changed as a result of this operation.
055     */
056    <T> boolean put(T object, Funnel<? super T> funnel, int numHashFunctions, BitArray bits);
057
058    /**
059     * Queries {@code numHashFunctions} bits of the given bit array, by hashing a user element;
060     * returns {@code true} if and only if all selected bits are set.
061     */
062    <T> boolean mightContain(
063        T object, Funnel<? super T> funnel, int numHashFunctions, BitArray bits);
064
065    /**
066     * Identifier used to encode this strategy, when marshalled as part of a BloomFilter.
067     * Only values in the [-128, 127] range are valid for the compact serial form.
068     * Non-negative values are reserved for enums defined in BloomFilterStrategies;
069     * negative values are reserved for any custom, stateful strategy we may define
070     * (e.g. any kind of strategy that would depend on user input).
071     */
072    int ordinal();
073  }
074
075  /** The bit set of the BloomFilter (not necessarily power of 2!)*/
076  private final BitArray bits;
077
078  /** Number of hashes per element */
079  private final int numHashFunctions;
080
081  /** The funnel to translate Ts to bytes */
082  private final Funnel<T> funnel;
083
084  /**
085   * The strategy we employ to map an element T to {@code numHashFunctions} bit indexes.
086   */
087  private final Strategy strategy;
088
089  /**
090   * Creates a BloomFilter.
091   */
092  private BloomFilter(BitArray bits, int numHashFunctions, Funnel<T> funnel,
093      Strategy strategy) {
094    Preconditions.checkArgument(numHashFunctions > 0, "numHashFunctions zero or negative");
095    this.bits = checkNotNull(bits);
096    this.numHashFunctions = numHashFunctions;
097    this.funnel = checkNotNull(funnel);
098    this.strategy = strategy;
099
100    /*
101     * This only exists to forbid BFs that cannot use the compact persistent representation.
102     * If it ever throws, at a user who was not intending to use that representation, we should
103     * reconsider
104     */
105    if (numHashFunctions > 255) {
106      throw new AssertionError("Currently we don't allow BloomFilters that would use more than" +
107          "255 hash functions, please contact the guava team");
108    }
109  }
110
111  /**
112   * Creates a new {@code BloomFilter} that's a copy of this instance. The new instance is equal to
113   * this instance but shares no mutable state.
114   *
115   * @since 12.0
116   */
117  public BloomFilter<T> copy() {
118    return new BloomFilter<T>(bits.copy(), numHashFunctions, funnel, strategy);
119  }
120
121  /**
122   * Returns {@code true} if the element <i>might</i> have been put in this Bloom filter,
123   * {@code false} if this is <i>definitely</i> not the case.
124   */
125  public boolean mightContain(T object) {
126    return strategy.mightContain(object, funnel, numHashFunctions, bits);
127  }
128
129  /**
130   * Puts an element into this {@code BloomFilter}. Ensures that subsequent invocations of
131   * {@link #mightContain(Object)} with the same element will always return {@code true}.
132   *
133   * @return true if the bloom filter's bits changed as a result of this operation. If the bits
134   *         changed, this is <i>definitely</i> the first time {@code object} has been added to the
135   *         filter. If the bits haven't changed, this <i>might</i> be the first time {@code object}
136   *         has been added to the filter. Note that {@code put(t)} always returns the
137   *         <i>opposite</i> result to what {@code mightContain(t)} would have returned at the time
138   *         it is called."
139   * @since 12.0 (present in 11.0 with {@code void} return type})
140   */
141  public boolean put(T object) {
142    return strategy.put(object, funnel, numHashFunctions, bits);
143  }
144
145  /**
146   * Returns the probability that {@linkplain #mightContain(Object)} will erroneously return
147   * {@code true} for an object that has not actually been put in the {@code BloomFilter}.
148   *
149   * <p>Ideally, this number should be close to the {@code falsePositiveProbability} parameter
150   * passed in {@linkplain #create(Funnel, int, double)}, or smaller. If it is
151   * significantly higher, it is usually the case that too many elements (more than
152   * expected) have been put in the {@code BloomFilter}, degenerating it.
153   */
154  public double expectedFalsePositiveProbability() {
155    return Math.pow((double) bits.bitCount() / bits.size(), numHashFunctions);
156  }
157
158  /**
159   * {@inheritDoc}
160   *
161   * <p>This implementation uses reference equality to compare funnels.
162   */
163  @Override public boolean equals(Object o) {
164    if (o instanceof BloomFilter) {
165      BloomFilter<?> that = (BloomFilter<?>) o;
166      return this.numHashFunctions == that.numHashFunctions
167          && this.bits.equals(that.bits)
168          && this.funnel == that.funnel
169          && this.strategy == that.strategy;
170    }
171    return false;
172  }
173
174  @Override public int hashCode() {
175    return bits.hashCode();
176  }
177
178  @VisibleForTesting int getHashCount() {
179    return numHashFunctions;
180  }
181
182  /**
183   * Creates a {@code Builder} of a {@link BloomFilter BloomFilter<T>}, with the expected number
184   * of insertions and expected false positive probability.
185   *
186   * <p>Note that overflowing a {@code BloomFilter} with significantly more elements
187   * than specified, will result in its saturation, and a sharp deterioration of its
188   * false positive probability.
189   *
190   * <p>The constructed {@code BloomFilter<T>} will be serializable if the provided
191   * {@code Funnel<T>} is.
192   *
193   * <p>It is recommended the funnel is implemented as a Java enum. This has the benefit of ensuring
194   * proper serialization and deserialization, which is important since {@link #equals} also relies
195   * on object identity of funnels.
196   *
197   * @param funnel the funnel of T's that the constructed {@code BloomFilter<T>} will use
198   * @param expectedInsertions the number of expected insertions to the constructed
199   *        {@code BloomFilter<T>}; must be positive
200   * @param falsePositiveProbability the desired false positive probability (must be positive and
201   *        less than 1.0)
202   * @return a {@code BloomFilter}
203   */
204  public static <T> BloomFilter<T> create(Funnel<T> funnel, int expectedInsertions /* n */,
205      double falsePositiveProbability) {
206    checkNotNull(funnel);
207    checkArgument(expectedInsertions >= 0, "Expected insertions cannot be negative");
208    checkArgument(falsePositiveProbability > 0.0 & falsePositiveProbability < 1.0,
209        "False positive probability in (0.0, 1.0)");
210    if (expectedInsertions == 0) {
211      expectedInsertions = 1;
212    }
213    /*
214     * andreou: I wanted to put a warning in the javadoc about tiny fpp values,
215     * since the resulting size is proportional to -log(p), but there is not
216     * much of a point after all, e.g. optimalM(1000, 0.0000000000000001) = 76680
217     * which is less that 10kb. Who cares!
218     */
219    int numBits = optimalNumOfBits(expectedInsertions, falsePositiveProbability);
220    int numHashFunctions = optimalNumOfHashFunctions(expectedInsertions, numBits);
221    return new BloomFilter<T>(new BitArray(numBits), numHashFunctions, funnel,
222        BloomFilterStrategies.MURMUR128_MITZ_32);
223  }
224
225  /**
226   * Creates a {@code Builder} of a {@link BloomFilter BloomFilter<T>}, with the expected number
227   * of insertions, and a default expected false positive probability of 3%.
228   *
229   * <p>Note that overflowing a {@code BloomFilter} with significantly more elements
230   * than specified, will result in its saturation, and a sharp deterioration of its
231   * false positive probability.
232   *
233   * <p>The constructed {@code BloomFilter<T>} will be serializable if the provided
234   * {@code Funnel<T>} is.
235   *
236   * @param funnel the funnel of T's that the constructed {@code BloomFilter<T>} will use
237   * @param expectedInsertions the number of expected insertions to the constructed
238   *        {@code BloomFilter<T>}; must be positive
239   * @return a {@code BloomFilter}
240   */
241  public static <T> BloomFilter<T> create(Funnel<T> funnel, int expectedInsertions /* n */) {
242    return create(funnel, expectedInsertions, 0.03); // FYI, for 3%, we always get 5 hash functions
243  }
244
245  /*
246   * Cheat sheet:
247   *
248   * m: total bits
249   * n: expected insertions
250   * b: m/n, bits per insertion
251
252   * p: expected false positive probability
253   *
254   * 1) Optimal k = b * ln2
255   * 2) p = (1 - e ^ (-kn/m))^k
256   * 3) For optimal k: p = 2 ^ (-k) ~= 0.6185^b
257   * 4) For optimal k: m = -nlnp / ((ln2) ^ 2)
258   */
259
260  private static final double LN2 = Math.log(2);
261  private static final double LN2_SQUARED = LN2 * LN2;
262
263  /**
264   * Computes the optimal k (number of hashes per element inserted in Bloom filter), given the
265   * expected insertions and total number of bits in the Bloom filter.
266   *
267   * See http://en.wikipedia.org/wiki/File:Bloom_filter_fp_probability.svg for the formula.
268   *
269   * @param n expected insertions (must be positive)
270   * @param m total number of bits in Bloom filter (must be positive)
271   */
272  @VisibleForTesting static int optimalNumOfHashFunctions(int n, int m) {
273    return Math.max(1, (int) Math.round(m / n * LN2));
274  }
275
276  /**
277   * Computes m (total bits of Bloom filter) which is expected to achieve, for the specified
278   * expected insertions, the required false positive probability.
279   *
280   * See http://en.wikipedia.org/wiki/Bloom_filter#Probability_of_false_positives for the formula.
281   *
282   * @param n expected insertions (must be positive)
283   * @param p false positive rate (must be 0 < p < 1)
284   */
285  @VisibleForTesting static int optimalNumOfBits(int n, double p) {
286    return (int) (-n * Math.log(p) / LN2_SQUARED);
287  }
288
289  private Object writeReplace() {
290    return new SerialForm<T>(this);
291  }
292
293  private static class SerialForm<T> implements Serializable {
294    final long[] data;
295    final int numHashFunctions;
296    final Funnel<T> funnel;
297    final Strategy strategy;
298
299    SerialForm(BloomFilter<T> bf) {
300      this.data = bf.bits.data;
301      this.numHashFunctions = bf.numHashFunctions;
302      this.funnel = bf.funnel;
303      this.strategy = bf.strategy;
304    }
305    Object readResolve() {
306      return new BloomFilter<T>(new BitArray(data), numHashFunctions, funnel, strategy);
307    }
308    private static final long serialVersionUID = 1;
309  }
310}