Logo ROOT  
Reference Guide
ROOT::Internal::RRawFile Class Referenceabstract

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/

Definition at line 43 of file RRawFile.hxx.

Classes

struct  RBlockBuffer
 
struct  RIOVec
 Used for vector reads from multiple offsets into multiple buffers. More...
 
struct  ROptions
 On construction, an ROptions parameter can customize the RRawFile behavior. More...
 

Public Types

enum  ELineBreaks { ELineBreaks::kAuto, ELineBreaks::kSystem, ELineBreaks::kUnix, ELineBreaks::kWindows }
 kAuto detects the line break from the first line, kSystem picks the system's default More...
 

Public Member Functions

 RRawFile (const RRawFile &)=delete
 
 RRawFile (std::string_view url, ROptions options)
 
virtual ~RRawFile ()
 
virtual std::unique_ptr< RRawFileClone () const =0
 Create a new RawFile that accesses the same resource. The file pointer is reset to zero. More...
 
virtual int GetFeatures () const =0
 Derived classes shall inform the user about the supported functionality, which can possibly depend on the file at hand. More...
 
std::uint64_t GetFilePos () const
 Returns the offset for the next Read/Readln call. More...
 
std::uint64_t GetSize ()
 Returns the size of the file. More...
 
std::string GetUrl () const
 Returns the url of the file. More...
 
voidMap (size_t nbytes, std::uint64_t offset, std::uint64_t &mapdOffset)
 Memory mapping according to POSIX standard; in particular, new mappings of the same range replace older ones. More...
 
RRawFileoperator= (const RRawFile &)=delete
 
size_t Read (void *buffer, size_t nbytes)
 Read from fFilePos offset. Returns the actual number of bytes read. More...
 
size_t ReadAt (void *buffer, size_t nbytes, std::uint64_t offset)
 Buffered read from a random position. More...
 
bool Readln (std::string &line)
 Read the next line starting from the current value of fFilePos. Returns false if the end of the file is reached. More...
 
void ReadV (RIOVec *ioVec, unsigned int nReq)
 Opens the file if necessary and calls ReadVImpl. More...
 
void Seek (std::uint64_t offset)
 Change the cursor fFilePos. More...
 
void Unmap (void *region, size_t nbytes)
 Receives a pointer returned by Map() and should have nbytes set to the full length of the mapping. More...
 

Static Public Member Functions

static std::unique_ptr< RRawFileCreate (std::string_view url, ROptions options=ROptions())
 Factory method that returns a suitable concrete implementation according to the transport in the url. More...
 
static std::string GetLocation (std::string_view url)
 Returns only the file location, e.g. "server/file" for http://server/file. More...
 
static std::string GetTransport (std::string_view url)
 Returns only the transport protocol in lower case, e.g. "http" for HTTP://server/file. More...
 

Static Public Attributes

static constexpr int kFeatureHasAsyncIo = 0x04
 File supports async IO. More...
 
static constexpr int kFeatureHasMmap = 0x02
 Map() and Unmap() are implemented. More...
 
static constexpr int kFeatureHasSize = 0x01
 GetSize() does not return kUnknownFileSize. More...
 
static constexpr std::uint64_t kUnknownFileSize = std::uint64_t(-1)
 Derived classes do not necessarily need to provide file size information but they can return "not known" instead. More...
 

Protected Member Functions

virtual std::uint64_t GetSizeImpl ()=0
 Derived classes should return the file size or kUnknownFileSize. More...
 
virtual voidMapImpl (size_t nbytes, std::uint64_t offset, std::uint64_t &mapdOffset)
 If a derived class supports mmap, the MapImpl and UnmapImpl calls are supposed to be implemented, too The default implementation throws an error. More...
 
virtual void OpenImpl ()=0
 OpenImpl() is called at most once and before any call to either DoReadAt or DoGetSize. More...
 
virtual size_t ReadAtImpl (void *buffer, size_t nbytes, std::uint64_t offset)=0
 Derived classes should implement low-level reading without buffering. More...
 
virtual void ReadVImpl (RIOVec *ioVec, unsigned int nReq)
 By default implemented as a loop of ReadAt calls but can be overwritten, e.g. XRootD or DAVIX implementations. More...
 
virtual void UnmapImpl (void *region, size_t nbytes)
 Derived classes with mmap support must be able to unmap the memory area handed out by Map() More...
 

Protected Attributes

std::uint64_t fFilePos
 The current position in the file, which can be changed by Seek, Read, and Readln. More...
 
ROptions fOptions
 
std::string fUrl
 

Private Attributes

unsigned int fBlockBufferIdx
 To be used modulo kNumBlockBuffers, points to the last used block buffer in fBlockBuffers. More...
 
RBlockBuffer fBlockBuffers [kNumBlockBuffers]
 An active buffer and a shadow buffer, which supports "jumping back" to a previously used location in the file. More...
 
unsigned char * fBufferSpace
 Memory block containing the block buffers consecutively. More...
 
std::uint64_t fFileSize
 The cached file size. More...
 
bool fIsOpen
 Files are opened lazily and only when required; the open state is kept by this flag. More...
 

