X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/75e196b201be758ffb857c3f2d33847e8cca0d18..a6d2f88debdfa7bc390b63c1f18a0541987ae0b8:/services/keepstore/volume.go

diff --git a/services/keepstore/volume.go b/services/keepstore/volume.go
index cdaec92326..8ae6660fd4 100644
--- a/services/keepstore/volume.go
+++ b/services/keepstore/volume.go
@@ -10,17 +10,14 @@ import (
 // for example, a single mounted disk, a RAID array, an Amazon S3 volume,
 // etc.
 type Volume interface {
-	// Get a block. IFF the returned error is nil, the caller must
-	// put the returned slice back into the buffer pool when it's
-	// finished with it. (Otherwise, the buffer pool will be
-	// depleted and eventually -- when all available buffers are
-	// used and not returned -- operations will reach deadlock.)
+	// Get a block: copy the block data into buf, and return the
+	// number of bytes copied.
 	//
 	// loc is guaranteed to consist of 32 or more lowercase hex
 	// digits.
 	//
-	// Get should not verify the integrity of the returned data:
-	// it should just return whatever was found in its backing
+	// Get should not verify the integrity of the data: it should
+	// just return whatever was found in its backing
 	// store. (Integrity checking is the caller's responsibility.)
 	//
 	// If an error is encountered that prevents it from
@@ -36,10 +33,12 @@ type Volume interface {
 	// access log if the block is not found on any other volumes
 	// either).
 	//
-	// If the data in the backing store is bigger than BLOCKSIZE,
-	// Get is permitted to return an error without reading any of
-	// the data.
-	Get(loc string) ([]byte, error)
+	// If the data in the backing store is bigger than len(buf),
+	// then Get is permitted to return an error without reading
+	// any of the data.
+	//
+	// len(buf) will not exceed BlockSize.
+	Get(loc string, buf []byte) (int, error)
 
 	// Compare the given data with the stored data (i.e., what Get
 	// would return). If equal, return nil. If not, return
@@ -52,7 +51,7 @@ type Volume interface {
 	//
 	// loc is as described in Get.
 	//
-	// len(block) is guaranteed to be between 0 and BLOCKSIZE.
+	// len(block) is guaranteed to be between 0 and BlockSize.
 	//
 	// If a block is already stored under the same name (loc) with
 	// different content, Put must either overwrite the existing
@@ -144,20 +143,21 @@ type Volume interface {
 	// particular order.
 	IndexTo(prefix string, writer io.Writer) error
 
-	// Delete deletes the block data from the underlying storage
-	// device.
+	// Trash moves the block data from the underlying storage
+	// device to trash area. The block then stays in trash for
+	// -trash-lifetime interval before it is actually deleted.
 	//
 	// loc is as described in Get.
 	//
 	// If the timestamp for the given locator is newer than
-	// blob_signature_ttl, Delete must not delete the data.
+	// blobSignatureTTL, Trash must not trash the data.
 	//
-	// If a Delete operation overlaps with any Touch or Put
+	// If a Trash operation overlaps with any Touch or Put
 	// operations on the same locator, the implementation must
 	// ensure one of the following outcomes:
 	//
 	//   - Touch and Put return a non-nil error, or
-	//   - Delete does not delete the block, or
+	//   - Trash does not trash the block, or
 	//   - Both of the above.
 	//
 	// If it is possible for the storage device to be accessed by
@@ -171,9 +171,12 @@ type Volume interface {
 	// reliably or fail outright.
 	//
 	// Corollary: A successful Touch or Put guarantees a block
-	// will not be deleted for at least blob_signature_ttl
+	// will not be trashed for at least blobSignatureTTL
 	// seconds.
-	Delete(loc string) error
+	Trash(loc string) error
+
+	// Untrash moves block from trash back into store
+	Untrash(loc string) error
 
 	// Status returns a *VolumeStatus representing the current
 	// in-use and available storage capacity and an
@@ -195,6 +198,15 @@ type Volume interface {
 	// will fail because it is full, but Mtime or Delete can
 	// succeed -- then Writable should return false.
 	Writable() bool
+
+	// Replication returns the storage redundancy of the
+	// underlying device. It will be passed on to clients in
+	// responses to PUT requests.
+	Replication() int
+
+	// EmptyTrash looks for trashed blocks that exceeded trashLifetime
+	// and deletes them from the volume.
+	EmptyTrash()
 }
 
 // A VolumeManager tells callers which volumes can read, which volumes