maintner, godata: explain updates and read locks
Explain how to keep the godata corpus up-to-date, and clarify the
requirements around locking and updating.
Fix a typo.
Change-Id: Ic9dbe203d1dee7ad3c7463ae932df5daadb51923
Reviewed-on: https://go-review.googlesource.com/47813
Reviewed-by: Andrew Bonventre <andybons@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
diff --git a/maintner/godata/godata.go b/maintner/godata/godata.go
index 80d96ca..3293bab 100644
--- a/maintner/godata/godata.go
+++ b/maintner/godata/godata.go
@@ -23,6 +23,9 @@
// Github activity, and Gerrit activity and metadata since the
// beginning of the project.
//
+// Use Corpus.Update to keep the corpus up-to-date. If you do this, you must
+// hold the read lock if reading and updating concurrently.
+//
// The initial call to Get will download approximately 350-400 MB of
// data into a directory "golang-maintner" under your operating
// system's user cache directory. Subsequent calls will only download
diff --git a/maintner/maintner.go b/maintner/maintner.go
index d8bbd59..07f66ee 100644
--- a/maintner/maintner.go
+++ b/maintner/maintner.go
@@ -64,7 +64,7 @@
}
// RLock grabs the corpus's read lock. Grabbing the read lock prevents
-// any concurrent writes from mutation the corpus. This is only
+// any concurrent writes from mutating the corpus. This is only
// necessary if the application is querying the corpus and calling its
// Update method concurrently.
func (c *Corpus) RLock() { c.mu.RLock() }
@@ -249,8 +249,9 @@
// the context expires.
// If Update returns ErrSplit, the corpus can longer be updated.
//
-// Update must not be called concurrently with any other method or
-// access of the corpus, including other Update calls.
+// Update must not be called concurrently with any other Update calls. If
+// reading the corpus concurrently while the corpus is updating, you must hold
+// the read lock using Corpus.RLock.
func (c *Corpus) Update(ctx context.Context) error {
if c.mutationSource == nil {
panic("Update called without call to Initialize")
