Seastar
High performance C++ framework for concurrent servers
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
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.

Examples
file_demo.cc.

#include <seastar/core/file.hh>

Classes

class  eof_error
 

Public Member Functions

 file () noexcept
 
 file (shared_ptr< file_impl > impl) noexcept
 
 file (file_handle &&handle) noexcept
 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 noexcept
 Alignment requirement for file offsets (for reads)
 
uint64_t disk_write_dma_alignment () const noexcept
 Alignment requirement for file offsets (for writes)
 
uint64_t disk_overwrite_dma_alignment () const noexcept
 
uint64_t memory_dma_alignment () const noexcept
 Alignment requirement for data buffers.
 
size_t disk_read_max_length () const noexcept
 
size_t disk_write_max_length () const noexcept
 
template<typename CharType >
future< size_t > dma_read (uint64_t aligned_pos, CharType *aligned_buffer, size_t aligned_len, io_intent *intent=nullptr) noexcept
 
template<typename CharType >
future< temporary_buffer< CharType > > dma_read (uint64_t pos, size_t len, io_intent *intent=nullptr) noexcept
 
template<typename CharType >
future< temporary_buffer< CharType > > dma_read_exactly (uint64_t pos, size_t len, io_intent *intent=nullptr) noexcept
 
future< size_t > dma_read (uint64_t pos, std::vector< iovec > iov, io_intent *intent=nullptr) noexcept
 
template<typename CharType >
future< size_t > dma_write (uint64_t pos, const CharType *buffer, size_t len, io_intent *intent=nullptr) noexcept
 
future< size_t > dma_write (uint64_t pos, std::vector< iovec > iov, io_intent *intent=nullptr) noexcept
 
future flush () noexcept
 
future< struct stat > stat () noexcept
 Returns stat information about the file.
 
future truncate (uint64_t length) noexcept
 Truncates the file to a specified length.
 
future allocate (uint64_t position, uint64_t length) noexcept
 
future discard (uint64_t offset, uint64_t length) noexcept
 
future< int > ioctl (uint64_t cmd, void *argp) noexcept
 
future< int > ioctl_short (uint64_t cmd, void *argp) noexcept
 
future< int > fcntl (int op, uintptr_t arg=0UL) noexcept
 
future< int > fcntl_short (int op, uintptr_t arg=0UL) noexcept
 
future set_file_lifetime_hint (uint64_t hint) noexcept
 
future set_inode_lifetime_hint (uint64_t hint) noexcept
 
future< uint64_t > get_file_lifetime_hint () noexcept
 
future< uint64_t > get_inode_lifetime_hint () noexcept
 
future< uint64_t > size () const noexcept
 Gets the file size.
 
future close () noexcept
 
subscription< directory_entrylist_directory (std::function< future<>(directory_entry de)> next)
 Returns a directory listing, given that this file object is a directory.
 
coroutine::experimental::generator< directory_entryexperimental_list_directory ()
 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, io_intent *intent=nullptr) noexcept
 
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 (std::string_view name, open_flags flags) noexcept
 
future< fileopen_file_dma (std::string_view name, open_flags flags, file_open_options options) noexcept
 
future< fileopen_directory (std::string_view name) noexcept
 

Constructor & Destructor Documentation

◆ file() [1/2]

seastar::file::file ( )
inlinenoexcept

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 
)
noexcept

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.
lengthlength of range to allocate.
Returns
future that becomes ready when the operation completes.

◆ close()

future seastar::file::close ( )
noexcept

Closes the file.

Flushes any pending operations and release any resources associated with the file (except for stable storage). Resets the file object back to uninitialized state as if by assigning file() to it.

Note
close() never fails. It just reports errors and swallows them. 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 
)
noexcept

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.

◆ disk_overwrite_dma_alignment()

uint64_t seastar::file::disk_overwrite_dma_alignment ( ) const
inlinenoexcept

Alignment requirement for file offsets (for overwrites).

