Seastar
High performance C++ framework for concurrent servers
|
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 |
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. | |
file & | operator= (const file &x) noexcept=default |
file & | operator= (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_entry > | list_directory (std::function< future<>(directory_entry de)> next) |
Returns a directory listing, given that this file object is a directory. | |
coroutine::experimental::generator< directory_entry > | experimental_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< file > | open_file_dma (std::string_view name, open_flags flags) noexcept |
future< file > | open_file_dma (std::string_view name, open_flags flags, file_open_options options) noexcept |
future< file > | open_directory (std::string_view name) noexcept |
|
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.
|
default |
Copies a file object. The new and old objects refer to the same underlying file.
x | file object to be copied |
|
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.
position | beginning of the range at which to allocate blocks. |
length | length of range to allocate. |
|
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.
|
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.
|
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.
|
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
|
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
|
inlinenoexcept |
Perform a single DMA read operation.
aligned_pos | offset to begin reading at (should be aligned) |
aligned_buffer | output buffer (should be aligned) |
aligned_len | number of bytes to read (should be aligned) |
intent | the IO intention confirmation (seastar::io_intent) |
Alignment is HW dependent but use 4KB alignment to be on the safe side as explained above.
|
inlinenoexcept |
Read the requested amount of bytes starting from the given offset.
pos | offset to begin reading from |
len | number of bytes to read |
intent | the IO intention confirmation (seastar::io_intent) |
This function doesn't require any alignment for both "pos" and "len"
|
inlinenoexcept |
Performs a DMA read into the specified iovec.
pos | offset to read from. Must be aligned to disk_read_dma_alignment. |
iov | vector of address/size pairs to read into. Addresses must be aligned. |
intent | the IO intention confirmation (seastar::io_intent) |
|
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.
offset | starting address of the range the read bulk should contain |
range_size | size of the addresses range |
intent | the IO intention confirmation (seastar::io_intent) |
|
inlinenoexcept |
Read the exact amount of bytes.
pos | offset in a file to begin reading from |
len | number of bytes to read |
intent | the IO intention confirmation (seastar::io_intent) |
|
inlinenoexcept |
Performs a DMA write from the specified buffer.
pos | offset to write into. Must be aligned to disk_write_dma_alignment. |
buffer | aligned address of buffer to read from. Buffer must exists until the future is made ready. |
len | number of bytes to write. Must be aligned. |
intent | the IO intention confirmation (seastar::io_intent) |
|
inlinenoexcept |
Performs a DMA write to the specified iovec.
pos | offset to write into. Must be aligned to disk_write_dma_alignment. |
iov | vector of address/size pairs to write from. Addresses must be aligned. |
intent | the IO intention confirmation (seastar::io_intent) |
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.
|
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.
op | the operation to be executed |
arg | the optional argument |
|
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.
op | the operation to be executed |
arg | the optional argument |
|
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.
|
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.
|
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.
|
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.
cmd | ioctl command to be executed |
argp | pointer to the buffer which holds the argument |
|
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.
cmd | ioctl command to be executed |
argp | pointer to the buffer which holds the argument |
|
inlineexplicitnoexcept |
Checks whether the file object was initialized.
Assigns a file object. After assignent, the destination and source refer to the same underlying file.
x | file object to assign to this . |
|
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.
hint | the hint value of the stream |
|
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.
hint | the hint value of the stream |