/// Seastar is a high performance C++ application framework for high
/// concurrency server applications.
///
-/// A good place to start is the [Tutorial](doc/tutorial.md).
+/// A good place to start is the [Tutorial](tutorial.html) or [Multi-page version](split/).
///
/// Please see:
/// - \ref future-module Documentation on futures and promises, which are
/// - \ref fiber-module Utilities for managing loosely coupled chains of
/// continuations, also known as fibers
/// - \ref thread-module Support for traditional threaded execution
+/// - \ref rpc Build high-level communication protocols
+///
+/// View the [Seastar compatibility statement](./md_compatibility.html) for
+/// information about library evolution.
#include <seastar/core/sstring.hh>
#include <seastar/core/future.hh>
#include <seastar/core/file-types.hh>
#include <seastar/util/bool_class.hh>
+#include <seastar/util/std-compat.hh>
#include "./internal/api-level.hh"
namespace seastar {
template <class CharType> class input_stream;
template <class CharType> class output_stream;
-// reactor.hh
-SEASTAR_INCLUDE_API_V2 namespace api_v2 { class server_socket; }
-
-#if SEASTAR_API_LEVEL <= 1
-
-SEASTAR_INCLUDE_API_V1 namespace api_v1 { class server_socket; }
-
-#endif
-
+class server_socket;
+class socket;
class connected_socket;
class socket_address;
struct listen_options;
struct file_open_options;
struct stat_data;
+namespace net {
+
+class udp_channel;
+
+}
+
// Networking API
/// \defgroup networking-module Networking
/// \return a \ref connected_socket object, or an exception
future<connected_socket> connect(socket_address sa, socket_address local, transport proto);
+
+/// Creates a socket object suitable for establishing stream-oriented connections
+///
+/// \return a \ref socket object that can be used for establishing connections
+socket make_socket();
+
+/// Creates a udp_channel object suitable for sending UDP packets
+///
+/// The channel is not bound to a local address, and thus can only be used
+/// for sending.
+///
+/// \return a \ref net::udp_channel object that can be used for UDP transfers.
+net::udp_channel make_udp_channel();
+
+
+/// Creates a udp_channel object suitable for sending and receiving UDP packets
+///
+/// \param local local address to bind to
+///
+/// \return a \ref net::udp_channel object that can be used for UDP transfers.
+net::udp_channel make_udp_channel(const socket_address& local);
+
/// @}
/// \defgroup fileio-module File Input/Output
/// containing directory is sync'ed.
///
/// \relates file
-future<file> open_file_dma(sstring name, open_flags flags);
+future<file> open_file_dma(std::string_view name, open_flags flags) noexcept;
/// Opens or creates a file. The "dma" in the name refers to the fact
/// that data transfers are unbuffered and uncached.
/// containing directory is sync'ed.
///
/// \relates file
-future<file> open_file_dma(sstring name, open_flags flags, file_open_options options);
+future<file> open_file_dma(std::string_view name, open_flags flags, file_open_options options) noexcept;
/// Checks if a given directory supports direct io
///
/// 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 \ref path is
+/// A std::system_error with the respective error code is also thrown if \c path is
/// not a directory.
///
/// \param path the directory we need to verify.
-future<> check_direct_io_support(sstring path);
+future<> check_direct_io_support(std::string_view path) noexcept;
/// Opens a directory.
///
///
/// \return a \ref file object representing a directory. The only
/// legal operations are \ref file::list_directory(),
-/// \ref file::fsync(), and \ref file::close().
+/// \ref file::flush(), and \ref file::close().
///
/// \relates file
-future<file> open_directory(sstring name);
+future<file> open_directory(std::string_view name) noexcept;
/// Creates a new directory.
///
/// \note
/// The directory is not guaranteed to be stable on disk, unless the
/// containing directory is sync'ed.
-future<> make_directory(sstring name, file_permissions permissions = file_permissions::default_dir_permissions);
+future<> make_directory(std::string_view name, file_permissions permissions = file_permissions::default_dir_permissions) noexcept;
/// Ensures a directory exists
///
/// The directory is not guaranteed to be stable on disk, unless the
/// containing directory is sync'ed.
/// If the directory exists, the provided permissions are not applied.
-future<> touch_directory(sstring name, file_permissions permissions = file_permissions::default_dir_permissions);
+future<> touch_directory(std::string_view name, file_permissions permissions = file_permissions::default_dir_permissions) noexcept;
/// Recursively ensures a directory exists
///
/// The provided permissions are applied only on the last component in the path, if it needs to be created,
/// if intermediate directories do not exist, they are created with the default_dir_permissions.
/// If any directory exists, the provided permissions are not applied.
-future<> recursive_touch_directory(sstring name, file_permissions permissions = file_permissions::default_dir_permissions);
+future<> recursive_touch_directory(std::string_view name, file_permissions permissions = file_permissions::default_dir_permissions) noexcept;
/// Synchronizes a directory to disk
///
/// directory.
///
/// \param name name of the directory to potentially create
-future<> sync_directory(sstring name);
+future<> sync_directory(std::string_view name) noexcept;
/// Removes (unlinks) a file or an empty directory
/// \note
/// The removal is not guaranteed to be stable on disk, unless the
/// containing directory is sync'ed.
-future<> remove_file(sstring name);
+future<> remove_file(std::string_view name) noexcept;
/// Renames (moves) a file.
///
/// \note
/// The rename is not guaranteed to be stable on disk, unless the
/// both containing directories are sync'ed.
-future<> rename_file(sstring old_name, sstring new_name);
+future<> rename_file(std::string_view old_name, std::string_view new_name) noexcept;
struct follow_symlink_tag { };
using follow_symlink = bool_class<follow_symlink_tag>;
/// Return stat information about a file.
///
/// \param name name of the file to return its stat information
-/// \param follow_symlink follow symbolic links.
+/// \param fs a follow_symlink flag to follow symbolic links.
///
/// \return stat_data of the file identified by name.
/// If name identifies a symbolic link then stat_data is returned either for the target of the link,
/// with follow_symlink::yes, or for the link itself, with follow_symlink::no.
-future<stat_data> file_stat(sstring name, follow_symlink fs = follow_symlink::yes);
+future<stat_data> file_stat(std::string_view name, follow_symlink fs = follow_symlink::yes) noexcept;
/// Return the size of a file.
///
/// Note that file_size of a symlink is NOT the size of the symlink -
/// which is the length of the pathname it contains -
/// but rather the size of the file to which it points.
-future<uint64_t> file_size(sstring name);
+future<uint64_t> file_size(std::string_view name) noexcept;
/// Check file access.
///
/// \param flags bit pattern containing type of access to check (read/write/execute or exists).
///
/// If only access_flags::exists is queried, returns true if the file exists, or false otherwise.
-/// Throws a compat::filesystem::filesystem_error exception if any error other than ENOENT is encountered.
+/// Throws a std::filesystem::filesystem_error exception if any error other than ENOENT is encountered.
///
/// If any of the access_flags (read/write/execute) is set, returns true if the file exists and is
/// accessible with the requested flags, or false if the file exists and is not accessible
/// as queried.
-/// Throws a compat::filesystem::filesystem_error exception if any error other than EACCES is encountered.
+/// Throws a std::filesystem::filesystem_error exception if any error other than EACCES is encountered.
/// Note that if any path component leading to the file is not searchable, the file is considered inaccessible
/// with the requested mode and false will be returned.
-future<bool> file_accessible(sstring name, access_flags flags);
+future<bool> file_accessible(std::string_view name, access_flags flags) noexcept;
/// check if a file exists.
///
/// \param name name of the file to check
-future<bool> file_exists(sstring name);
+future<bool> file_exists(std::string_view name) noexcept;
+
+/// Determine the type of a file (regular file, directory, etc.)
+///
+/// \param name name of the file for which type information is requested
+/// \param follow a follow_symlink flag that determines whether a trailing symbolic link should be followed or not
+///
+/// \return a engaged optional with the file type if lookup was successful; a disengaged optional
+/// if the file (or one of its parent directories) does not exist; an exceptional future on
+/// other errors.
+future<std::optional<directory_entry_type>> file_type(std::string_view name, follow_symlink follow = follow_symlink::yes) noexcept;
+
/// Creates a hard link for a file
///
/// \param oldpath existing file name
/// \param newpath name of link
///
-future<> link_file(sstring oldpath, sstring newpath);
+future<> link_file(std::string_view oldpath, std::string_view newpath) noexcept;
/// Changes the permissions mode of a file or directory
///
/// \param name name of the file ot directory to change
/// \param permissions permissions to set
///
-future<> chmod(sstring name, file_permissions permissions);
+future<> chmod(std::string_view name, file_permissions permissions) noexcept;
/// Return information about the filesystem where a file is located.
///
/// \param name name of the file to inspect
-future<fs_type> file_system_at(sstring name);
+future<fs_type> file_system_at(std::string_view name) noexcept;
/// Return space available to unprivileged users in filesystem where a file is located, in bytes.
///
/// \param name name of the file to inspect
-future<uint64_t> fs_avail(sstring name);
+future<uint64_t> fs_avail(std::string_view name) noexcept;
/// Return free space in filesystem where a file is located, in bytes.
///
/// \param name name of the file to inspect
-future<uint64_t> fs_free(sstring name);
+future<uint64_t> fs_free(std::string_view name) noexcept;
/// @}
}
projects / ceph.git / blobdiff