Specifies the minimum alignment for disk offsets for overwrites (writes to a location that was previously written). This can be smaller than disk_write_dma_alignment(), allowing a reduction in disk bandwidth used.

◆ disk_read_max_length()

size_t seastar::file::disk_read_max_length ( ) const
inlinenoexcept

Recommended limit for read request size. Submitting a larger request will not cause any error, but may result in poor latencies for this and any other concurrent requests

◆ disk_write_max_length()

size_t seastar::file::disk_write_max_length ( ) const
inlinenoexcept

Recommended limit for write request size. Submitting a larger request will not cause any error, but may result in poor latencies for this and any other concurrent requests

◆ 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,
io_intent intent = nullptr 
)
inlinenoexcept

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)
intentthe IO intention confirmation (seastar::io_intent)

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

Returns
number of bytes actually read or exceptional future in case of I/O error
Examples
file_demo.cc.

◆ dma_read() [2/3]

template<typename CharType >
future< temporary_buffer< CharType > > seastar::file::dma_read ( uint64_t  pos,
size_t  len,
io_intent intent = nullptr 
)
inlinenoexcept

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

Parameters
posoffset to begin reading from
lennumber of bytes to read
intentthe IO intention confirmation (seastar::io_intent)
Returns
temporary buffer containing the requested data. or exceptional future in 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 or in case of I/O error.

◆ dma_read() [3/3]

future< size_t > seastar::file::dma_read ( uint64_t  pos,
std::vector< iovec >  iov,
io_intent intent = nullptr 
)
inlinenoexcept

Performs a DMA read into the specified iovec.

Parameters
posoffset to read from. Must be aligned to disk_read_dma_alignment.
iovvector of address/size pairs to read into. Addresses must be aligned.
intentthe IO intention confirmation (seastar::io_intent)
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,
io_intent intent = nullptr 
)
inlinenoexcept

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
intentthe IO intention confirmation (seastar::io_intent)
Returns
temporary buffer containing the read data bulk. or exceptional future holding: system_error exception 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,
io_intent intent = nullptr 
)
inlinenoexcept

Read the exact amount of bytes.

Parameters
posoffset in a file to begin reading from
lennumber of bytes to read
intentthe IO intention confirmation (seastar::io_intent)
Returns
temporary buffer containing the read data or exceptional future in case an error, holding: end_of_file_error if 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,
io_intent intent = nullptr 
)
inlinenoexcept

Performs a DMA write from the specified buffer.

Parameters
posoffset to write into. Must be aligned to disk_write_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.
intentthe IO intention confirmation (seastar::io_intent)
Returns
a future representing the number of bytes actually written. A short write may happen due to an I/O error.
Examples
file_demo.cc.

◆ dma_write() [2/2]

future< size_t > seastar::file::dma_write ( uint64_t  pos,
std::vector< iovec >  iov,
io_intent intent = nullptr 
)
inlinenoexcept

Performs a DMA write to the specified iovec.

Parameters
posoffset to write into. Must be aligned to disk_write_dma_alignment.
iovvector of address/size pairs to write from. Addresses must be aligned.
intentthe IO intention confirmation (seastar::io_intent)
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.

◆ fcntl()

future< int > seastar::file::fcntl ( int  op,
uintptr_t  arg = 0UL 
)
noexcept

Generic fcntl syscall support for special file handling.

fcntl performs the operation specified by 'op' field on the file. Some of the use cases can be - setting file status flags, advisory record locking, managing signals, managing file leases or write hints etc. Refer fcntl(2) man page for more details.

Parameters
opthe operation to be executed
argthe optional argument
Returns
a future containing the return value if any, or an exceptional future if the operation has failed

◆ fcntl_short()

future< int > seastar::file::fcntl_short ( int  op,
uintptr_t  arg = 0UL 
)
noexcept

Performs a 'short' fcntl syscall on seastar::file

