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