Seastar
High performance C++ framework for concurrent servers
Classes | Public Member Functions | Related Functions | List of all members
seastar::file Class Reference

Detailed Description

A data file on persistent storage.

File objects represent uncached, unbuffered files. As such great care must be taken to cache data at the application layer; neither seastar nor the OS will cache these file.

Data is transferred using direct memory access (DMA). This imposes restrictions on file offsets and data pointers. The former must be aligned on a 4096 byte boundary, while a 512 byte boundary suffices for the latter.

#include <seastar/core/file.hh>

Classes

class  eof_error
 
struct  read_state
 

Public Member Functions

 file ()
 
 file (shared_ptr< file_impl > impl)
 
 file (file_handle &&handle)
 Constructs a file object from a file_handle obtained from another shard.
 
 operator bool () const noexcept
 
 file (const file &x)=default
 
 file (file &&x) noexcept
 Moves a file object.
 
fileoperator= (const file &x) noexcept=default
 
fileoperator= (file &&x) noexcept=default
 Moves assigns a file object.
 
uint64_t disk_read_dma_alignment () const
 Alignment requirement for file offsets (for reads)
 
uint64_t disk_write_dma_alignment () const
 Alignment requirement for file offsets (for writes)
 
uint64_t memory_dma_alignment () const
 Alignment requirement for data buffers.
 
template<typename CharType >
future< size_t > dma_read (uint64_t aligned_pos, CharType *aligned_buffer, size_t aligned_len, const io_priority_class &pc=default_priority_class())
 
template<typename CharType >
future< temporary_buffer< CharType > > dma_read (uint64_t pos, size_t len, const io_priority_class &pc=default_priority_class())
 
template<typename CharType >
future< temporary_buffer< CharType > > dma_read_exactly (uint64_t pos, size_t len, const io_priority_class &pc=default_priority_class())
 
future< size_t > dma_read (uint64_t pos, std::vector< iovec > iov, const io_priority_class &pc=default_priority_class())
 
template<typename CharType >
future< size_t > dma_write (uint64_t pos, const CharType *buffer, size_t len, const io_priority_class &pc=default_priority_class())
 
future< size_t > dma_write (uint64_t pos, std::vector< iovec > iov, const io_priority_class &pc=default_priority_class())
 
future flush ()
 
future< struct stat > stat ()
 Returns stat information about the file.
 
future truncate (uint64_t length)
 Truncates the file to a specified length.
 
future allocate (uint64_t position, uint64_t length)
 
future discard (uint64_t offset, uint64_t length)
 
future< uint64_t > size () const
 Gets the file size.
 
future close ()
 
subscription< directory_entrylist_directory (std::function< future<>(directory_entry de)> next)
 Returns a directory listing, given that this file object is a directory.
 
template<typename CharType >
future< temporary_buffer< CharType > > dma_read_bulk (uint64_t offset, size_t range_size, const io_priority_class &pc=default_priority_class())
 
file_handle dup ()
 Creates a handle that can be transported across shards. More...
 

Related Functions

(Note that these are not member functions.)

future< fileopen_file_dma (sstring name, open_flags flags)
 
future< fileopen_file_dma (sstring name, open_flags flags, file_open_options options)
 
future< fileopen_directory (sstring name)
 

Class Documentation

◆ seastar::file::read_state

struct seastar::file::read_state

Constructor & Destructor Documentation

◆ file() [1/2]

seastar::file::file ( )
inline

Default constructor constructs an uninitialized file object.

A default constructor is useful for the common practice of declaring a variable, and only assigning to it later. The uninitialized file must not be used, or undefined behavior will result (currently, a null pointer dereference).

One can check whether a file object is in uninitialized state with operator bool(); One can reset a file back to uninitialized state by assigning file() to it.

◆ file() [2/2]

seastar::file::file ( const file x)
default

Copies a file object. The new and old objects refer to the same underlying file.

Parameters
xfile object to be copied

Member Function Documentation

◆ allocate()

future seastar::file::allocate ( uint64_t  position,
uint64_t  length 
)
inline

Preallocate disk blocks for a specified byte range.

Requests the file system to allocate disk blocks to back the specified range (length bytes starting at position). The range may be outside the current file size; the blocks can then be used when appending to the file.

Parameters
positionbeginning of the range at which to allocate blocks. length length of range to allocate.
Returns
future that becomes ready when the operation completes.

◆ close()

future seastar::file::close ( )
inline

Closes the file.

Flushes any pending operations and release any resources associated with the file (except for stable storage).

Note
to ensure file data reaches stable storage, you must call flush() before calling close().

◆ discard()

future seastar::file::discard ( uint64_t  offset,
uint64_t  length 
)
inline

Discard unneeded data from the file.

The discard operation tells the file system that a range of offsets (which be aligned) is no longer needed and can be reused.

◆ dma_read() [1/3]

