datastore: variadic Get, Put, Exists, Delete.

service/datastore/interface.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 datastore
 
 import (
         "golang.org/x/net/context"
 )
 
@@ skipping 150 matching lines @@
         // Does a Get for this key and returns true iff it exists. Will only return
         // an error if it's not ErrNoSuchEntity. This is slightly more efficient
         // than using Get directly, because it uses the underlying RawInterface to
         // avoid some reflection and copies.
         Exists(k *Key) (bool, error)
 
         // Does a GetMulti for thes keys and returns true iff they exist. Will only
         // return an error if it's not ErrNoSuchEntity. This is slightly more efficient
         // than using Get directly, because it uses the underlying RawInterface to
         // avoid some reflection and copies.
-        ExistsMulti(k []*Key) (BoolList, error)
+        //
+        // If an error is encountered, the returned error will be a MultiError whose
+        // error index corresponds to the key for which the error was encountered.
+        ExistsMulti(k ...*Key) (BoolList, error)
 
-        // Get retrieves a single object from the datastore
+        // Get retrieves objects from the datastore.
         //
-        // dst must be one of:
-        //   - *S where S is a struct
-        //   - *P where *P is a concrete type implementing PropertyLoadSaver
-        Get(dst interface{}) error
-
-        // Put inserts a single object into the datastore
+        // Each element in dst must be one of:
+        //      - *S where S is a struct
+        //      - *P where *P is a concrete type implementing PropertyLoadSaver
+        //      - []S or []*S where S is a struct
+        //      - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
+        //      - []I where I is some interface type. Each element of the slice must
+        //        be non-nil, and its underlying type must be either *S or *P.
         //
-        // src must be one of:
-        //   - *S where S is a struct
-        //   - *P where *P is a concrete type implementing PropertyLoadSaver
+        // If an error is encountered, the returned error value will depend on the
+        // input arguments. If one argument is supplied, the result will be the
+        // encountered error type. If multiple arguments are supplied, the result will
+        // be a MultiError whose error index corresponds to the argument in which the
+        // error was encountered.
         //
-        // A *Key will be extracted from src via KeyForObj. If
-        // extractedKey.Incomplete() is true, then Put will write the resolved (i.e.
-        // automatic datastore-populated) *Key back to src.
-        Put(src interface{}) error
-
-        // Delete removes an item from the datastore.
-        Delete(key *Key) error
+        // If a dst argument is a slice, its error type will be a MultiError. Note
+        // that in the scenario where multiple slices are provided, this will return a
+        // return a MultiError containing a nexted MultiError for each slice argument.
+        Get(dst ...interface{}) error
 
         // GetMulti retrieves items from the datastore.
         //
         // dst must be one of:
         //   - []S or []*S where S is a struct
         //   - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
         //   - []I where I is some interface type. Each element of the slice must
         //     be non-nil, and its underlying type must be either *S or *P.
+        //
+        // NOTE: GetMulti is obsolete. The vararg-accepting Get should be used
+        // instead. This is left for backwards compatibility, but will be removed from
+        // this interface at some point in the future.

[iannucci, 2016/05/25 17:36:47]

as in: right after this lands and we refactor luci-go/infra?

         GetMulti(dst interface{}) error
 
+        // Put inserts a single object into the datastore
+        //
+        // src must be one of:
+        //      - *S where S is a struct
+        //      - *P where *P is a concrete type implementing PropertyLoadSaver
+        //      - []S or []*S where S is a struct
+        //      - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
+        //      - []I where i is some interface type. Each elemet of the slice must
+        //        be non-nil, and its underlying type must be either *S or *P.
+        //
+        // A *Key will be extracted from src via KeyForObj. If
+        // extractedKey.Incomplete() is true, then Put will write the resolved (i.e.
+        // automatic datastore-populated) *Key back to src.
+        //
+        // If an error is encountered, the returned error value will depend on the
+        // input arguments. If one argument is supplied, the result will be the
+        // encountered error type. If multiple arguments are supplied, the result will
+        // be a MultiError whose error index corresponds to the argument in which the
+        // error was encountered.
+        //
+        // If a src argument is a slice, its error type will be a MultiError. Note
+        // that in the scenario where multiple slices are provided, this will return a
+        // return a MultiError containing a nexted MultiError for each slice argument.
+        Put(src ...interface{}) error
+
         // PutMulti writes items to the datastore.
         //
         // src must be one of:
-        //   - []S or []*S where S is a struct
-        //   - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
-        //   - []I where i is some interface type. Each elemet of the slice must
-        //     be non-nil, and its underlying type must be either *S or *P.
+        //      - []S or []*S where S is a struct
+        //      - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
+        //      - []I where i is some interface type. Each elemet of the slice must
+        //        be non-nil, and its underlying type must be either *S or *P.
         //
         // If items in src resolve to Incomplete keys, PutMulti will write the
         // resolved keys back to the items in src.
+        //
+        // NOTE: PutMulti is obsolete. The vararg-accepting Put should be used
+        // instead. This is left for backwards compatibility, but will be removed from
+        // this interface at some point in the future.
         PutMulti(src interface{}) error
 
+        // Delete removes the supplied keys from the datastore.
+        //
+        // If an error is encountered, the returned error value will depend on the
+        // input arguments. If one argument is supplied, the result will be the
+        // encountered error type. If multiple arguments are supplied, the result will
+        // be a MultiError whose error index corresponds to the argument in which the
+        // error was encountered.
+        Delete(key *Key) error
+
         // DeleteMulti removes items from the datastore.
-        DeleteMulti(keys []*Key) error
+        //
+        // If an error is encountered, the returned error will be a MultiError whose
+        // error index corresponds to the key for which the error was encountered.
+        DeleteMulti(keys ...*Key) error

[iannucci, 2016/05/25 17:36:47]

do you plan to reconcile the Delete interface with the Put/Get interface? I'm
not sure I like the discrepancy :/

Why not deprecate DeleteMulti and make Delete take ...*Key?

Why did we decide against making delete also take ...interface{} where those
things can be exactly the same objects that we passed to Put/Get (and extract a
*Key using the same mechanism, assuming that the object isn't actually a *Key
itself)? I remember talking about it, but I don't remember the outcome.

 
         // Testable returns the Testable interface for the implementation, or nil if
         // there is none.
         Testable() Testable
 
         // Raw returns the underlying RawInterface. The Interface and RawInterface may
         // be used interchangably; there's no danger of interleaving access to the
         // datastore via the two.
         Raw() RawInterface
 }