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