template<typename CharType >
future<size_t> seastar::file::dma_read ( uint64_t  aligned_pos,
CharType *  aligned_buffer,
size_t  aligned_len,
const io_priority_class &  pc = default_priority_class() 
)
inline

Perform a single DMA read operation.

Parameters
aligned_posoffset to begin reading at (should be aligned)
aligned_bufferoutput buffer (should be aligned)
aligned_lennumber of bytes to read (should be aligned)
pcthe IO priority class under which to queue this operation

Alignment is HW dependent but use 4KB alignment to be on the safe side as explained above.

Returns
number of bytes actually read
Exceptions
exceptionin case of I/O error

◆ dma_read() [2/3]

template<typename CharType >
future<temporary_buffer<CharType> > seastar::file::dma_read ( uint64_t  pos,
size_t  len,
const io_priority_class &  pc = default_priority_class() 
)
inline

Read the requested amount of bytes starting from the given offset.

Parameters
posoffset to begin reading from
lennumber of bytes to read
pcthe IO priority class under which to queue this operation
Returns
temporary buffer containing the requested data.
Exceptions
exceptionin case of I/O error

This function doesn't require any alignment for both "pos" and "len"

Note
size of the returned buffer may be smaller than "len" if EOF is reached of in case of I/O error.

◆ dma_read() [3/3]

future<size_t> seastar::file::dma_read ( uint64_t  pos,
std::vector< iovec >  iov,
const io_priority_class &  pc = default_priority_class() 
)
inline

Performs a DMA read into the specified iovec.

Parameters
posoffset to read from. Must be aligned to dma_alignment.
iovvector of address/size pairs to read into. Addresses must be aligned.
pcthe IO priority class under which to queue this operation
Returns
a future representing the number of bytes actually read. A short read may happen due to end-of-file or an I/O error.

◆ dma_read_bulk()

template<typename CharType >
future<temporary_buffer<CharType> > seastar::file::dma_read_bulk ( uint64_t  offset,
size_t  range_size,
const io_priority_class &  pc = default_priority_class() 
)
inline

Read a data bulk containing the provided addresses range that starts at the given offset and ends at either the address aligned to dma_alignment (4KB) or at the file end.

Parameters
offsetstarting address of the range the read bulk should contain
range_sizesize of the addresses range
pcthe IO priority class under which to queue this operation
Returns
temporary buffer containing the read data bulk.
Exceptions
system_errorexception in case of I/O error or eof_error when "offset" is beyond EOF.

◆ dma_read_exactly()

template<typename CharType >
future<temporary_buffer<CharType> > seastar::file::dma_read_exactly ( uint64_t  pos,
size_t  len,
const io_priority_class &  pc = default_priority_class() 
)
inline

Read the exact amount of bytes.

Parameters
posoffset in a file to begin reading from
lennumber of bytes to read
pcthe IO priority class under which to queue this operation
Returns
temporary buffer containing the read data
Exceptions
end_of_file_errorif EOF is reached, file_io_error or std::system_error in case of I/O error.

◆ dma_write() [1/2]

template<typename CharType >
future<size_t> seastar::file::dma_write ( uint64_t  pos,
const CharType *  buffer,
size_t  len,
const io_priority_class &  pc = default_priority_class() 
)
inline

Performs a DMA write from the specified buffer.

Parameters
posoffset to write into. Must be aligned to dma_alignment.
bufferaligned address of buffer to read from. Buffer must exists until the future is made ready.
lennumber of bytes to write. Must be aligned.
pcthe IO priority class under which to queue this operation
Returns
a future representing the number of bytes actually written. A short write may happen due to an I/O error.

◆ dma_write() [2/2]

future<size_t> seastar::file::dma_write ( uint64_t  pos,
std::vector< iovec >  iov,
const io_priority_class &  pc = default_priority_class() 
)
inline

Performs a DMA write to the specified iovec.

Parameters
posoffset to write into. Must be aligned to dma_alignment.
iovvector of address/size pairs to write from. Addresses must be aligned.
pcthe IO priority class under which to queue this operation
Returns
a future representing the number of bytes actually written. A short write may happen due to an I/O error.

◆ dup()

file_handle seastar::file::dup ( )

Creates a handle that can be transported across shards.

Creates a handle that can be transported across shards, and then used to create a new shard-local file object that refers to the same on-disk file.

Note
Use on read-only files.

◆ flush()

future seastar::file::flush ( )
inline

Causes any previously written data to be made stable on persistent storage.

Prior to a flush, written data may or may not survive a power failure. After a flush, data is guaranteed to be on disk.

◆ operator bool()

seastar::file::operator bool ( ) const
inlineexplicitnoexcept

Checks whether the file object was initialized.

Returns
false if the file object is uninitialized (default constructed), true if the file object refers to an actual file.

◆ operator=()

file& seastar::file::operator= ( const file x)
defaultnoexcept

Assigns a file object. After assignent, the destination and source refer to the same underlying file.

Parameters
xfile object to assign to this.

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