disk_cache.h revision bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Defines the public interface of the disk cache. For more details see 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// http://dev.chromium.org/developers/design-documents/network-stack/disk-cache 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef NET_DISK_CACHE_DISK_CACHE_H_ 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define NET_DISK_CACHE_DISK_CACHE_H_ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string> 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <vector> 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h" 15eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "base/time/time.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/cache_type.h" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/completion_callback.h" 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_export.h" 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base { 212a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)class FilePath; 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class MessageLoopProxy; 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace net { 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class IOBuffer; 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NetLog; 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace disk_cache { 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Entry; 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Backend; 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Returns an instance of a Backend of the given |type|. |path| points to a 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// folder where the cached data will be stored (if appropriate). This cache 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// instance must be the only object that will be reading or writing files to 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// that folder. The returned object should be deleted when not needed anymore. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// If |force| is true, and there is a problem with the cache initialization, the 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// files will be deleted and a new set will be created. |max_bytes| is the 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// maximum size the cache can grow to. If zero is passed in as |max_bytes|, the 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// cache will determine the value to use. |thread| can be used to perform IO 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// operations if a dedicated thread is required; a valid value is expected for 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// any backend that performs operations on a disk. The returned pointer can be 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// NULL if a fatal error is found. The actual return value of the function is a 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// net error code. If this function returns ERR_IO_PENDING, the |callback| will 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// be invoked when a backend is available or a fatal error condition is reached. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The pointer to receive the |backend| must remain valid until the operation 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// completes (the callback is notified). 502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)NET_EXPORT int CreateCacheBackend(net::CacheType type, 51a93a17c8d99d686bd4a1511e5504e5e6cc9fcadfTorne (Richard Coles) net::BackendType backend_type, 522a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) const base::FilePath& path, 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int max_bytes, bool force, 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) base::MessageLoopProxy* thread, 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) net::NetLog* net_log, Backend** backend, 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const net::CompletionCallback& callback); 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The root interface for a disk cache instance. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT Backend { 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef net::CompletionCallback CompletionCallback; 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If the backend is destroyed when there are operations in progress (any 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback that has not been invoked yet), this method cancels said 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // operations so the callbacks are not invoked, possibly leaving the work 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // half way (for instance, dooming just a few entries). Note that pending IO 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // for a given Entry (as opposed to the Backend) will still generate a 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback from within this method. 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~Backend() {} 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the type of this cache. 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual net::CacheType GetCacheType() const = 0; 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the number of entries in the cache. 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int32 GetEntryCount() const = 0; 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Opens an existing entry. Upon success, |entry| holds a pointer to an Entry 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // object representing the specified disk cache entry. When the entry pointer 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is no longer needed, its Close method should be called. The return value is 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // a net error code. If this method returns ERR_IO_PENDING, the |callback| 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // will be invoked when the entry is available. The pointer to receive the 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |entry| must remain valid until the operation completes. 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int OpenEntry(const std::string& key, Entry** entry, 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Creates a new entry. Upon success, the out param holds a pointer to an 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Entry object representing the newly created disk cache entry. When the 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entry pointer is no longer needed, its Close method should be called. The 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // return value is a net error code. If this method returns ERR_IO_PENDING, 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the |callback| will be invoked when the entry is available. The pointer to 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // receive the |entry| must remain valid until the operation completes. 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int CreateEntry(const std::string& key, Entry** entry, 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Marks the entry, specified by the given key, for deletion. The return value 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is a net error code. If this method returns ERR_IO_PENDING, the |callback| 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // will be invoked after the entry is doomed. 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int DoomEntry(const std::string& key, 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Marks all entries for deletion. The return value is a net error code. If 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this method returns ERR_IO_PENDING, the |callback| will be invoked when the 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // operation completes. 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int DoomAllEntries(const CompletionCallback& callback) = 0; 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Marks a range of entries for deletion. This supports unbounded deletes in 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // either direction by using null Time values for either argument. The return 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // value is a net error code. If this method returns ERR_IO_PENDING, the 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |callback| will be invoked when the operation completes. 1102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) virtual int DoomEntriesBetween(base::Time initial_time, 1112a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) base::Time end_time, 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Marks all entries accessed since |initial_time| for deletion. The return 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // value is a net error code. If this method returns ERR_IO_PENDING, the 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |callback| will be invoked when the operation completes. 1172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) virtual int DoomEntriesSince(base::Time initial_time, 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Enumerates the cache. Initialize |iter| to NULL before calling this method 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the first time. That will cause the enumeration to start at the head of 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the cache. For subsequent calls, pass the same |iter| pointer again without 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // changing its value. This method returns ERR_FAILED when there are no more 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entries to enumerate. When the entry pointer is no longer needed, its 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Close method should be called. The return value is a net error code. If 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this method returns ERR_IO_PENDING, the |callback| will be invoked when the 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |next_entry| is available. The pointer to receive the |next_entry| must 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // remain valid until the operation completes. 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NOTE: This method does not modify the last_used field of the entry, and 1312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // therefore it does not impact the eviction ranking of the entry. However, 1322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // an enumeration will go through all entries on the cache only if the cache 1332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // is not modified while the enumeration is taking place. Significantly 1342a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // altering the entry pointed by |iter| (for example, deleting the entry) will 1352a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // invalidate |iter|. Performing operations on an entry that modify the entry 1362a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // may result in loops in the iteration, skipped entries or similar. 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int OpenNextEntry(void** iter, Entry** next_entry, 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Releases iter without returning the next entry. Whenever OpenNextEntry() 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // returns true, but the caller is not interested in continuing the 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // enumeration by calling OpenNextEntry() again, the enumeration must be 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // ended by calling this method with iter returned by OpenNextEntry(). 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void EndEnumeration(void** iter) = 0; 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Return a list of cache statistics. 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void GetStats( 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::vector<std::pair<std::string, std::string> >* stats) = 0; 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Called whenever an external cache in the system reuses the resource 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // referred to by |key|. 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void OnExternalCacheHit(const std::string& key) = 0; 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This interface represents an entry in the disk cache. 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT Entry { 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef net::CompletionCallback CompletionCallback; 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef net::IOBuffer IOBuffer; 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Marks this cache entry for deletion. 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void Doom() = 0; 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Releases this entry. Calling this method does not cancel pending IO 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // operations on this entry. Even after the last reference to this object has 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // been released, pending completion callbacks may be invoked. 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void Close() = 0; 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the key associated with this cache entry. 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual std::string GetKey() const = 0; 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the time when this cache entry was last used. 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual base::Time GetLastUsed() const = 0; 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the time when this cache entry was last modified. 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual base::Time GetLastModified() const = 0; 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the size of the cache data with the given index. 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int32 GetDataSize(int index) const = 0; 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1812a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Copies cached data into the given buffer of length |buf_len|. Returns the 1822a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // number of bytes read or a network error code. If this function returns 1832a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // ERR_IO_PENDING, the completion callback will be called on the current 1842a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // thread when the operation completes, and a reference to |buf| will be 1852a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // retained until the callback is called. Note that as long as the function 1862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // does not complete immediately, the callback will always be invoked, even 1872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // after Close has been called; in other words, the caller may close this 1882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // entry without having to wait for all the callbacks, and still rely on the 1892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // cleanup performed from the callback code. 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int ReadData(int index, int offset, IOBuffer* buf, int buf_len, 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Copies data from the given buffer of length |buf_len| into the cache. 1942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Returns the number of bytes written or a network error code. If this 1952a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // function returns ERR_IO_PENDING, the completion callback will be called 1962a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // on the current thread when the operation completes, and a reference to 1972a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // |buf| will be retained until the callback is called. Note that as long as 1982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // the function does not complete immediately, the callback will always be 1992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // invoked, even after Close has been called; in other words, the caller may 2002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // close this entry without having to wait for all the callbacks, and still 2012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // rely on the cleanup performed from the callback code. 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If truncate is true, this call will truncate the stored data at the end of 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // what we are writing here. 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int WriteData(int index, int offset, IOBuffer* buf, int buf_len, 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback, 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool truncate) = 0; 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Sparse entries support: 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // A Backend implementation can support sparse entries, so the cache keeps 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // track of which parts of the entry have been written before. The backend 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // will never return data that was not written previously, so reading from 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // such region will return 0 bytes read (or actually the number of bytes read 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // before reaching that region). 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // There are only two streams for sparse entries: a regular control stream 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // (index 0) that must be accessed through the regular API (ReadData and 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // WriteData), and one sparse stream that must me accessed through the sparse- 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // aware API that follows. Calling a non-sparse aware method with an index 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // argument other than 0 is a mistake that results in implementation specific 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // behavior. Using a sparse-aware method with an entry that was not stored 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // using the same API, or with a backend that doesn't support sparse entries 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // will return ERR_CACHE_OPERATION_NOT_SUPPORTED. 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The storage granularity of the implementation should be at least 1 KB. In 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // other words, storing less than 1 KB may result in an implementation 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // dropping the data completely, and writing at offsets not aligned with 1 KB, 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // or with lengths not a multiple of 1 KB may result in the first or last part 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // of the data being discarded. However, two consecutive writes should not 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // result in a hole in between the two parts as long as they are sequential 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // (the second one starts where the first one ended), and there is no other 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // write between them. 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The Backend implementation is free to evict any range from the cache at any 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // moment, so in practice, the previously stated granularity of 1 KB is not 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // as bad as it sounds. 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The sparse methods don't support multiple simultaneous IO operations to the 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // same physical entry, so in practice a single object should be instantiated 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // for a given key at any given time. Once an operation has been issued, the 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // caller should wait until it completes before starting another one. This 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // requirement includes the case when an entry is closed while some operation 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is in progress and another object is instantiated; any IO operation will 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // fail while the previous operation is still in-flight. In order to deal with 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this requirement, the caller could either wait until the operation 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // completes before closing the entry, or call CancelSparseIO() before closing 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the entry, and call ReadyForSparseIO() on the new entry and wait for the 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback before issuing new operations. 2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Behaves like ReadData() except that this method is used to access sparse 2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entries. 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int ReadSparseData(int64 offset, IOBuffer* buf, int buf_len, 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Behaves like WriteData() except that this method is used to access sparse 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entries. |truncate| is not part of this interface because a sparse entry 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is not expected to be reused with new data. To delete the old data and 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // start again, or to reduce the total size of the stream data (which implies 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // that the content has changed), the whole entry should be doomed and 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // re-created. 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int WriteSparseData(int64 offset, IOBuffer* buf, int buf_len, 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns information about the currently stored portion of a sparse entry. 2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |offset| and |len| describe a particular range that should be scanned to 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // find out if it is stored or not. |start| will contain the offset of the 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // first byte that is stored within this range, and the return value is the 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // minimum number of consecutive stored bytes. Note that it is possible that 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this entry has stored more than the returned value. This method returns a 2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // net error code whenever the request cannot be completed successfully. If 2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this method returns ERR_IO_PENDING, the |callback| will be invoked when the 2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // operation completes, and |start| must remain valid until that point. 2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int GetAvailableRange(int64 offset, int len, int64* start, 2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback) = 0; 2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns true if this entry could be a sparse entry or false otherwise. This 2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is a quick test that may return true even if the entry is not really 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // sparse. This method doesn't modify the state of this entry (it will not 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // create sparse tracking data). GetAvailableRange or ReadSparseData can be 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // used to perform a definitive test of whether an existing entry is sparse or 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not, but that method may modify the current state of the entry (making it 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // sparse, for instance). The purpose of this method is to test an existing 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entry, but without generating actual IO to perform a thorough check. 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool CouldBeSparse() const = 0; 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Cancels any pending sparse IO operation (if any). The completion callback 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // of the operation in question will still be called when the operation 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // finishes, but the operation will finish sooner when this method is used. 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void CancelSparseIO() = 0; 2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns OK if this entry can be used immediately. If that is not the 2925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // case, returns ERR_IO_PENDING and invokes the provided callback when this 2935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entry is ready to use. This method always returns OK for non-sparse 2945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // entries, and returns ERR_IO_PENDING when a previous operation was cancelled 2955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // (by calling CancelSparseIO), but the cache is still busy with it. If there 2965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is a pending operation that has not been cancelled, this method will return 2975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // OK although another IO operation cannot be issued at this time; in this 2985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // case the caller should just wait for the regular callback to be invoked 2995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // instead of using this method to provide another callback. 3005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 3015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Note that CancelSparseIO may have been called on another instance of this 3025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // object that refers to the same physical disk entry. 3035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Note: This method is deprecated. 3045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int ReadyForSparseIO(const CompletionCallback& callback) = 0; 3055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) protected: 3075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~Entry() {} 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 310bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdochstruct EntryDeleter { 311bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch void operator()(Entry* entry) { 312bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch // Note that |entry| is ref-counted. 313bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch entry->Close(); 314bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch } 315bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch}; 316bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch 317bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch// Automatically closes an entry when it goes out of scope. 318bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdochtypedef scoped_ptr<Entry, EntryDeleter> ScopedEntryPtr; 319bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch 3205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace disk_cache 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // NET_DISK_CACHE_DISK_CACHE_H_ 323