Seastar
High performance C++ framework for concurrent servers
Classes | Enumerations | Functions
File Input/Output

Classes

struct  seastar::directory_entry
 A directory entry being listed. More...
 
struct  seastar::file_open_options
 
class  seastar::file
 
class  seastar::file_handle
 A shard-transportable handle to a file. More...
 

Enumerations

enum  seastar::directory_entry_type {
  block_device, char_device, directory, fifo,
  link, regular, socket
}
 
enum  seastar::fs_type {
  other, xfs, ext2, ext3,
  ext4, btrfs, hfs, tmpfs
}
 Enumeration describing the type of a particular filesystem.
 

Functions

future seastar::check_direct_io_support (sstring path)
 
future seastar::make_directory (sstring name)
 
future seastar::touch_directory (sstring name)
 
future seastar::recursive_touch_directory (sstring name)
 
future seastar::sync_directory (sstring name)
 
future seastar::remove_file (sstring pathname)
 
future seastar::rename_file (sstring old_pathname, sstring new_pathname)
 
future< uint64_t > seastar::file_size (sstring name)
 
future< bool > seastar::file_exists (sstring name)
 
future seastar::link_file (sstring oldpath, sstring newpath)
 
future< fs_typeseastar::file_system_at (sstring name)
 
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)
 

Detailed Description

Seastar provides a file API to deal with persistent storage. Unlike most file APIs, seastar offers unbuffered file I/O (similar to, and based on, O_DIRECT). Unbuffered I/O means that the application is required to do its own caching, but delivers better performance if this caching is done correctly.

For random I/O or sequential unbuffered I/O, the file class provides a set of methods for reading, writing, discarding, or otherwise manipulating a file. For buffered sequential I/O, see make_file_input_stream() and make_file_output_stream().


Class Documentation

◆ seastar::directory_entry

struct seastar::directory_entry

A directory entry being listed.

Class Members
sstring name Name of the file in a directory entry. Will never be "." or "..". Only the last component is included.
optional< directory_entry_type > type Type of the directory entry, if known.

◆ seastar::file_open_options

struct seastar::file_open_options

File open options

Options used to configure an open file.

file

Class Members
uint64_t extent_allocation_size_hint Allocate this much disk space when extending the file.
bool sloppy_size Allow the file size not to track the amount of data written until a flush.
uint64_t sloppy_size_hint Hint as to what the eventual file size will be.

Enumeration Type Documentation

◆ directory_entry_type

Enumeration describing the type of a directory entry being listed.

See also
file::list_directory()

Function Documentation

◆ check_direct_io_support()

future seastar::check_direct_io_support ( sstring  path)

Checks if a given directory supports direct io

Seastar bypasses the Operating System caches and issues direct io to the underlying block devices. Projects using seastar should check if the directory lies in a filesystem that support such operations. This function can be used to do that.

It will return if direct io can be used, or throw an std::system_error exception, with the EINVAL error code.

A std::system_error with the respective error code is also thrown if path is not a directory.

Parameters
paththe directory we need to verify.

◆ file_exists()

future< bool > seastar::file_exists ( sstring  name)

check if a file exists.

Parameters
namename of the file to check

◆ file_size()

future< uint64_t > seastar::file_size ( sstring  name)

Return the size of a file.

Parameters
namename of the file to return the size

◆ file_system_at()

future< fs_type > seastar::file_system_at ( sstring  name)

Return information about the filesystem where a file is located.

Parameters
namename of the file to inspect

◆ link_file()

future seastar::link_file ( sstring  oldpath,
sstring  newpath 
)

Creates a hard link for a file

Parameters
oldpathexisting file name
newpathname of link

◆ make_directory()

future seastar::make_directory ( sstring  name)

Creates a new directory.

Parameters
namename of the directory to create
Note
The directory is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ open_directory()

future< file > open_directory ( sstring  name)
related

Opens a directory.

Parameters
namename of the directory to open
Returns
a file object representing a directory. The only legal operations are file::list_directory(), file::fsync(), and file::close().

◆ open_file_dma() [1/2]

future< file > open_file_dma ( sstring  name,
open_flags  flags 
)
related

Opens or creates a file. The "dma" in the name refers to the fact that data transfers are unbuffered and uncached.

Parameters
namethe name of the file to open or create
flagsvarious flags controlling the open process
Returns
a file object, as a future
Note
The file name is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ open_file_dma() [2/2]

future< file > open_file_dma ( sstring  name,
open_flags  flags,
file_open_options  options 
)
related

Opens or creates a file. The "dma" in the name refers to the fact that data transfers are unbuffered and uncached.

Parameters
namethe name of the file to open or create
flagsvarious flags controlling the open process
optionsoptions for opening the file
Returns
a file object, as a future
Note
The file name is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ recursive_touch_directory()

future seastar::recursive_touch_directory ( sstring  name)

Recursively ensures a directory exists

Checks whether each component of a directory exists, and if not, creates it.

Parameters
namename of the directory to potentially create
separatorcharacter used as directory separator
Note
This function fsyncs each component created, and is therefore guaranteed to be stable on disk.

◆ remove_file()

future seastar::remove_file ( sstring  name)

Removes (unlinks) a file.

Parameters
namename of the file to remove
Note
The removal is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ rename_file()

future seastar::rename_file ( sstring  old_name,
sstring  new_name 
)

Renames (moves) a file.

Parameters
old_nameexisting file name
new_namenew file name
Note
The rename is not guaranteed to be stable on disk, unless the both containing directories are sync'ed.

◆ sync_directory()

future seastar::sync_directory ( sstring  name)

Synchronizes a directory to disk

Makes sure the modifications in a directory are synchronized in disk. This is useful, for instance, after creating or removing a file inside the directory.

Parameters
namename of the directory to potentially create

◆ touch_directory()

future seastar::touch_directory ( sstring  name)

Ensures a directory exists

Checks whether a directory exists, and if not, creates it. Only the last component of the directory name is created.

Parameters
namename of the directory to potentially create
Note
The directory is not guaranteed to be stable on disk, unless the containing directory is sync'ed.