Static Private Attributes

static constexpr unsigned int kNumBlockBuffers = 2
 Don't change without adapting ReadAt() More...
 

#include <ROOT/RRawFile.hxx>

Inheritance diagram for ROOT::Internal::RRawFile:
[legend]

Member Enumeration Documentation

◆ ELineBreaks

kAuto detects the line break from the first line, kSystem picks the system's default

Enumerator
kAuto 
kSystem 
kUnix 
kWindows 

Definition at line 48 of file RRawFile.hxx.

Constructor & Destructor Documentation

◆ RRawFile() [1/2]

ROOT::Internal::RRawFile::RRawFile ( std::string_view  url,
ROptions  options 
)

Definition at line 61 of file RRawFile.cxx.

◆ RRawFile() [2/2]

ROOT::Internal::RRawFile::RRawFile ( const RRawFile )
delete

◆ ~RRawFile()

ROOT::Internal::RRawFile::~RRawFile ( )
virtual

Definition at line 67 of file RRawFile.cxx.

Member Function Documentation

◆ Clone()

virtual std::unique_ptr<RRawFile> ROOT::Internal::RRawFile::Clone ( ) const
pure virtual

Create a new RawFile that accesses the same resource. The file pointer is reset to zero.

Implemented in ROOT::Internal::RRawFileDavix, ROOT::Internal::RRawFileWin, and ROOT::Internal::RRawFileUnix.

◆ Create()

std::unique_ptr< ROOT::Internal::RRawFile > ROOT::Internal::RRawFile::Create ( std::string_view  url,
ROptions  options = ROptions() 
)
static

Factory method that returns a suitable concrete implementation according to the transport in the url.

Definition at line 73 of file RRawFile.cxx.

◆ GetFeatures()

virtual int ROOT::Internal::RRawFile::GetFeatures ( ) const
pure virtual

Derived classes shall inform the user about the supported functionality, which can possibly depend on the file at hand.

Implemented in ROOT::Internal::RRawFileDavix, ROOT::Internal::RRawFileWin, and ROOT::Internal::RRawFileUnix.

◆ GetFilePos()

std::uint64_t ROOT::Internal::RRawFile::GetFilePos ( ) const
inline

Returns the offset for the next Read/Readln call.

Definition at line 167 of file RRawFile.hxx.

◆ GetLocation()

std::string ROOT::Internal::RRawFile::GetLocation ( std::string_view  url)
static

Returns only the file location, e.g. "server/file" for http://server/file.

Definition at line 113 of file RRawFile.cxx.

◆ GetSize()

std::uint64_t ROOT::Internal::RRawFile::GetSize ( )

Returns the size of the file.

Definition at line 121 of file RRawFile.cxx.

◆ GetSizeImpl()

virtual std::uint64_t ROOT::Internal::RRawFile::GetSizeImpl ( )
protectedpure virtual

Derived classes should return the file size or kUnknownFileSize.

Implemented in ROOT::Internal::RRawFileDavix, ROOT::Internal::RRawFileWin, and ROOT::Internal::RRawFileUnix.

◆ GetTransport()

std::string ROOT::Internal::RRawFile::GetTransport ( std::string_view  url)
static

Returns only the transport protocol in lower case, e.g. "http" for HTTP://server/file.

Definition at line 136 of file RRawFile.cxx.

◆ GetUrl()

std::string ROOT::Internal::RRawFile::GetUrl ( ) const

Returns the url of the file.

Definition at line 132 of file RRawFile.cxx.

◆ Map()

void * ROOT::Internal::RRawFile::Map ( size_t  nbytes,
std::uint64_t  offset,
std::uint64_t &  mapdOffset 
)

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.

Definition at line 146 of file RRawFile.cxx.

◆ MapImpl()

void * ROOT::Internal::RRawFile::MapImpl ( size_t  nbytes,
std::uint64_t  offset,
std::uint64_t &  mapdOffset 
)
protectedvirtual

If a derived class supports mmap, the MapImpl and UnmapImpl calls are supposed to be implemented, too The default implementation throws an error.

Reimplemented in ROOT::Internal::RRawFileUnix.

Definition at line 95 of file RRawFile.cxx.

◆ OpenImpl()

virtual void ROOT::Internal::RRawFile::OpenImpl ( )
protectedpure virtual

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.

Implemented in ROOT::Internal::RRawFileDavix, ROOT::Internal::RRawFileWin, and ROOT::Internal::RRawFileUnix.

◆ operator=()

RRawFile& ROOT::Internal::RRawFile::operator= ( const RRawFile )
delete

◆ Read()

size_t ROOT::Internal::RRawFile::Read ( void buffer,
size_t  nbytes 
)

Read from fFilePos offset. Returns the actual number of bytes read.

Definition at line 154 of file RRawFile.cxx.

◆ ReadAt()

size_t ROOT::Internal::RRawFile::ReadAt ( void buffer,
size_t  nbytes,
std::uint64_t  offset 
)

Buffered read from a random position.

Returns the actual number of bytes read. Short reads indicate the end of the file

Definition at line 161 of file RRawFile.cxx.

