1c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// Copyright (c) 2006-2010 The Chromium Authors. All rights reserved. 2c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Use of this source code is governed by a BSD-style license that can be 3c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// found in the LICENSE file. 4c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 5c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Defines the public interface of the disk cache. For more details see 6c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// http://dev.chromium.org/developers/design-documents/disk-cache 7c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 8c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#ifndef NET_DISK_CACHE_DISK_CACHE_H_ 9c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#define NET_DISK_CACHE_DISK_CACHE_H_ 103345a6884c488ff3a535c2c9acdd33d74b37e311Iain Merrick#pragma once 11c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 12c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include <string> 13c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include <vector> 14c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 15c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include "base/basictypes.h" 16c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include "base/time.h" 17c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include "net/base/cache_type.h" 18c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include "net/base/completion_callback.h" 19c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 20c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottclass FilePath; 21c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 22c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdochnamespace base { 23c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdochclass MessageLoopProxy; 24c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch} 25c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch 26c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottnamespace net { 27c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottclass IOBuffer; 283f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsenclass NetLog; 29c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott} 30c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 31c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottnamespace disk_cache { 32c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 33c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottclass Entry; 34c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottclass Backend; 35c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scotttypedef net::CompletionCallback CompletionCallback; 36c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 37c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Returns an instance of a Backend of the given |type|. |path| points to a 38c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// folder where the cached data will be stored (if appropriate). This cache 39c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// instance must be the only object that will be reading or writing files to 40c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// that folder. The returned object should be deleted when not needed anymore. 41c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// If |force| is true, and there is a problem with the cache initialization, the 42c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// files will be deleted and a new set will be created. |max_bytes| is the 43c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// maximum size the cache can grow to. If zero is passed in as |max_bytes|, the 44c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// cache will determine the value to use. |thread| can be used to perform IO 45c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// operations if a dedicated thread is required; a valid value is expected for 46c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// any backend that performs operations on a disk. The returned pointer can be 47c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// NULL if a fatal error is found. The actual return value of the function is a 48c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// net error code. If this function returns ERR_IO_PENDING, the |callback| will 49c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// be invoked when a backend is available or a fatal error condition is reached. 50c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// The pointer to receive the |backend| must remain valid until the operation 51c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch// completes (the callback is notified). 52c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottint CreateCacheBackend(net::CacheType type, const FilePath& path, int max_bytes, 53c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch bool force, base::MessageLoopProxy* thread, 543f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen net::NetLog* net_log, Backend** backend, 553f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen CompletionCallback* callback); 56c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 57c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// The root interface for a disk cache instance. 58c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottclass Backend { 59c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 60c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // If the backend is destroyed when there are operations in progress (any 61c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // callback that has not been invoked yet), this method cancels said 62c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // operations so the callbacks are not invoked, possibly leaving the work 63c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // half way (for instance, dooming just a few entries). Note that pending IO 64c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // for a given Entry (as opposed to the Backend) will still generate a 65c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // callback from within this method. 66c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual ~Backend() {} 67c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 68c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns the number of entries in the cache. 69c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int32 GetEntryCount() const = 0; 70c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 71c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Opens an existing entry. Upon success, |entry| holds a pointer to an Entry 72c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // object representing the specified disk cache entry. When the entry pointer 73c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // is no longer needed, its Close method should be called. The return value is 74c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // a net error code. If this method returns ERR_IO_PENDING, the |callback| 75c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // will be invoked when the entry is available. The pointer to receive the 76c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // |entry| must remain valid until the operation completes. 77c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int OpenEntry(const std::string& key, Entry** entry, 78c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 79c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 80c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Creates a new entry. Upon success, the out param holds a pointer to an 81c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Entry object representing the newly created disk cache entry. When the 82c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // entry pointer is no longer needed, its Close method should be called. The 83c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // return value is a net error code. If this method returns ERR_IO_PENDING, 84c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // the |callback| will be invoked when the entry is available. The pointer to 85c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // receive the |entry| must remain valid until the operation completes. 86c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int CreateEntry(const std::string& key, Entry** entry, 87c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 88c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 89c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Marks the entry, specified by the given key, for deletion. The return value 90c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // is a net error code. If this method returns ERR_IO_PENDING, the |callback| 91c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // will be invoked after the entry is doomed. 92c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int DoomEntry(const std::string& key, 93c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 94c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 95c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Marks all entries for deletion. The return value is a net error code. If 96c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // this method returns ERR_IO_PENDING, the |callback| will be invoked when the 97c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // operation completes. 98c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int DoomAllEntries(CompletionCallback* callback) = 0; 99c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 100c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Marks a range of entries for deletion. This supports unbounded deletes in 101c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // either direction by using null Time values for either argument. The return 102c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // value is a net error code. If this method returns ERR_IO_PENDING, the 103c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // |callback| will be invoked when the operation completes. 104c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int DoomEntriesBetween(const base::Time initial_time, 105c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott const base::Time end_time, 106c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 107c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 108c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Marks all entries accessed since |initial_time| for deletion. The return 109c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // value is a net error code. If this method returns ERR_IO_PENDING, the 110c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // |callback| will be invoked when the operation completes. 111c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int DoomEntriesSince(const base::Time initial_time, 112c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 113c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 114c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Enumerates the cache. Initialize |iter| to NULL before calling this method 115c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // the first time. That will cause the enumeration to start at the head of 116c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // the cache. For subsequent calls, pass the same |iter| pointer again without 117c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // changing its value. This method returns ERR_FAILED when there are no more 118c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // entries to enumerate. When the entry pointer is no longer needed, its 119c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Close method should be called. The return value is a net error code. If 120c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // this method returns ERR_IO_PENDING, the |callback| will be invoked when the 121c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // |next_entry| is available. The pointer to receive the |next_entry| must 122c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // remain valid until the operation completes. 123c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 124c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // NOTE: This method does not modify the last_used field of the entry, and 125c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // therefore it does not impact the eviction ranking of the entry. 126c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int OpenNextEntry(void** iter, Entry** next_entry, 127c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 128c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 129c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Releases iter without returning the next entry. Whenever OpenNextEntry() 130c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // returns true, but the caller is not interested in continuing the 131c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // enumeration by calling OpenNextEntry() again, the enumeration must be 132c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // ended by calling this method with iter returned by OpenNextEntry(). 133c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void EndEnumeration(void** iter) = 0; 134c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 135c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Return a list of cache statistics. 136c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void GetStats( 137c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott std::vector<std::pair<std::string, std::string> >* stats) = 0; 138c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott}; 139c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 140c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// This interface represents an entry in the disk cache. 141c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottclass Entry { 142c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 143c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Marks this cache entry for deletion. 144c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Doom() = 0; 145c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 146c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Releases this entry. Calling this method does not cancel pending IO 147c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // operations on this entry. Even after the last reference to this object has 148c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // been released, pending completion callbacks may be invoked. 149c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Close() = 0; 150c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 151c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns the key associated with this cache entry. 152c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual std::string GetKey() const = 0; 153c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 154c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns the time when this cache entry was last used. 155c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual base::Time GetLastUsed() const = 0; 156c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 157c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns the time when this cache entry was last modified. 158c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual base::Time GetLastModified() const = 0; 159c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 160c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns the size of the cache data with the given index. 161c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int32 GetDataSize(int index) const = 0; 162c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 163c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Copies cache data into the given buffer of length |buf_len|. If 164c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // completion_callback is null, then this call blocks until the read 165c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // operation is complete. Otherwise, completion_callback will be 166c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // called on the current thread once the read completes. Returns the 167c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // number of bytes read or a network error code. If a completion callback is 168c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // provided then it will be called if this function returns ERR_IO_PENDING, 169c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // and a reference to |buf| will be retained until the callback is called. 170c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Note that the callback will be invoked in any case, even after Close has 171c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // been called; in other words, the caller may close this entry without 172c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // having to wait for all the callbacks, and still rely on the cleanup 173c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // performed from the callback code. 174c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int ReadData(int index, int offset, net::IOBuffer* buf, int buf_len, 175c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* completion_callback) = 0; 176c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 177c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Copies cache data from the given buffer of length |buf_len|. If 178c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // completion_callback is null, then this call blocks until the write 179c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // operation is complete. Otherwise, completion_callback will be 180c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // called on the current thread once the write completes. Returns the 181c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // number of bytes written or a network error code. If a completion callback 182c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // is provided then it will be called if this function returns ERR_IO_PENDING, 183c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // and a reference to |buf| will be retained until the callback is called. 184c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Note that the callback will be invoked in any case, even after Close has 185c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // been called; in other words, the caller may close this entry without 186c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // having to wait for all the callbacks, and still rely on the cleanup 187c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // performed from the callback code. 188c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // If truncate is true, this call will truncate the stored data at the end of 189c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // what we are writing here. 190c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int WriteData(int index, int offset, net::IOBuffer* buf, int buf_len, 191c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* completion_callback, 192c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott bool truncate) = 0; 193c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 194c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Sparse entries support: 195c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 196c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // A Backend implementation can support sparse entries, so the cache keeps 197c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // track of which parts of the entry have been written before. The backend 198c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // will never return data that was not written previously, so reading from 199c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // such region will return 0 bytes read (or actually the number of bytes read 200c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // before reaching that region). 201c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 202c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // There are only two streams for sparse entries: a regular control stream 203c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // (index 0) that must be accessed through the regular API (ReadData and 204c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // WriteData), and one sparse stream that must me accessed through the sparse- 205c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // aware API that follows. Calling a non-sparse aware method with an index 206c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // argument other than 0 is a mistake that results in implementation specific 207c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // behavior. Using a sparse-aware method with an entry that was not stored 208c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // using the same API, or with a backend that doesn't support sparse entries 209c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // will return ERR_CACHE_OPERATION_NOT_SUPPORTED. 210c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 211c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // The storage granularity of the implementation should be at least 1 KB. In 212c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // other words, storing less than 1 KB may result in an implementation 213c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // dropping the data completely, and writing at offsets not aligned with 1 KB, 214c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // or with lengths not a multiple of 1 KB may result in the first or last part 215c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // of the data being discarded. However, two consecutive writes should not 216c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // result in a hole in between the two parts as long as they are sequential 217c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // (the second one starts where the first one ended), and there is no other 218c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // write between them. 219c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 220c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // The Backend implementation is free to evict any range from the cache at any 221c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // moment, so in practice, the previously stated granularity of 1 KB is not 222c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // as bad as it sounds. 223c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 224c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // The sparse methods don't support multiple simultaneous IO operations to the 225c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // same physical entry, so in practice a single object should be instantiated 226c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // for a given key at any given time. Once an operation has been issued, the 227c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // caller should wait until it completes before starting another one. This 228c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // requirement includes the case when an entry is closed while some operation 229c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // is in progress and another object is instantiated; any IO operation will 230c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // fail while the previous operation is still in-flight. In order to deal with 231c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // this requirement, the caller could either wait until the operation 232c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // completes before closing the entry, or call CancelSparseIO() before closing 233c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // the entry, and call ReadyForSparseIO() on the new entry and wait for the 234c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // callback before issuing new operations. 235c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 236c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Behaves like ReadData() except that this method is used to access sparse 237c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // entries. 238c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int ReadSparseData(int64 offset, net::IOBuffer* buf, int buf_len, 239c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* completion_callback) = 0; 240c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 241c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Behaves like WriteData() except that this method is used to access sparse 242c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // entries. |truncate| is not part of this interface because a sparse entry 243c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // is not expected to be reused with new data. To delete the old data and 244c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // start again, or to reduce the total size of the stream data (which implies 245c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // that the content has changed), the whole entry should be doomed and 246c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // re-created. 247c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int WriteSparseData(int64 offset, net::IOBuffer* buf, int buf_len, 248c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* completion_callback) = 0; 249c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 250c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns information about the currently stored portion of a sparse entry. 251c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // |offset| and |len| describe a particular range that should be scanned to 252c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // find out if it is stored or not. |start| will contain the offset of the 253c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // first byte that is stored within this range, and the return value is the 254c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // minimum number of consecutive stored bytes. Note that it is possible that 255c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // this entry has stored more than the returned value. This method returns a 256c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // net error code whenever the request cannot be completed successfully. If 257c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // this method returns ERR_IO_PENDING, the |callback| will be invoked when the 258c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // operation completes, and |start| must remain valid until that point. 259c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int GetAvailableRange(int64 offset, int len, int64* start, 260c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott CompletionCallback* callback) = 0; 261c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 262c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // Returns true if this entry could be a sparse entry or false otherwise. This 263c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // is a quick test that may return true even if the entry is not really 264c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // sparse. This method doesn't modify the state of this entry (it will not 265c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // create sparse tracking data). GetAvailableRange or ReadSparseData can be 266c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // used to perfom a definitive test of wether an existing entry is sparse or 267c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // not, but that method may modify the current state of the entry (making it 268c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // sparse, for instance). The purpose of this method is to test an existing 269c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch // entry, but without generating actual IO to perform a thorough check. 270c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch virtual bool CouldBeSparse() const = 0; 271c407dc5cd9bdc5668497f21b26b09d988ab439deBen Murdoch 272c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Cancels any pending sparse IO operation (if any). The completion callback 273c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // of the operation in question will still be called when the operation 274c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // finishes, but the operation will finish sooner when this method is used. 275c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void CancelSparseIO() = 0; 276c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 277c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Returns OK if this entry can be used immediately. If that is not the 278c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // case, returns ERR_IO_PENDING and invokes the provided callback when this 279c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // entry is ready to use. This method always returns OK for non-sparse 280c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // entries, and returns ERR_IO_PENDING when a previous operation was cancelled 281c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // (by calling CancelSparseIO), but the cache is still busy with it. If there 282c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // is a pending operation that has not been cancelled, this method will return 283c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // OK although another IO operation cannot be issued at this time; in this 284c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // case the caller should just wait for the regular callback to be invoked 285c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // instead of using this method to provide another callback. 286c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // 287c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Note that CancelSparseIO may have been called on another instance of this 288c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // object that refers to the same physical disk entry. 289c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Note: This method is deprecated. 290c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual int ReadyForSparseIO(CompletionCallback* completion_callback) = 0; 291c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 292c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott protected: 293c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual ~Entry() {} 294c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott}; 295c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 296c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott} // namespace disk_cache 297c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 298c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#endif // NET_DISK_CACHE_DISK_CACHE_H_ 299