EIC code displayed by LXR master/​include/​root/​ROOT/​RRawFile.hxx	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 10:10:48

 // @(#)root/io:$Id$
 // Author: Jakob Blomer
 
 /*************************************************************************
  * Copyright (C) 1995-2018, Rene Brun and Fons Rademakers.               *
  * All rights reserved.                                                  *
  *                                                                       *
  * For the licensing terms see $ROOTSYS/LICENSE.                         *
  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
  *************************************************************************/
 
 #ifndef ROOT_RRawFile
 #define ROOT_RRawFile
 
 #include <string_view>
 
 #include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <string>
 
 namespace ROOT {
 namespace Internal {
 
 /**
  * \class RRawFile RRawFile.hxx
  * \ingroup IO
  *
  * The RRawFile provides read-only access to local and remote files. Data can be read either byte-wise or line-wise.
  * The RRawFile base class provides line-wise access and buffering for byte-wise access. Derived classes provide the
  * low-level read operations, e.g. from a local file system or from a web server. The RRawFile is used for non-ROOT
  * RDataSource implementations and for RNTuple.
  *
  * Files are addressed by URL consisting of a transport protocol part and a location, like file:///path/to/data
  * If the transport protocol part and the :// separator are missing, the default protocol is local file. Files are
  * opened when required (on reading, getting file size) and closed on object destruction.
  *
  * RRawFiles manage system resources and are therefore made non-copyable. They can be explicitly cloned though.
  *
  * RRawFile objects are conditionally thread safe. See the user manual for further details:
  * https://root.cern/manual/thread_safety/
  */
 class RRawFile {
 public:
    /// Derived classes do not necessarily need to provide file size information but they can return "not known" instead
    static constexpr std::uint64_t kUnknownFileSize = std::uint64_t(-1);
    /// kAuto detects the line break from the first line, kSystem picks the system's default
    enum class ELineBreaks { kAuto, kSystem, kUnix, kWindows };
 
    // Combination of flags provided by derived classes about the nature of the file
    /// GetSize() does not return kUnknownFileSize
    static constexpr int kFeatureHasSize = 0x01;
    /// Map() and Unmap() are implemented
    static constexpr int kFeatureHasMmap = 0x02;
    /// File supports async IO
    static constexpr int kFeatureHasAsyncIo = 0x04;
 
    /// On construction, an ROptions parameter can customize the RRawFile behavior
    struct ROptions {
       ELineBreaks fLineBreak;
       /**
        * Read at least fBlockSize bytes at a time. A value of zero turns off I/O buffering. A negative value indicates
        * that the protocol-dependent default block size should be used.
        */
       int fBlockSize;
       ROptions() : fLineBreak(ELineBreaks::kAuto), fBlockSize(-1) {}
    };
 
    /// Used for vector reads from multiple offsets into multiple buffers. This is unlike readv(), which scatters a
    /// single byte range from disk into multiple buffers.
    struct RIOVec {
       /// The destination for reading
       void *fBuffer = nullptr;
       /// The file offset
       std::uint64_t fOffset = 0;
       /// The number of desired bytes
       std::size_t fSize = 0;
       /// The number of actually read bytes, set by ReadV()
       std::size_t fOutBytes = 0;
    };
 
    /// Implementations may enforce limits on the use of vector reads. These limits can depend on the server or
    /// the specific file opened and can be queried per RRawFile object through GetReadVLimits().
    /// Note that due to such limits, a vector read with a single request can behave differently from a Read() call.
    struct RIOVecLimits {
       /// Maximum number of elements in a ReadV request vector
       std::size_t fMaxReqs = static_cast<std::size_t>(-1);
       /// Maximum size in bytes of any single request in the request vector
       std::size_t fMaxSingleSize = static_cast<std::size_t>(-1);
       /// Maximum size in bytes of the sum of requests in the vector
       std::uint64_t fMaxTotalSize = static_cast<std::uint64_t>(-1);
 
       bool HasReqsLimit() const { return fMaxReqs != static_cast<std::size_t>(-1); }
       bool HasSizeLimit() const
       {
          return fMaxSingleSize != static_cast<std::size_t>(-1) || fMaxTotalSize != static_cast<std::uint64_t>(-1);
       }
    };
 
 private:
    /// Don't change without adapting ReadAt()
    static constexpr unsigned int kNumBlockBuffers = 2;
    struct RBlockBuffer {
       /// Where in the open file does fBuffer start
       std::uint64_t fBufferOffset;
       /// The number of currently buffered bytes in fBuffer
       size_t fBufferSize;
       /// Points into the I/O buffer with data from the file, not owned.
       unsigned char *fBuffer;
 
       RBlockBuffer() : fBufferOffset(0), fBufferSize(0), fBuffer(nullptr) {}
       RBlockBuffer(const RBlockBuffer &) = delete;
       RBlockBuffer &operator=(const RBlockBuffer &) = delete;
       ~RBlockBuffer() = default;
 
       /// Tries to copy up to nbytes starting at offset from fBuffer into buffer.  Returns number of bytes copied.
       size_t CopyTo(void *buffer, size_t nbytes, std::uint64_t offset);
    };
    /// To be used modulo kNumBlockBuffers, points to the last used block buffer in fBlockBuffers
    unsigned int fBlockBufferIdx;
    /// An active buffer and a shadow buffer, which supports "jumping back" to a previously used location in the file
    RBlockBuffer fBlockBuffers[kNumBlockBuffers];
    /// Memory block containing the block buffers consecutively
    unsigned char *fBufferSpace;
    /// The cached file size
    std::uint64_t fFileSize;
    /// Files are opened lazily and only when required; the open state is kept by this flag
    bool fIsOpen;
 
 protected:
    std::string fUrl;
    ROptions fOptions;
    /// The current position in the file, which can be changed by Seek, Read, and Readln
    std::uint64_t fFilePos;
 
    /**
     * OpenImpl() is called at most once and before any call to either DoReadAt or DoGetSize. If fOptions.fBlocksize
     * is negative, derived classes are responsible to set a sensible value. After a call to OpenImpl(),
     * fOptions.fBlocksize must be larger or equal to zero.
     */
    virtual void OpenImpl() = 0;
    /**
     * Derived classes should implement low-level reading without buffering. Short reads indicate the end of the file,
     * therefore derived classes should return nbytes bytes if available.
     */
    virtual size_t ReadAtImpl(void *buffer, size_t nbytes, std::uint64_t offset) = 0;
    /// Derived classes should return the file size or kUnknownFileSize
    virtual std::uint64_t GetSizeImpl() = 0;
 
    /// If a derived class supports mmap, the MapImpl and UnmapImpl calls are supposed to be implemented, too
    /// The default implementation throws an error
    virtual void *MapImpl(size_t nbytes, std::uint64_t offset, std::uint64_t &mapdOffset);
    /// Derived classes with mmap support must be able to unmap the memory area handed out by Map()
    virtual void UnmapImpl(void *region, size_t nbytes);
 
    /// By default implemented as a loop of ReadAt calls but can be overwritten, e.g. XRootD or DAVIX implementations
    virtual void ReadVImpl(RIOVec *ioVec, unsigned int nReq);
 
    /// Open the file if not already open. Otherwise noop.
    void EnsureOpen();
 
 public:
    RRawFile(std::string_view url, ROptions options);
    RRawFile(const RRawFile &) = delete;
    RRawFile &operator=(const RRawFile &) = delete;
    virtual ~RRawFile();
 
    /// Create a new RawFile that accesses the same resource.  The file pointer is reset to zero.
    virtual std::unique_ptr<RRawFile> Clone() const = 0;
 
    /// Factory method that returns a suitable concrete implementation according to the transport in the url
    static std::unique_ptr<RRawFile> Create(std::string_view url, ROptions options = ROptions());
    /// Returns only the file location, e.g. "server/file" for http://server/file
    static std::string GetLocation(std::string_view url);
    /// Returns only the transport protocol in lower case, e.g. "http" for HTTP://server/file
    static std::string GetTransport(std::string_view url);
 
    /**
     * Buffered read from a random position. Returns the actual number of bytes read.
     * Short reads indicate the end of the file
     */
    size_t ReadAt(void *buffer, size_t nbytes, std::uint64_t offset);
    /// Read from fFilePos offset. Returns the actual number of bytes read.
    size_t Read(void *buffer, size_t nbytes);
    /// Change the cursor fFilePos
    void Seek(std::uint64_t offset);
    /// Returns the offset for the next Read/Readln call
    std::uint64_t GetFilePos() const { return fFilePos; }
    /// Returns the size of the file
    std::uint64_t GetSize();
    /// Returns the url of the file
    std::string GetUrl() const;
 
    /// Opens the file if necessary and calls ReadVImpl
    void ReadV(RIOVec *ioVec, unsigned int nReq);
    /// Returns the limits regarding the ioVec input to ReadV for this specific file; may open the file as a side-effect.
    virtual RIOVecLimits GetReadVLimits() { return RIOVecLimits(); }
 
    /// Memory mapping according to POSIX standard; in particular, new mappings of the same range replace older ones.
    /// Mappings need to be aligned at page boundaries, therefore the real offset can be smaller than the desired value.
    /// Users become owner of the address returned by Map() and are responsible for calling Unmap() with the full length.
    void *Map(size_t nbytes, std::uint64_t offset, std::uint64_t &mapdOffset);
    /// Receives a pointer returned by Map() and should have nbytes set to the full length of the mapping
    void Unmap(void *region, size_t nbytes);
 
    /// Derived classes shall inform the user about the supported functionality, which can possibly depend
    /// on the file at hand
    virtual int GetFeatures() const = 0;
 
    /// Read the next line starting from the current value of fFilePos. Returns false if the end of the file is reached.
    bool Readln(std::string &line);
 
    /// Once opened, the file stay open until destruction of the RRawFile object
    bool IsOpen() const { return fIsOpen; }
 }; // class RRawFile
 
 } // namespace Internal
 } // namespace ROOT
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team