Improving documentation for major release.

Author: panmari

cuckoofilter.go

@@ -10,7 +10,7 @@ import (
 // is attempted.
 const maxCuckooKickouts = 500
 
-// Filter is a probabilistic counter
+// Filter is a probabilistic counter.
 type Filter struct {
 	buckets []bucket
 	count   uint
@@ -19,10 +19,10 @@ type Filter struct {
 	bucketIndexMask uint
 }
 
-// NewFilter returns a new cuckoofilter sutable for the given number of elements.
-// When inserting more elements, insertion speed will drop significantly.
+// NewFilter returns a new cuckoofilter suitable for the given number of elements.
+// When inserting more elements, insertion speed will drop significantly and insertions might fail altogether.
 // A capacity of 1000000 is a normal default, which allocates
-// about ~1MB on 64-bit machines.
+// about ~2MB on 64-bit machines.
 func NewFilter(numElements uint) *Filter {
 	numBuckets := getNextPow2(uint64(numElements / bucketSize))
 	if float64(numElements)/float64(numBuckets*bucketSize) > 0.96 {
@@ -58,14 +58,10 @@ func (cf *Filter) Reset() {
 	cf.count = 0
 }
 
-func randi(i1, i2 uint) uint {
-	if rand.Int31()%2 == 0 {
-		return i1
-	}
-	return i2
-}
-
-// Insert inserts data into the counter and returns true upon success
+// Insert data into the filter. Returns false if insertion failed. In the resulting state, the filter
+// * Might return false negatives
+// * Deletes are not guaranteed to work
+// To increase success rate of inserts, create a larger filter.
 func (cf *Filter) Insert(data []byte) bool {
 	i1, fp := getIndexAndFingerprint(data, cf.bucketIndexMask)
 	if cf.insert(fp, i1) {
@@ -101,7 +97,7 @@ func (cf *Filter) reinsert(fp fingerprint, i uint) bool {
 	return false
 }
 
-// Delete data from counter if exists and return if deleted or not
+// Delete data from the filter. Returns true if the data was found and deleted.
 func (cf *Filter) Delete(data []byte) bool {
 	i1, fp := getIndexAndFingerprint(data, cf.bucketIndexMask)
 	i2 := getAltIndex(fp, i1, cf.bucketIndexMask)
@@ -116,7 +112,7 @@ func (cf *Filter) delete(fp fingerprint, i uint) bool {
 	return false
 }
 
-// Count returns the number of items in the counter
+// Count returns the number of items in the filter.
 func (cf *Filter) Count() uint {
 	return cf.count
 }
@@ -126,7 +122,7 @@ func (cf *Filter) LoadFactor() float64 {
 	return float64(cf.count) / float64(len(cf.buckets)*bucketSize)
 }
 
-// Encode returns a byte slice representing a Cuckoofilter
+// Encode returns a byte slice representing a Cuckoofilter.
 func (cf *Filter) Encode() []byte {
 	bytes := make([]byte, 0, len(cf.buckets)*bucketSize*fingerprintSizeBits/8)
 	for _, b := range cf.buckets {
@@ -139,7 +135,7 @@ func (cf *Filter) Encode() []byte {
 	return bytes
 }
 
-// Decode returns a Cuckoofilter from a byte slice
+// Decode returns a Cuckoofilter from a byte slice created using Encode.
 func Decode(bytes []byte) (*Filter, error) {
 	var count uint
 	if len(bytes)%bucketSize != 0 {

util.go

@@ -2,10 +2,19 @@ package cuckoo
 
 import (
 	"encoding/binary"
+	"math/rand"
 
 	metro "github.com/dgryski/go-metro"
 )
 
+// randi returns either i1 or i2 randomly.
+func randi(i1, i2 uint) uint {
+	if rand.Int31()%2 == 0 {
+		return i1
+	}
+	return i2
+}
+
 func getAltIndex(fp fingerprint, i uint, bucketIndexMask uint) uint {
 	b := make([]byte, 2)
 	binary.LittleEndian.PutUint16(b, uint16(fp))