Do major refactoring re: resource management.

Changes to the API:

* Most types have a Close() method, which can be used to explicitly free
  the memory used by the type. The garbage collector will still pick
  them up eventually, but since the go GC sometimes doesn't make the
  smartest decisions about foreign objects, this is available.

Functional changes to the implementation:

* Close() methods (which are called by GC) are now much safer and more
  robust:
  * They are now thread-safe.
  * It is safe to call them more than once.
  * It is safe to call Close() on a child object whose parent has
    already been Close()d.

The above issues were causing runtime panics under various
circumstances. There are a few of these still to hunt down.

The details of the internals are described in the file
README-INTERNALS.md

Organizational changes to the implementation:

* Everything with a Close() method is defined in terms of a type
  cStruct, which captures most of the common functionality between them.
  There's generally less boilerplate, and allows only writing the tricky
  synchronization stuff for use with Close()/GC once.

Author: zenhack

README-INTERNALS.md

@@ -0,0 +1,49 @@
+This document describes some general patterns in the implementation.
+
+# Resource reclamation.
+
+The library is written such that all resources will be released when the
+garbage collector claims an object. However, we also export Close()
+methods on each type that needs explicit cleanup. This is because the Go
+garbage collector [isn't always able to make the right decisions about
+objects with pointers to C memory][1].
+
+## Tracking dependencies
+
+Each notmuch object has a corresponding wrapper object:
+notmuch_database_t is wrapped by DB, notmuch_query_t is wrapped by Query
+and so on. Each of these wrappers is an alias for the type cStruct,
+which holds a pointer to the underlying C object, and also to the
+wrappers for any objects referenced by the underlying C object (via the
+"parents" field).  This keeps the GC from collecting parent objects if
+the children are still in use.
+
+## Creating objects
+
+When creating an object, the caller should set the parents field to a
+slice containing pointers to the object's immediate parent objects, and
+set cptr to the underlying c pointer. Finally, calling setGcClose on the
+object will cause it to be released properly by the garbage collector.
+
+## Cleaning up
+
+Calling the `Close()` method on an object a second time is a no-op, and
+thus always safe. The primary reason for this is that it makes dealing
+with mixing GC and manual reclamation simple.
+
+The Close methods also clear all of their references to parent objects
+explicitly. While this isn't strictly necessary, it means the GC
+will know that they are unreachable sooner, if that becomes the case.
+Per the documentation for `runtime.SetFinalizer`, once the finalizer is
+called, the object will stick around until the next time the GC looks at
+it. Because of this, it won't otherwise even consider parent objects
+until the third pass at least.
+
+In some cases, invoking the `*_destroy` function on an object also
+cleans up its children, in which case it becomes unsafe to then invoke
+their `*_destroy` function. cStruct handles all of the bookkeeping and
+synchronization necessary to deal with this; derived types just need to
+make proper use of doClose() in their Close() implementation (see the
+comments in cstruct.go)
+
+[1]: https://gist.github.com/dwbuiten/c9865c4afb38f482702e#cleaning

cstruct.go

@@ -0,0 +1,99 @@
+package notmuch
+
+// Copyright © 2015 The go.notmuch Authors. Authors can be found in the AUTHORS file.
+// Licensed under the GPLv3 or later.
+// See COPYING at the root of the repository for details.
+
+import (
+	"io"
+	"runtime"
+	"sync"
+	"unsafe"
+)
+
+// cStruct is the common representation of almost all of our wrapper types.
+//
+// It does the heavy lifting of interacting with the garbage
+// collector/*_destroy functions.
+type cStruct struct {
+	// A pointer to the underlying c object
+	cptr unsafe.Pointer
+
+	// Parent object. Holding a pointer to this in Go-land makes the reference
+	// visible to the garbage collector, and thus prevents it from being
+	// reclaimed prematurely.
+	parent *cStruct
+
+	// readers-writer lock for dealing with mixing manual calls to Close() with
+	// GC.
+	lock sync.RWMutex
+}
+
+// Recursively acquire read locks on this object and all parent objects.
+func (c *cStruct) rLock() {
+	c.lock.RLock()
+	if c.parent != nil {
+		c.parent.rLock()
+	}
+}
+
+// Recursively release read locks this object and all parent objects.
+func (c *cStruct) rUnlock() {
+	if c.parent != nil {
+		c.parent.rUnlock()
+	}
+	c.lock.RUnlock()
+}
+
+// Call f in a context in which it is safe to destroy the underlying C object.
+// `f` will only be invoked if the underlying object is still live. When `f`
+// is invoked,  The calling goroutine will hold the necessary locks to make
+// destroying the underlying object safe.
+//
+// Typically, wrapper types will use this to implement their Close() methods;
+// it handles all of the synchronization bits.
+func (c *cStruct) doClose(f func() error) error {
+	// Briefly:
+	// 1. Acquire a write lock on ourselves.
+	// 2. Acquire read locks for all of our ancestors in pre-order (the ordering
+	//    is important to avoid deadlocks).
+	// 3. Check if we're live, and call f if so.
+	// 4. Clear all of our references to other objects, and release the locks
+	var err error
+	c.lock.Lock()
+	if c.parent != nil {
+		c.parent.rLock()
+	}
+	if c.live() {
+		err = f()
+	}
+	if c.parent != nil {
+		c.parent.rUnlock()
+	}
+	c.cptr = nil
+	c.parent = nil
+	c.lock.Unlock()
+	return err
+}
+
+// Returns true if and only if c's underlying object is live, i.e. neither it
+// nor any of its ancestor objects have been finalized.
+//
+// Note that this method does no synchronization; the caller must separately
+// acquire the necessary locks.
+func (c *cStruct) live() bool {
+	if c.cptr == nil {
+		return false
+	}
+	if c.parent == nil {
+		return true
+	}
+	return c.parent.live()
+}
+
+// Set a finalizer to invoke c.Close() when c is garbage collected.
+func setGcClose(c io.Closer) {
+	runtime.SetFinalizer(c, func(c io.Closer) {
+		c.Close()
+	})
+}