This is similar to generic fcntl; the difference is, here user indicates that this operation is a short one, and does not involve any i/o or locking. The file module will process this differently from normal fcntl(). Use this only if the user is sure that the operation does not involve any blocking operation. If unsure, use the default fcntl() method. Refer fcntl(2) man page for more details on fcntl operation.

Parameters
opthe operation to be executed
argthe optional argument
Returns
a future containing the return value if any, or an exceptional future if the operation has failed

◆ flush()

future seastar::file::flush ( )
noexcept

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.

◆ get_file_lifetime_hint()

future< uint64_t > seastar::file::get_file_lifetime_hint ( )
noexcept

Get the lifetime hint of the open file descriptor of seastar::file which was set by set_file_lifetime_hint()

Write lifetime hints can be used to inform the kernel about the relative expected lifetime of writes on a given inode or via open file descriptor. An application may use the different hint values to separate writes into different write classes, so that multiple users or applications running on a single storage back-end can aggregate their I/O patterns in a consistent manner. Refer fcntl(2) man page for more details on write lifetime hints.

Returns
the hint value of the open file descriptor

◆ get_inode_lifetime_hint()

future< uint64_t > seastar::file::get_inode_lifetime_hint ( )
noexcept

Get the lifetime hint of the inode of seastar::file which was set by set_inode_lifetime_hint()

Write lifetime hints can be used to inform the kernel about the relative expected lifetime of writes on a given inode or via open file descriptor. An application may use the different hint values to separate writes into different write classes, so that multiple users or applications running on a single storage back-end can aggregate their I/O patterns in a consistent manner. Refer fcntl(2) man page for more details on write lifetime hints.

Returns
the hint value of the inode

◆ ioctl()

future< int > seastar::file::ioctl ( uint64_t  cmd,
void *  argp 
)
noexcept

Generic ioctl syscall support for special file handling.

This interface is useful for many non-standard operations on seastar::file. The examples can be - querying device or file system capabilities, configuring special performance or access modes on devices etc. Refer ioctl(2) man page for more details.

Parameters
cmdioctl command to be executed
argppointer to the buffer which holds the argument
Returns
a future containing the return value if any, or an exceptional future if the operation has failed.

◆ ioctl_short()

future< int > seastar::file::ioctl_short ( uint64_t  cmd,
void *  argp 
)
noexcept

Performs a short ioctl syscall on seastar::file

This is similar to generic ioctl; the difference is, here user indicates that this operation is a short one, and does not involve any i/o or locking. The file module will process this differently from the normal ioctl(). Use this method only if the user is sure that the operation does not involve any blocking operation. If unsure, use the default ioctl() method. Refer ioctl(2) man page for more details on ioctl operation.

Parameters
cmdioctl command to be executed
argppointer to the buffer which holds the argument
Returns
a future containing the return value if any, or an exceptional future if the operation has failed.

◆ 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.

◆ set_file_lifetime_hint()

future seastar::file::set_file_lifetime_hint ( uint64_t  hint)
noexcept

Set a lifetime hint for the open file descriptor corresponding to seastar::file

Write lifetime hints can be used to inform the kernel about the relative expected lifetime of writes on a given inode or via open file descriptor. An application may use the different hint values to separate writes into different write classes, so that multiple users or applications running on a single storage back-end can aggregate their I/O patterns in a consistent manner. Refer fcntl(2) man page for more details on write lifetime hints.

Parameters
hintthe hint value of the stream
Returns
future indicating success or failure

◆ set_inode_lifetime_hint()

future seastar::file::set_inode_lifetime_hint ( uint64_t  hint)
noexcept

Set a lifetime hint for the inode corresponding to seastar::file

Write lifetime hints can be used to inform the kernel about the relative expected lifetime of writes on a given inode or via open file descriptor. An application may use the different hint values to separate writes into different write classes, so that multiple users or applications running on a single storage back-end can aggregate their I/O patterns in a consistent manner. Refer fcntl(2) man page for more details on write lifetime hints.

Parameters
hintthe hint value of the stream
Returns
future indicating success or failure

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