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 015 package com.google.common.hash; 016 017 import static com.google.common.base.Preconditions.checkArgument; 018 import static com.google.common.base.Preconditions.checkNotNull; 019 020 import com.google.common.annotations.Beta; 021 import com.google.common.annotations.VisibleForTesting; 022 import com.google.common.base.Preconditions; 023 import com.google.common.hash.BloomFilterStrategies.BitArray; 024 025 import 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 * @param <T> the type of instances that the {@code BloomFilter} accepts 037 * @author Kevin Bourrillion 038 * @author Dimitris Andreou 039 * @since 11.0 040 */ 041 @Beta 042 public final class BloomFilter<T> implements Serializable { 043 /** 044 * A strategy to translate T instances, to {@code numHashFunctions} bit indexes. 045 */ 046 interface Strategy extends java.io.Serializable { 047 /** 048 * Sets {@code numHashFunctions} bits of the given bit array, by hashing a user element. 049 */ 050 <T> void put(T object, Funnel<? super T> funnel, int numHashFunctions, BitArray bits); 051 052 /** 053 * Queries {@code numHashFunctions} bits of the given bit array, by hashing a user element; 054 * returns {@code true} if and only if all selected bits are set. 055 */ 056 <T> boolean mightContain( 057 T object, Funnel<? super T> funnel, int numHashFunctions, BitArray bits); 058 } 059 060 /** The bit set of the BloomFilter (not necessarily power of 2!)*/ 061 private final BitArray bits; 062 063 /** Number of hashes per element */ 064 private final int numHashFunctions; 065 066 /** The funnel to translate Ts to bytes */ 067 private final Funnel<T> funnel; 068 069 /** 070 * The strategy we employ to map an element T to {@code numHashFunctions} bit indexes. 071 */ 072 private final Strategy strategy; 073 074 /** 075 * Creates a BloomFilter. 076 */ 077 private BloomFilter(BitArray bits, int numHashFunctions, Funnel<T> funnel, 078 Strategy strategy) { 079 Preconditions.checkArgument(numHashFunctions > 0, "numHashFunctions zero or negative"); 080 this.bits = checkNotNull(bits); 081 this.numHashFunctions = numHashFunctions; 082 this.funnel = checkNotNull(funnel); 083 this.strategy = strategy; 084 } 085 086 /** 087 * Returns {@code true} if the element <i>might</i> have been put in this Bloom filter, 088 * {@code false} if this is <i>definitely</i> not the case. 089 */ 090 public boolean mightContain(T object) { 091 return strategy.mightContain(object, funnel, numHashFunctions, bits); 092 } 093 094 /** 095 * Puts an element into this {@code BloomFilter}. Ensures that subsequent invocations of 096 * {@link #mightContain(Object)} with the same element will always return {@code true}. 097 */ 098 public void put(T object) { 099 strategy.put(object, funnel, numHashFunctions, bits); 100 } 101 102 @VisibleForTesting int getHashCount() { 103 return numHashFunctions; 104 } 105 106 @VisibleForTesting double computeExpectedFalsePositiveRate(int insertions) { 107 return Math.pow( 108 1 - Math.exp(-numHashFunctions * ((double) insertions / (bits.size()))), 109 numHashFunctions); 110 } 111 112 /** 113 * Creates a {@code Builder} of a {@link BloomFilter BloomFilter<T>}, with the expected number 114 * of insertions and expected false positive probability. 115 * 116 * <p>Note that overflowing a {@code BloomFilter} with significantly more elements 117 * than specified, will result in its saturation, and a sharp deterioration of its 118 * false positive probability. 119 * 120 * <p>The constructed {@code BloomFilter<T>} will be serializable if the provided 121 * {@code Funnel<T>} is. 122 * 123 * @param funnel the funnel of T's that the constructed {@code BloomFilter<T>} will use 124 * @param expectedInsertions the number of expected insertions to the constructed 125 * {@code BloomFilter<T>}; must be positive 126 * @param falsePositiveProbability the desired false positive probability (must be positive and 127 * less than 1.0) 128 * @return a {@code Builder} 129 */ 130 public static <T> BloomFilter<T> create(Funnel<T> funnel, int expectedInsertions /* n */, 131 double falsePositiveProbability) { 132 checkNotNull(funnel); 133 checkArgument(expectedInsertions > 0, "Expected insertions must be positive"); 134 checkArgument(falsePositiveProbability > 0.0 & falsePositiveProbability < 1.0, 135 "False positive probability in (0.0, 1.0)"); 136 /* 137 * andreou: I wanted to put a warning in the javadoc about tiny fpp values, 138 * since the resulting size is proportional to -log(p), but there is not 139 * much of a point after all, e.g. optimalM(1000, 0.0000000000000001) = 76680 140 * which is less that 10kb. Who cares! 141 */ 142 int numBits = optimalNumOfBits(expectedInsertions, falsePositiveProbability); 143 int numHashFunctions = optimalNumOfHashFunctions(expectedInsertions, numBits); 144 return new BloomFilter<T>(new BitArray(numBits), numHashFunctions, funnel, 145 BloomFilterStrategies.MURMUR128_MITZ_32); 146 } 147 148 /** 149 * Creates a {@code Builder} of a {@link BloomFilter BloomFilter<T>}, with the expected number 150 * of insertions, and a default expected false positive probability of 3%. 151 * 152 * <p>Note that overflowing a {@code BloomFilter} with significantly more elements 153 * than specified, will result in its saturation, and a sharp deterioration of its 154 * false positive probability. 155 * 156 * <p>The constructed {@code BloomFilter<T>} will be serializable if the provided 157 * {@code Funnel<T>} is. 158 * 159 * @param funnel the funnel of T's that the constructed {@code BloomFilter<T>} will use 160 * @param expectedInsertions the number of expected insertions to the constructed 161 * {@code BloomFilter<T>}; must be positive 162 * @return a {@code Builder} 163 */ 164 public static <T> BloomFilter<T> create(Funnel<T> funnel, int expectedInsertions /* n */) { 165 return create(funnel, expectedInsertions, 0.03); // FYI, for 3%, we always get 5 hash functions 166 } 167 168 /* 169 * Cheat sheet: 170 * 171 * m: total bits 172 * n: expected insertions 173 * b: m/n, bits per insertion 174 175 * p: expected false positive probability 176 * 177 * 1) Optimal k = b * ln2 178 * 2) p = (1 - e ^ (-kn/m))^k 179 * 3) For optimal k: p = 2 ^ (-k) ~= 0.6185^b 180 * 4) For optimal k: m = -nlnp / ((ln2) ^ 2) 181 */ 182 183 private static final double LN2 = Math.log(2); 184 private static final double LN2_SQUARED = LN2 * LN2; 185 186 /** 187 * Computes the optimal k (number of hashes per element inserted in Bloom filter), given the 188 * expected insertions and total number of bits in the Bloom filter. 189 * 190 * See http://en.wikipedia.org/wiki/File:Bloom_filter_fp_probability.svg for the formula. 191 * 192 * @param n expected insertions (must be positive) 193 * @param m total number of bits in Bloom filter (must be positive) 194 */ 195 @VisibleForTesting static int optimalNumOfHashFunctions(int n, int m) { 196 return Math.max(1, (int) Math.round(m / n * LN2)); 197 } 198 199 /** 200 * Computes m (total bits of Bloom filter) which is expected to achieve, for the specified 201 * expected insertions, the required false positive probability. 202 * 203 * See http://en.wikipedia.org/wiki/Bloom_filter#Probability_of_false_positives for the formula. 204 * 205 * @param n expected insertions (must be positive) 206 * @param p false positive rate (must be 0 < p < 1) 207 */ 208 @VisibleForTesting static int optimalNumOfBits(int n, double p) { 209 return (int) (-n * Math.log(p) / LN2_SQUARED); 210 } 211 212 private Object writeReplace() { 213 return new SerialForm<T>(this); 214 } 215 216 private static class SerialForm<T> implements Serializable { 217 final long[] data; 218 final int numHashFunctions; 219 final Funnel<T> funnel; 220 final Strategy strategy; 221 222 SerialForm(BloomFilter<T> bf) { 223 this.data = bf.bits.data; 224 this.numHashFunctions = bf.numHashFunctions; 225 this.funnel = bf.funnel; 226 this.strategy = bf.strategy; 227 } 228 Object readResolve() { 229 return new BloomFilter<T>(new BitArray(data), numHashFunctions, funnel, strategy); 230 } 231 private static final long serialVersionUID = 1; 232 } 233 }