datastore: variadic Get, Put, Exists, Delete.

service/datastore/interface.go

Index: service/datastore/interface.go
diff --git a/service/datastore/interface.go b/service/datastore/interface.go
index c70dd53c54095804b6f88826e452f27f4707a14a..a8b131cda6d21041c2136a665b56d0e97428b552 100644
--- a/service/datastore/interface.go
+++ b/service/datastore/interface.go
@@ -168,28 +168,31 @@ type Interface interface {
 	// 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)
-
-	// Get retrieves a single object 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
+	// 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)
 
-	// Put inserts a single object into the datastore
+	// Get retrieves objects from the datastore.
 	//
-	// src must be one of:
-	//   - *S where S is a struct
-	//   - *P where *P is a concrete type implementing PropertyLoadSaver
+	// 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.
 	//
-	// 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 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 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.
 	//
@@ -198,22 +201,67 @@ type Interface interface {
 	//   - []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.