Disk cache: Interface for the sparse cache support....

net/disk_cache/disk_cache.h

 // Copyright (c) 2006-2008 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.
 
 // Defines the public interface of the disk cache. For more details see
 // http://dev.chromium.org/developers/design-documents/disk-cache
 
 #ifndef NET_DISK_CACHE_DISK_CACHE_H_
 #define NET_DISK_CACHE_DISK_CACHE_H_
 
@@ skipping 136 matching lines @@
   // Note that the callback will be invoked in any case, even after Close has
   // been called; in other words, the caller may close this entry without
   // having to wait for all the callbacks, and still rely on the cleanup
   // performed from the callback code.
   // If truncate is true, this call will truncate the stored data at the end of
   // what we are writing here.
   virtual int WriteData(int index, int offset, net::IOBuffer* buf, int buf_len,
                         net::CompletionCallback* completion_callback,
                         bool truncate) = 0;
 
+  // Sparse entries support:
+  //
+  // A Backend implementation can support sparse entries, so the cache keeps
+  // track of which parts of the entry have been written before. The backend
+  // will never return data that was not written previously, so reading from
+  // such region will return 0 bytes read (or actually the number of bytes read
+  // before reaching that region).
+  //
+  // There are only two streams for sparse entries: a regular control stream
+  // (index 0) that must be accessed through the regular API (ReadData and
+  // WriteData), and one sparse stream that must me accessed through the sparse-
+  // aware API that follows. Calling a non-sparse aware method with an index
+  // argument other than 0 is a mistake that results in implementation specific
+  // behavior. Using a sparse-aware method with an entry that was not stored
+  // using the same API, or with a backend that doesn't support sparse entries
+  // will return ERR_CACHE_INVALID_REQUEST.
+  //
+  // The storage granularity of the implementation should be at least 1 KB. In
+  // other words, storing less than 1 KB may result in an implementation
+  // dropping the data completely, and writing at offsets not aligned with 1 KB,
+  // or with lengths not a multiple of 1 KB may result in the first or last part
+  // of the data being discarded. However, two consecutive writes should not
+  // result in a hole in between the two parts as long as they are sequential
+  // (the second one starts where the first one ended), and there is no other
+  // write between them.
+  //
+  // The Backend implementation is free to evict any range from the cache at any
+  // moment, so in practice, the previously stated granularity of 1 KB is not
+  // as bad as it sounds.
+
+  // Behaves like ReadData() except that this method is used to access sparse
+  // entries.
+  virtual int ReadSparseData(int64 offset, net::IOBuffer* buf, int buf_len,
+                             net::CompletionCallback* completion_callback) = 0;
+
+  // Behaves like WriteData() except that this method is used to access sparse
+  // entries. |truncate| is not part of this interface because a sparse entry
+  // is not expected to be reused with new data. To delete the old data and
+  // start again, or to reduce the total size of the stream data (which implies
+  // that the content has changed), the whole entry should be doomed and
+  // re-created.
+  virtual int WriteSparseData(int64 offset, net::IOBuffer* buf, int buf_len,
+                              net::CompletionCallback* completion_callback) = 0;
+
+  // Returns information about the currently stored portion of a sparse entry.
+  // |offset| and |len| describe a particular range that should be scanned to
+  // find out if it is stored or not. |start| will contain the offset of the
+  // first byte that is stored within this range, and the return value is the
+  // minimum number of consecutive stored bytes. Note that it is possible that
+  // this entry has stored more than the returned value. This method returns a
+  // net error code whenever the request cannot be completed successfully.
+  virtual int GetAvailableRange(int64 offset, int len, int64* start) = 0;
+
  protected:
   virtual ~Entry() {}
 };
 
 }  // namespace disk_cache
 
 #endif  // NET_DISK_CACHE_DISK_CACHE_H_