Fix races in txnBuf

filter/txnBuf/doc.go

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Package txnBuf contains a transaction buffer filter for the datastore
 // service.
 //
 // By default, datastore transactions take a snapshot of the entity group as
 // soon as you Get or Put into it. All subsequent Get (and query) operations
 // reflect the state of the ORIGINAL transaction snapshot, regardless of any
@@ skipping 39 matching lines @@
 //   - Metadata entities (e.g. `__entity_group__`) will reflect their values as
 //     they were at the beginning of the transaction, and will not increment
 //     as you write inside of the transaction.
 //
 //   - Query cursors are not supported. Since the cursor format for the
 //     in-memory datastore implementation isn't compatible with the production
 //     cursors, it would be pretty tricky to make it so that cursors were
 //     viable outside the transaction as well as inside of it while also having
 //     it accurately reflect the 'merged' query results.
 //
-//   - No parallel access to datastore while in a transaction; all nested
-//     transactions are serialized. This is done for simplicity and correctness.
+//   - No parallel access* to datastore while in a transaction; all nested
+//     operations are serialized. This is done for simplicity and correctness.
+//
+//     * The exception is that callbacks inside of
+//     a Run/GetMulti/DeleteMulti/PutMulti query MAY read/write the current
+//     transaction. Modifications to the datastore during query executions will
+//     not affect the query results (e.g. the query has snapshot consistency
+//     from the moment that it begins iteration). Note, however, that datastore
+//     operations within the callback are still synchronized. This behavior is
+//     so that the user is not forced to buffer all of the query results before
+//     doing work with them, but can treat the query like a stream of events,
+//     if they so choose.
 //
 //   - The changing of namespace inside of a transaction is undefined... This is
 //     just generally a terrible idea anyway, but I thought it was worth
 //     mentioning.
 package txnBuf