CascadeFileStream Class Reference

base class of high-performance streams More...

#include <cascade/util/CascadeFileStream.h>

Inheritance diagram for CascadeFileStream:

List of all members.

Public Member Functions
	CascadeFileStream ()
virtual	~CascadeFileStream ()
virtual bool	Open (CascadeFile &file)
virtual bool	Open (const CascadeString &url)
virtual bool	IsOpen ()
virtual void	Close ()
virtual u32	GetBlockSize ()
virtual u64	GetSize ()
virtual u64	GetPosition ()
virtual bool	SeekToPosition (u64 nPosition)
virtual u32	ReadBytes (u32 nBytes, void *pBuff)

---

Detailed Description

base class of high-performance streams

Skip the description

CascadeFileStream provides the highest read performance for sequential streaming from files possible. CascadeFileStream will use O_DIRECT file access when the underlying filesystem supports it, or O_STREAMING access on files that don't support O_DIRECT. If you are processing file data as you [sequentially] read files, then you should use class CascadeFileStream. For details on how CascadeFileStream works, read on.

When the underlying file system provides O_DIRECT access, CascadeFileStream will use O_DIRECT access. Linux, however, imposes some restrictions. Namely all read requests must start on fs block boundaries and have a size that is a multiple of the block size. Because a file's block size can vary, a good rule of thumb is to perform reads aligned on and in increments of 4096 bytes since that will cover the cases of blocksizes of 512 bytes, 1K, 2K and 4K. In addition to aligning your file read location and size, Linux also requires that your memory buffer start on an address with the same alignment.

CascadeFileStream imposes no such restrictions.

If the underlying filesystem supports O_DIRECT, the file is opened with O_DIRECT. If the client honors the buffer and read alignment restrictions, values will be passed directly to the operating system for direct O_DIRECT access. If the alignment restrictions are not honored, an internally aligned buffer will be created in an optimized fashion and used for O_DIRECT access. The data will then be memcpy'd into the proper place in the client's buffer. Although the performance hit of an extra copy is incurred, with the benefits of O_DIRECT, reads are faster nonetheless. If the underlying filesystem does not support O_DIRECT access, then the file will be opened with O_STREAMING access. All reads are passed directly to the operating system. O_STREAMING provides after-read page cache pruning, so system performance will not degrade after heavy reading.

---

class CascadeFileStream

---

Constructor & Destructor Documentation

CascadeFileStream::CascadeFileStream (   )

the constructor This constructor is light weight.

virtual CascadeFileStream::~CascadeFileStream (   )  [virtual]

the destructor The CascadeFileStream destructor closes the file stream if necessary.

---

Member Function Documentation

virtual void CascadeFileStream::Close (   )  [virtual]

closes the file-stream Close() closes a previously opened file stream.

virtual u32 CascadeFileStream::GetBlockSize (   )  [virtual]

gets the block size of the file stream GetBlockSize() gets the block size of the file. This block size may be used to align and size read requests for optimal performance. This function only succeeds if the file is open. Returns: the block size of the file

virtual u64 CascadeFileStream::GetPosition (   )  [virtual]

returns the current position in the stream Returns the current position in the stream. Returns: the current position in the stream Implements CascadeStream.

virtual u64 CascadeFileStream::GetSize (   )  [virtual]

returns the size of the stream Returns number of total bytes in the stream. The size doesn't change as bytes are read or the position is seeked to. Returns: the size of the data stream in bytes Implements CascadeStream.

virtual bool CascadeFileStream::IsOpen (   )  [virtual]

determines whether or not the file stream is open IsOpen determines whether or not the file stream is open. Returns: whether or not the file stream is open

virtual bool CascadeFileStream::Open (  const CascadeString &  url  )  [virtual]

opens a url as a file stream Open() opens a url as a file stream. File streams provide the best read performance for read-and-consume data streamed from files. The url passed in must begin with "file://" Parameters: url  the url to open as a stream (must be a file:// url) Returns: whether or not the open was successful.

virtual bool CascadeFileStream::Open (  CascadeFile &  file  )  [virtual]

opens a file as a file stream Open() opens a file as a file stream. File streams provide the best read performance for read-and-consume data streamed from files. Parameters: file  the file to open as a stream Returns: whether or not the open was successful.

virtual u32 CascadeFileStream::ReadBytes (  u32  nBytes, void *  pBuff )  [virtual]

reads bytes from the stream Reads bytes from the stream. Returns: the number of bytes actually read from the stream Implements CascadeStream.

virtual bool CascadeFileStream::SeekToPosition (  u64  nPosition  )  [virtual]

seeks to a position in the stream SeekToPositions seeks to a byte position in the stream. Returns: whether or not the seek succeeded Implements CascadeStream.

---

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

• CascadeFileStream.h

---