OLD | NEW |
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2012 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/network-stack/disk-cache | 6 // http://dev.chromium.org/developers/design-documents/network-stack/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 |
(...skipping 64 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
75 | 75 |
76 // Returns the number of entries in the cache. | 76 // Returns the number of entries in the cache. |
77 virtual int32 GetEntryCount() const = 0; | 77 virtual int32 GetEntryCount() const = 0; |
78 | 78 |
79 // Opens an existing entry. Upon success, |entry| holds a pointer to an Entry | 79 // Opens an existing entry. Upon success, |entry| holds a pointer to an Entry |
80 // object representing the specified disk cache entry. When the entry pointer | 80 // object representing the specified disk cache entry. When the entry pointer |
81 // is no longer needed, its Close method should be called. The return value is | 81 // is no longer needed, its Close method should be called. The return value is |
82 // a net error code. If this method returns ERR_IO_PENDING, the |callback| | 82 // a net error code. If this method returns ERR_IO_PENDING, the |callback| |
83 // will be invoked when the entry is available. The pointer to receive the | 83 // will be invoked when the entry is available. The pointer to receive the |
84 // |entry| must remain valid until the operation completes. | 84 // |entry| must remain valid until the operation completes. |
85 virtual int OpenEntry(const std::string& key, Entry** entry, | 85 virtual int OpenEntry(const std::string& key, |
| 86 Entry** entry, |
86 const CompletionCallback& callback) = 0; | 87 const CompletionCallback& callback) = 0; |
87 | 88 |
88 // Creates a new entry. Upon success, the out param holds a pointer to an | 89 // Creates a new entry. Upon success, the out param holds a pointer to an |
89 // Entry object representing the newly created disk cache entry. When the | 90 // Entry object representing the newly created disk cache entry. When the |
90 // entry pointer is no longer needed, its Close method should be called. The | 91 // entry pointer is no longer needed, its Close method should be called. The |
91 // return value is a net error code. If this method returns ERR_IO_PENDING, | 92 // return value is a net error code. If this method returns ERR_IO_PENDING, |
92 // the |callback| will be invoked when the entry is available. The pointer to | 93 // the |callback| will be invoked when the entry is available. The pointer to |
93 // receive the |entry| must remain valid until the operation completes. | 94 // receive the |entry| must remain valid until the operation completes. |
94 virtual int CreateEntry(const std::string& key, Entry** entry, | 95 virtual int CreateEntry(const std::string& key, |
| 96 Entry** entry, |
95 const CompletionCallback& callback) = 0; | 97 const CompletionCallback& callback) = 0; |
96 | 98 |
97 // Marks the entry, specified by the given key, for deletion. The return value | 99 // Marks the entry, specified by the given key, for deletion. The return value |
98 // is a net error code. If this method returns ERR_IO_PENDING, the |callback| | 100 // is a net error code. If this method returns ERR_IO_PENDING, the |callback| |
99 // will be invoked after the entry is doomed. | 101 // will be invoked after the entry is doomed. |
100 virtual int DoomEntry(const std::string& key, | 102 virtual int DoomEntry(const std::string& key, |
101 const CompletionCallback& callback) = 0; | 103 const CompletionCallback& callback) = 0; |
102 | 104 |
103 // Marks all entries for deletion. The return value is a net error code. If | 105 // Marks all entries for deletion. The return value is a net error code. If |
104 // this method returns ERR_IO_PENDING, the |callback| will be invoked when the | 106 // this method returns ERR_IO_PENDING, the |callback| will be invoked when the |
(...skipping 24 matching lines...) Expand all Loading... |
129 // |next_entry| is available. The pointer to receive the |next_entry| must | 131 // |next_entry| is available. The pointer to receive the |next_entry| must |
130 // remain valid until the operation completes. | 132 // remain valid until the operation completes. |
131 // | 133 // |
132 // NOTE: This method does not modify the last_used field of the entry, and | 134 // NOTE: This method does not modify the last_used field of the entry, and |
133 // therefore it does not impact the eviction ranking of the entry. However, | 135 // therefore it does not impact the eviction ranking of the entry. However, |
134 // an enumeration will go through all entries on the cache only if the cache | 136 // an enumeration will go through all entries on the cache only if the cache |
135 // is not modified while the enumeration is taking place. Significantly | 137 // is not modified while the enumeration is taking place. Significantly |
136 // altering the entry pointed by |iter| (for example, deleting the entry) will | 138 // altering the entry pointed by |iter| (for example, deleting the entry) will |
137 // invalidate |iter|. Performing operations on an entry that modify the entry | 139 // invalidate |iter|. Performing operations on an entry that modify the entry |
138 // may result in loops in the iteration, skipped entries or similar. | 140 // may result in loops in the iteration, skipped entries or similar. |
139 virtual int OpenNextEntry(void** iter, Entry** next_entry, | 141 virtual int OpenNextEntry(void** iter, |
| 142 Entry** next_entry, |
140 const CompletionCallback& callback) = 0; | 143 const CompletionCallback& callback) = 0; |
141 | 144 |
142 // Releases iter without returning the next entry. Whenever OpenNextEntry() | 145 // Releases iter without returning the next entry. Whenever OpenNextEntry() |
143 // returns true, but the caller is not interested in continuing the | 146 // returns true, but the caller is not interested in continuing the |
144 // enumeration by calling OpenNextEntry() again, the enumeration must be | 147 // enumeration by calling OpenNextEntry() again, the enumeration must be |
145 // ended by calling this method with iter returned by OpenNextEntry(). | 148 // ended by calling this method with iter returned by OpenNextEntry(). |
146 virtual void EndEnumeration(void** iter) = 0; | 149 virtual void EndEnumeration(void** iter) = 0; |
147 | 150 |
148 // Return a list of cache statistics. | 151 // Return a list of cache statistics. |
149 virtual void GetStats( | 152 virtual void GetStats( |
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
182 | 185 |
183 // Copies cached data into the given buffer of length |buf_len|. Returns the | 186 // Copies cached data into the given buffer of length |buf_len|. Returns the |
184 // number of bytes read or a network error code. If this function returns | 187 // number of bytes read or a network error code. If this function returns |
185 // ERR_IO_PENDING, the completion callback will be called on the current | 188 // ERR_IO_PENDING, the completion callback will be called on the current |
186 // thread when the operation completes, and a reference to |buf| will be | 189 // thread when the operation completes, and a reference to |buf| will be |
187 // retained until the callback is called. Note that as long as the function | 190 // retained until the callback is called. Note that as long as the function |
188 // does not complete immediately, the callback will always be invoked, even | 191 // does not complete immediately, the callback will always be invoked, even |
189 // after Close has been called; in other words, the caller may close this | 192 // after Close has been called; in other words, the caller may close this |
190 // entry without having to wait for all the callbacks, and still rely on the | 193 // entry without having to wait for all the callbacks, and still rely on the |
191 // cleanup performed from the callback code. | 194 // cleanup performed from the callback code. |
192 virtual int ReadData(int index, int offset, IOBuffer* buf, int buf_len, | 195 virtual int ReadData(int index, |
| 196 int offset, |
| 197 IOBuffer* buf, |
| 198 int buf_len, |
193 const CompletionCallback& callback) = 0; | 199 const CompletionCallback& callback) = 0; |
194 | 200 |
195 // Copies data from the given buffer of length |buf_len| into the cache. | 201 // Copies data from the given buffer of length |buf_len| into the cache. |
196 // Returns the number of bytes written or a network error code. If this | 202 // Returns the number of bytes written or a network error code. If this |
197 // function returns ERR_IO_PENDING, the completion callback will be called | 203 // function returns ERR_IO_PENDING, the completion callback will be called |
198 // on the current thread when the operation completes, and a reference to | 204 // on the current thread when the operation completes, and a reference to |
199 // |buf| will be retained until the callback is called. Note that as long as | 205 // |buf| will be retained until the callback is called. Note that as long as |
200 // the function does not complete immediately, the callback will always be | 206 // the function does not complete immediately, the callback will always be |
201 // invoked, even after Close has been called; in other words, the caller may | 207 // invoked, even after Close has been called; in other words, the caller may |
202 // close this entry without having to wait for all the callbacks, and still | 208 // close this entry without having to wait for all the callbacks, and still |
203 // rely on the cleanup performed from the callback code. | 209 // rely on the cleanup performed from the callback code. |
204 // If truncate is true, this call will truncate the stored data at the end of | 210 // If truncate is true, this call will truncate the stored data at the end of |
205 // what we are writing here. | 211 // what we are writing here. |
206 virtual int WriteData(int index, int offset, IOBuffer* buf, int buf_len, | 212 virtual int WriteData(int index, |
| 213 int offset, |
| 214 IOBuffer* buf, |
| 215 int buf_len, |
207 const CompletionCallback& callback, | 216 const CompletionCallback& callback, |
208 bool truncate) = 0; | 217 bool truncate) = 0; |
209 | 218 |
210 // Sparse entries support: | 219 // Sparse entries support: |
211 // | 220 // |
212 // A Backend implementation can support sparse entries, so the cache keeps | 221 // A Backend implementation can support sparse entries, so the cache keeps |
213 // track of which parts of the entry have been written before. The backend | 222 // track of which parts of the entry have been written before. The backend |
214 // will never return data that was not written previously, so reading from | 223 // will never return data that was not written previously, so reading from |
215 // such region will return 0 bytes read (or actually the number of bytes read | 224 // such region will return 0 bytes read (or actually the number of bytes read |
216 // before reaching that region). | 225 // before reaching that region). |
(...skipping 27 matching lines...) Expand all Loading... |
244 // requirement includes the case when an entry is closed while some operation | 253 // requirement includes the case when an entry is closed while some operation |
245 // is in progress and another object is instantiated; any IO operation will | 254 // is in progress and another object is instantiated; any IO operation will |
246 // fail while the previous operation is still in-flight. In order to deal with | 255 // fail while the previous operation is still in-flight. In order to deal with |
247 // this requirement, the caller could either wait until the operation | 256 // this requirement, the caller could either wait until the operation |
248 // completes before closing the entry, or call CancelSparseIO() before closing | 257 // completes before closing the entry, or call CancelSparseIO() before closing |
249 // the entry, and call ReadyForSparseIO() on the new entry and wait for the | 258 // the entry, and call ReadyForSparseIO() on the new entry and wait for the |
250 // callback before issuing new operations. | 259 // callback before issuing new operations. |
251 | 260 |
252 // Behaves like ReadData() except that this method is used to access sparse | 261 // Behaves like ReadData() except that this method is used to access sparse |
253 // entries. | 262 // entries. |
254 virtual int ReadSparseData(int64 offset, IOBuffer* buf, int buf_len, | 263 virtual int ReadSparseData(int64 offset, |
| 264 IOBuffer* buf, |
| 265 int buf_len, |
255 const CompletionCallback& callback) = 0; | 266 const CompletionCallback& callback) = 0; |
256 | 267 |
257 // Behaves like WriteData() except that this method is used to access sparse | 268 // Behaves like WriteData() except that this method is used to access sparse |
258 // entries. |truncate| is not part of this interface because a sparse entry | 269 // entries. |truncate| is not part of this interface because a sparse entry |
259 // is not expected to be reused with new data. To delete the old data and | 270 // is not expected to be reused with new data. To delete the old data and |
260 // start again, or to reduce the total size of the stream data (which implies | 271 // start again, or to reduce the total size of the stream data (which implies |
261 // that the content has changed), the whole entry should be doomed and | 272 // that the content has changed), the whole entry should be doomed and |
262 // re-created. | 273 // re-created. |
263 virtual int WriteSparseData(int64 offset, IOBuffer* buf, int buf_len, | 274 virtual int WriteSparseData(int64 offset, |
| 275 IOBuffer* buf, |
| 276 int buf_len, |
264 const CompletionCallback& callback) = 0; | 277 const CompletionCallback& callback) = 0; |
265 | 278 |
266 // Returns information about the currently stored portion of a sparse entry. | 279 // Returns information about the currently stored portion of a sparse entry. |
267 // |offset| and |len| describe a particular range that should be scanned to | 280 // |offset| and |len| describe a particular range that should be scanned to |
268 // find out if it is stored or not. |start| will contain the offset of the | 281 // find out if it is stored or not. |start| will contain the offset of the |
269 // first byte that is stored within this range, and the return value is the | 282 // first byte that is stored within this range, and the return value is the |
270 // minimum number of consecutive stored bytes. Note that it is possible that | 283 // minimum number of consecutive stored bytes. Note that it is possible that |
271 // this entry has stored more than the returned value. This method returns a | 284 // this entry has stored more than the returned value. This method returns a |
272 // net error code whenever the request cannot be completed successfully. If | 285 // net error code whenever the request cannot be completed successfully. If |
273 // this method returns ERR_IO_PENDING, the |callback| will be invoked when the | 286 // this method returns ERR_IO_PENDING, the |callback| will be invoked when the |
274 // operation completes, and |start| must remain valid until that point. | 287 // operation completes, and |start| must remain valid until that point. |
275 virtual int GetAvailableRange(int64 offset, int len, int64* start, | 288 virtual int GetAvailableRange(int64 offset, |
| 289 int len, |
| 290 int64* start, |
276 const CompletionCallback& callback) = 0; | 291 const CompletionCallback& callback) = 0; |
277 | 292 |
278 // Returns true if this entry could be a sparse entry or false otherwise. This | 293 // Returns true if this entry could be a sparse entry or false otherwise. This |
279 // is a quick test that may return true even if the entry is not really | 294 // is a quick test that may return true even if the entry is not really |
280 // sparse. This method doesn't modify the state of this entry (it will not | 295 // sparse. This method doesn't modify the state of this entry (it will not |
281 // create sparse tracking data). GetAvailableRange or ReadSparseData can be | 296 // create sparse tracking data). GetAvailableRange or ReadSparseData can be |
282 // used to perform a definitive test of whether an existing entry is sparse or | 297 // used to perform a definitive test of whether an existing entry is sparse or |
283 // not, but that method may modify the current state of the entry (making it | 298 // not, but that method may modify the current state of the entry (making it |
284 // sparse, for instance). The purpose of this method is to test an existing | 299 // sparse, for instance). The purpose of this method is to test an existing |
285 // entry, but without generating actual IO to perform a thorough check. | 300 // entry, but without generating actual IO to perform a thorough check. |
(...skipping 29 matching lines...) Expand all Loading... |
315 entry->Close(); | 330 entry->Close(); |
316 } | 331 } |
317 }; | 332 }; |
318 | 333 |
319 // Automatically closes an entry when it goes out of scope. | 334 // Automatically closes an entry when it goes out of scope. |
320 typedef scoped_ptr<Entry, EntryDeleter> ScopedEntryPtr; | 335 typedef scoped_ptr<Entry, EntryDeleter> ScopedEntryPtr; |
321 | 336 |
322 } // namespace disk_cache | 337 } // namespace disk_cache |
323 | 338 |
324 #endif // NET_DISK_CACHE_DISK_CACHE_H_ | 339 #endif // NET_DISK_CACHE_DISK_CACHE_H_ |
OLD | NEW |