FileHandler.h

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
#include <functional>
#include <map>
#include <string>
#include <utility>
#include <vector>
 
#include <vrs/ErrorCode.h>
#include <vrs/FileDelegator.h>
#include <vrs/FileSpec.h>
#include <vrs/VrsExport.h>
#include <vrs/helpers/EnumTemplates.hpp>
#include <vrs/os/CompilerAttributes.h>
 
namespace vrs {
 
using std::string;
using std::vector;
 
enum class CachingStrategy {
  Undefined = 0,
 
  Passive, 
  Streaming, 
  StreamingBidirectional, 
  StreamingBackward, 
  ReleaseAfterRead, 
 
  COUNT
};
 
constexpr const char* kPrefetchCache = "prefetch_cache";
 
VRS_API string toString(CachingStrategy cachingStrategy);
 
template <>
VRS_API CachingStrategy toEnum<>(const string& name);
 
class VRS_API FileHandler : public FileDelegator {
 public:
  struct CacheStats {
    double startTime;
    double waitTime;
    size_t blockReadCount;
    size_t blockMissingCount;
    size_t blockPendingCount;
    size_t sequenceSize;
  };
 
  using CacheStatsCallbackFunction = std::function<void(const CacheStats& stats)>;
 
  FileHandler() = default;
 
  static unique_ptr<FileHandler> makeOpen(const string& filePath);
  static unique_ptr<FileHandler> makeOpen(const FileSpec& fileSpec);
 
  virtual unique_ptr<FileHandler> makeNew() const = 0;
  virtual const string& getFileHandlerName() const = 0;
  virtual const string& getWriteFileHandlerName() const; // maybe use another FileHandler for writes
 
  virtual int open(const string& filePath);
  virtual int openSpec(const FileSpec& fileSpec) = 0;
 
  int delegateOpen(const FileSpec& fileSpec, unique_ptr<FileHandler>& outNewDelegate) override;
 
  virtual bool isOpened() const = 0;
 
  virtual int64_t getTotalSize() const = 0;
  virtual int close() = 0;
 
  virtual int skipForward(int64_t offset) = 0;
  virtual int setPos(int64_t offset) = 0;
  virtual bool isAvailableOrPrefetch(MAYBE_UNUSED size_t length) {
    return !isRemoteFileSystem();
  }
  virtual int read(void* buffer, size_t length) = 0;
  template <typename T, std::enable_if_t<std::is_trivially_copyable<T>::value, int> = 0>
  int read(T& object) {
    return read(&object, sizeof(object));
  }
  template <typename T, std::enable_if_t<std::is_trivially_copyable<T>::value, int> = 0>
  int read(vector<T>& vec) {
    return read(vec.data(), vec.size() * sizeof(T));
  }
  virtual size_t getLastRWSize() const = 0;
 
  virtual bool isReadOnly() const;
 
  virtual vector<std::pair<string, int64_t>> getFileChunks() const = 0;
  virtual void forgetFurtherChunks(int64_t maxSize) = 0;
 
  virtual int getLastError() const = 0;
  virtual bool isEof() const = 0;
  virtual int64_t getPos() const = 0;
  virtual int64_t getChunkPos() const = 0;
  virtual int getChunkRange(int64_t& outChunkOffset, int64_t& outChunkSize) const = 0;
 
  virtual bool setCachingStrategy(CachingStrategy /*cachingStrategy*/) {
    return false;
  }
  virtual CachingStrategy getCachingStrategy() const {
    return CachingStrategy::Passive; // default, in particular when there is no caching implemented.
  }
 
  virtual bool prefetchReadSequence(
      MAYBE_UNUSED const vector<std::pair<size_t, size_t>>& sequence,
      MAYBE_UNUSED bool clearSequence = true) {
    return false;
  }
 
  virtual bool setStatsCallback(const CacheStatsCallbackFunction& /* callback */) {
    return false;
  }
 
  virtual bool purgeCache() {
    return true;
  }
 
  bool isFileHandlerMatch(const FileSpec& fileSpec) const;
 
  virtual bool isRemoteFileSystem() const = 0;
 
  virtual bool showProgress() const {
    return isRemoteFileSystem();
  }
};
 
class VRS_API TemporaryCachingStrategy {
 public:
  TemporaryCachingStrategy(unique_ptr<FileHandler>& handler, CachingStrategy temporaryStrategy)
      : handler_{handler},
        originalPtr_{handler_.get()},
        originalStrategy_{handler->getCachingStrategy()} {
    handler_->setCachingStrategy(temporaryStrategy);
  }
  ~TemporaryCachingStrategy() {
    // only restore the original strategy if the handler hasn't been changed
    if (originalPtr_ == handler_.get()) {
      originalPtr_->setCachingStrategy(originalStrategy_);
    }
  }
 
 private:
  unique_ptr<FileHandler>& handler_;
  FileHandler* originalPtr_;
  CachingStrategy originalStrategy_;
};
 
} // namespace vrs