1 /* Copyright 2017 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 #ifndef TENSORFLOW_CORE_PLATFORM_CLOUD_FILE_BLOCK_CACHE_H_ 17 #define TENSORFLOW_CORE_PLATFORM_CLOUD_FILE_BLOCK_CACHE_H_ 18 19 #include <functional> 20 #include <list> 21 #include <map> 22 #include <memory> 23 #include <string> 24 #include <vector> 25 #include "tensorflow/core/lib/core/status.h" 26 #include "tensorflow/core/lib/core/stringpiece.h" 27 #include "tensorflow/core/platform/env.h" 28 #include "tensorflow/core/platform/mutex.h" 29 #include "tensorflow/core/platform/notification.h" 30 #include "tensorflow/core/platform/thread_annotations.h" 31 #include "tensorflow/core/platform/types.h" 32 33 namespace tensorflow { 34 35 /// \brief A block cache of file contents, keyed by {filename, offset}. 36 /// 37 /// This class should be shared by read-only random access files on a remote 38 /// filesystem (e.g. GCS). 39 class FileBlockCache { 40 public: 41 /// The callback executed when a block is not found in the cache, and needs to 42 /// be fetched from the backing filesystem. This callback is provided when the 43 /// cache is constructed. The returned Status should be OK as long as the 44 /// read from the remote filesystem succeeded (similar to the semantics of the 45 /// read(2) system call). 46 typedef std::function<Status(const string& filename, size_t offset, 47 size_t buffer_size, char* buffer, 48 size_t* bytes_transferred)> 49 BlockFetcher; 50 ~FileBlockCache()51 virtual ~FileBlockCache() {} 52 53 /// Read `n` bytes from `filename` starting at `offset` into `out`. This 54 /// method will return: 55 /// 56 /// 1) The error from the remote filesystem, if the read from the remote 57 /// filesystem failed. 58 /// 2) PRECONDITION_FAILED if the read from the remote filesystem succeeded, 59 /// but the read returned a partial block, and the LRU cache contained a 60 /// block at a higher offset (indicating that the partial block should have 61 /// been a full block). 62 /// 3) OUT_OF_RANGE if the read from the remote filesystem succeeded, but 63 /// the file contents do not extend past `offset` and thus nothing was 64 /// placed in `out`. 65 /// 4) OK otherwise (i.e. the read succeeded, and at least one byte was placed 66 /// in `out`). 67 virtual Status Read(const string& filename, size_t offset, size_t n, 68 char* buffer, size_t* bytes_transferred) = 0; 69 70 // Validate the given file signature with the existing file signature in the 71 // cache. Returns true if the signature doesn't change or the file did not 72 // exist before. If the signature changes, update the existing signature with 73 // the new one and remove the file from cache. 74 virtual bool ValidateAndUpdateFileSignature(const string& filename, 75 int64 file_signature) = 0; 76 77 /// Remove all cached blocks for `filename`. 78 virtual void RemoveFile(const string& filename) = 0; 79 80 /// Remove all cached data. 81 virtual void Flush() = 0; 82 83 /// Accessors for cache parameters. 84 virtual size_t block_size() const = 0; 85 virtual size_t max_bytes() const = 0; 86 virtual uint64 max_staleness() const = 0; 87 88 /// The current size (in bytes) of the cache. 89 virtual size_t CacheSize() const = 0; 90 91 // Returns true if the cache is enabled. If false, the BlockFetcher callback 92 // is always executed during Read. 93 virtual bool IsCacheEnabled() const = 0; 94 }; 95 96 } // namespace tensorflow 97 98 #endif // TENSORFLOW_CORE_PLATFORM_CLOUD_FILE_BLOCK_CACHE_H_ 99