datastore: Update AllocateIDs to take keys.

service/datastore/raw_interface.go

 // Copyright 2015 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 package datastore
 
 import (
         "fmt"
 
         "golang.org/x/net/context"
@@ skipping 24 matching lines @@
 //
 //   - val is the data of the entity
 //     * It may be nil if some of the keys to the GetMulti were bad, since all
 //       keys are validated before the RPC occurs!
 //   - err is an error associated with this entity (e.g. ErrNoSuchEntity).
 //
 // Return nil to continue iterating, or an error to stop. If you return the
 // error `Stop`, then GetMulti will stop the query and return nil.
 type GetMultiCB func(val PropertyMap, err error) error
 
-// PutMultiCB is the callback signature provided to RawInterface.PutMulti
+// NewKeyCB is the callback signature provided to RawInterface.PutMulti and
+// RawInterface.AllocateIDs. It is invoked once for each positional key that
+// was generated as the result of a call.
 //
 //   - key is the new key for the entity (if the original was incomplete)
 //     * It may be nil if some of the keys/vals to the PutMulti were bad, since
 //       all keys are validated before the RPC occurs!
 //   - err is an error associated with putting this entity.
 //
 // Return nil to continue iterating, or an error to stop. If you return the
 // error `Stop`, then PutMulti will stop the query and return nil.
-type PutMultiCB func(key *Key, err error) error
+type NewKeyCB func(key *Key, err error) error
 
 // DeleteMultiCB is the callback signature provided to RawInterface.DeleteMulti
 //
 //   - err is an error associated with deleting this entity.
 //
 // Return nil to continue iterating, or an error to stop. If you return the
 // error `Stop`, then DeleteMulti will stop the query and return nil.
 type DeleteMultiCB func(err error) error
 
 type nullMetaGetterType struct{}
@@ skipping 33 matching lines @@
                 return nullMetaGetter
         }
         return m[idx]
 }
 
 // RawInterface implements the datastore functionality without any of the fancy
 // reflection stuff. This is so that Filters can avoid doing lots of redundant
 // reflection work. See datastore.Interface for a more user-friendly interface.
 type RawInterface interface {
         // AllocateIDs allows you to allocate IDs from the datastore without putting
-        // any data. `incomplete` must be a PartialValid Key. If there's no error,
-        // a contiguous block of IDs of n length starting at `start` will be reserved
-        // indefinitely for the user application code for use in new keys. The
-        // appengine automatic ID generator will never automatically assign these IDs
-        // for Keys of this type.
-        AllocateIDs(incomplete *Key, n int) (start int64, err error)
+        // any data. The supplied keys must be PartialValid and share the same entity
+        // type.
+        //
+        // If there's no error, the keys in the slice will be replaced with keys
+        // containing integer IDs assigned to them.
+        AllocateIDs(keys []*Key, cb NewKeyCB) error
 
         // RunInTransaction runs f in a transaction.
         //
         // opts may be nil.
         //
         // NOTE: Implementations and filters are guaranteed that:
         //   - f is not nil
         RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error
 
         // DecodeCursor converts a string returned by a Cursor into a Cursor instance.
@@ skipping 29 matching lines @@
         // PutMulti writes items to the datastore.
         //
         // Callback execues once per key/value pair, in the passed-in order. Callback
         // may not execute at all if there was a server error.
         //
         // NOTE: Implementations and filters are guaranteed that:
         //   - len(keys) > 0
         //   - len(keys) == len(vals)
         //   - all keys are Valid and in the current namespace
         //   - cb is not nil
-        PutMulti(keys []*Key, vals []PropertyMap, cb PutMultiCB) error
+        PutMulti(keys []*Key, vals []PropertyMap, cb NewKeyCB) error
 
         // DeleteMulti removes items from the datastore.
         //
         // Callback execues once per key, in the order of keys. Callback may not
         // execute at all if there's a server error.
         //
         // NOTE: Implementations and filters are guaranteed that
         //   - len(keys) > 0
         //   - all keys are Valid, !Incomplete, and in the current namespace
         //   - none keys of the keys are 'special' (use a kind prefixed with '__')
         //   - cb is not nil
         DeleteMulti(keys []*Key, cb DeleteMultiCB) error
 
         // Testable returns the Testable interface for the implementation, or nil if
         // there is none.
         Testable() Testable
 }