◆ ReadAtImpl()

virtual size_t ROOT::Internal::RRawFile::ReadAtImpl ( void buffer,
size_t  nbytes,
std::uint64_t  offset 
)
protectedpure virtual

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.

Implemented in ROOT::Internal::RRawFileDavix, ROOT::Internal::RRawFileWin, and ROOT::Internal::RRawFileUnix.

◆ Readln()

bool ROOT::Internal::RRawFile::Readln ( std::string &  line)

Read the next line starting from the current value of fFilePos. Returns false if the end of the file is reached.

Definition at line 215 of file RRawFile.cxx.

◆ ReadV()

void ROOT::Internal::RRawFile::ReadV ( RIOVec ioVec,
unsigned int  nReq 
)

Opens the file if necessary and calls ReadVImpl.

Definition at line 207 of file RRawFile.cxx.

◆ ReadVImpl()

void ROOT::Internal::RRawFile::ReadVImpl ( RIOVec ioVec,
unsigned int  nReq 
)
protectedvirtual

By default implemented as a loop of ReadAt calls but can be overwritten, e.g. XRootD or DAVIX implementations.

Reimplemented in ROOT::Internal::RRawFileDavix, and ROOT::Internal::RRawFileUnix.

Definition at line 101 of file RRawFile.cxx.

◆ Seek()

void ROOT::Internal::RRawFile::Seek ( std::uint64_t  offset)

Change the cursor fFilePos.

Definition at line 248 of file RRawFile.cxx.

◆ Unmap()

void ROOT::Internal::RRawFile::Unmap ( void region,
size_t  nbytes 
)

Receives a pointer returned by Map() and should have nbytes set to the full length of the mapping.

Definition at line 253 of file RRawFile.cxx.

◆ UnmapImpl()

void ROOT::Internal::RRawFile::UnmapImpl ( void region,
size_t  nbytes 
)
protectedvirtual

Derived classes with mmap support must be able to unmap the memory area handed out by Map()

Reimplemented in ROOT::Internal::RRawFileUnix.

Definition at line 108 of file RRawFile.cxx.

Member Data Documentation

◆ fBlockBufferIdx

unsigned int ROOT::Internal::RRawFile::fBlockBufferIdx
private

To be used modulo kNumBlockBuffers, points to the last used block buffer in fBlockBuffers.

Definition at line 102 of file RRawFile.hxx.

◆ fBlockBuffers

RBlockBuffer ROOT::Internal::RRawFile::fBlockBuffers[kNumBlockBuffers]
private

An active buffer and a shadow buffer, which supports "jumping back" to a previously used location in the file.

Definition at line 104 of file RRawFile.hxx.

◆ fBufferSpace

unsigned char* ROOT::Internal::RRawFile::fBufferSpace
private

Memory block containing the block buffers consecutively.

Definition at line 106 of file RRawFile.hxx.

◆ fFilePos

std::uint64_t ROOT::Internal::RRawFile::fFilePos
protected

The current position in the file, which can be changed by Seek, Read, and Readln.

Definition at line 116 of file RRawFile.hxx.

◆ fFileSize

std::uint64_t ROOT::Internal::RRawFile::fFileSize
private

The cached file size.

Definition at line 108 of file RRawFile.hxx.

◆ fIsOpen

bool ROOT::Internal::RRawFile::fIsOpen
private

Files are opened lazily and only when required; the open state is kept by this flag.

Definition at line 110 of file RRawFile.hxx.

◆ fOptions

ROptions ROOT::Internal::RRawFile::fOptions
protected

Definition at line 114 of file RRawFile.hxx.

◆ fUrl

std::string ROOT::Internal::RRawFile::fUrl
protected

Definition at line 113 of file RRawFile.hxx.

◆ kFeatureHasAsyncIo

constexpr int ROOT::Internal::RRawFile::kFeatureHasAsyncIo = 0x04
staticconstexpr

File supports async IO.

Definition at line 56 of file RRawFile.hxx.

◆ kFeatureHasMmap

constexpr int ROOT::Internal::RRawFile::kFeatureHasMmap = 0x02
staticconstexpr

Map() and Unmap() are implemented.

Definition at line 54 of file RRawFile.hxx.

◆ kFeatureHasSize

constexpr int ROOT::Internal::RRawFile::kFeatureHasSize = 0x01
staticconstexpr

GetSize() does not return kUnknownFileSize.

Definition at line 52 of file RRawFile.hxx.

◆ kNumBlockBuffers

constexpr unsigned int ROOT::Internal::RRawFile::kNumBlockBuffers = 2
staticconstexprprivate

Don't change without adapting ReadAt()

Definition at line 84 of file RRawFile.hxx.

◆ kUnknownFileSize

constexpr std::uint64_t ROOT::Internal::RRawFile::kUnknownFileSize = std::uint64_t(-1)
staticconstexpr

Derived classes do not necessarily need to provide file size information but they can return "not known" instead.

Definition at line 46 of file RRawFile.hxx.

Libraries for ROOT::Internal::RRawFile:
[legend]

The documentation for this class was generated from the following files: