Adding documentation and example about thread safety.

Note that lookups (when there's no concurrent deletes/inserts) are
thread safe.

Author: panmari

README.md

@@ -58,3 +58,5 @@ func Example() {
 ```
 
 For more examples, see [the example tests](https://github.com/panmari/cuckoofilter/blob/master/example_test.go).
+Operations on a filter are not thread safe by default. 
+See [this example](example_threadsafe_test.go) for using the filter concurrently.

example_threadsafe_test.go

@@ -0,0 +1,63 @@
+package cuckoo_test
+
+import (
+	"fmt"
+	"sync"
+
+	cuckoo "github.com/panmari/cuckoofilter"
+)
+
+// Small wrapper around cuckoo filter making it thread safe.
+type threadSafeFilter struct {
+	cf *cuckoo.Filter
+	mu sync.RWMutex
+}
+
+func (f *threadSafeFilter) insert(item []byte) {
+	// Concurrent inserts need a Write lock.
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.cf.Insert(item)
+}
+
+func (f *threadSafeFilter) lookup(item []byte) bool {
+	// Concurrent lookups need a read lock.
+	f.mu.RLock()
+	defer f.mu.RUnlock()
+	return f.cf.Lookup(item)
+}
+
+func Example_threadSafe() {
+	cf := &threadSafeFilter{
+		cf: cuckoo.NewFilter(1000),
+	}
+
+	var wg sync.WaitGroup
+	// Insert items concurrently...
+	for i := byte(0); i < 50; i++ {
+		wg.Add(1)
+		go func(item byte) {
+			defer wg.Done()
+			cf.insert([]byte{item})
+		}(i)
+	}
+
+	// ...while also doing lookups concurrently.
+	for i := byte(0); i < 100; i++ {
+		wg.Add(1)
+		go func(item byte) {
+			defer wg.Done()
+			// State is not well-defined here, so we can't define expectations.
+			cf.lookup([]byte{item})
+		}(i)
+	}
+	wg.Wait()
+
+	// Simple lookups to verify initialization.
+	fmt.Println(cf.lookup([]byte{1}))
+	fmt.Println(cf.lookup([]byte{99}))
+
+	// Output:
+	// true
+	// false
+}