file.hh

/*
 * This file is open source software, licensed to you under the terms
 * of the Apache License, Version 2.0 (the "License").  See the NOTICE file
 * distributed with this work for additional information regarding copyright
 * ownership.  You may not use this file except in compliance with the License.
 *
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
/*
 * Copyright 2015 Cloudius Systems
 */
 
#pragma once
 
#include <seastar/util/std-compat.hh>
#include <seastar/core/coroutine.hh>
#include <seastar/coroutine/generator.hh>
#include <seastar/core/do_with.hh>
#include <seastar/core/stream.hh>
#include <seastar/core/sstring.hh>
#include <seastar/core/shared_ptr.hh>
#include <seastar/core/align.hh>
#include <seastar/core/io_priority_class.hh>
#include <seastar/core/file-types.hh>
#include <seastar/core/circular_buffer.hh>
#include <seastar/util/modules.hh>
#ifndef SEASTAR_MODULE
#include <sys/statvfs.h>
#include <sys/ioctl.h>
#include <linux/fs.h>
#include <sys/uio.h>
#include <unistd.h>
#include <chrono>
#include <concepts>
#include <cstdint>
#include <functional>
#include <optional>
#endif
 
namespace seastar {
 
SEASTAR_MODULE_EXPORT_BEGIN
 
 
struct directory_entry {
    sstring name;
    std::optional<directory_entry_type> type;
};
 
struct stat_data {
    uint64_t  device_id;      // ID of device containing file
    uint64_t  inode_number;   // Inode number
    uint64_t  mode;           // File type and mode
    directory_entry_type type;
    uint64_t  number_of_links;// Number of hard links
    uint64_t  uid;            // User ID of owner
    uint64_t  gid;            // Group ID of owner
    uint64_t  rdev;           // Device ID (if special file)
    uint64_t  size;           // Total size, in bytes
    uint64_t  block_size;     // Block size for filesystem I/O
    uint64_t  allocated_size; // Total size of allocated storage, in bytes
 
    std::chrono::system_clock::time_point time_accessed;  // Time of last content access
    std::chrono::system_clock::time_point time_modified;  // Time of last content modification
    std::chrono::system_clock::time_point time_changed;   // Time of last status change (either content or attributes)
};
 
struct file_open_options {
    uint64_t extent_allocation_size_hint = 1 << 20; 
    bool sloppy_size = false; 
    uint64_t sloppy_size_hint = 1 << 20; 
    file_permissions create_permissions = file_permissions::default_file_permissions; 
    bool append_is_unlikely = false; 
 
    // The fsxattr.fsx_extsize is 32-bit
    static constexpr uint64_t max_extent_allocation_size_hint = 1 << 31;
 
    // XFS ignores hints that are not aligned to the logical block size.
    // To fulfill the requirement, we ensure that hint is aligned to 128KB (best guess).
    static constexpr uint32_t min_extent_size_hint_alignment{128u << 10}; // 128KB
};
 
class file;
class file_impl;
class io_intent;
class file_handle;
class file_data_sink_impl;
class file_data_source_impl;
 
// A handle that can be transported across shards and used to
// create a dup(2)-like `file` object referring to the same underlying file
class file_handle_impl {
public:
    virtual ~file_handle_impl() = default;
    virtual std::unique_ptr<file_handle_impl> clone() const = 0;
    virtual shared_ptr<file_impl> to_file() && = 0;
};
 
class file_impl {
    friend class file;
protected:
    static file_impl* get_file_impl(file& f);
    unsigned _memory_dma_alignment = 4096;
    unsigned _disk_read_dma_alignment = 4096;
    unsigned _disk_write_dma_alignment = 4096;
    unsigned _disk_overwrite_dma_alignment = 4096;
    unsigned _read_max_length = 1u << 30;
    unsigned _write_max_length = 1u << 30;
public:
    virtual ~file_impl() {}
 
#if SEASTAR_API_LEVEL >= 7
    virtual future<size_t> write_dma(uint64_t pos, const void* buffer, size_t len, io_intent*) = 0;
    virtual future<size_t> write_dma(uint64_t pos, std::vector<iovec> iov, io_intent*) = 0;
    virtual future<size_t> read_dma(uint64_t pos, void* buffer, size_t len, io_intent*) = 0;
    virtual future<size_t> read_dma(uint64_t pos, std::vector<iovec> iov, io_intent*) = 0;
    virtual future<temporary_buffer<uint8_t>> dma_read_bulk(uint64_t offset, size_t range_size, io_intent*) = 0;
#else
    virtual future<size_t> write_dma(uint64_t pos, const void* buffer, size_t len, const io_priority_class& pc) = 0;
    virtual future<size_t> write_dma(uint64_t pos, std::vector<iovec> iov, const io_priority_class& pc) = 0;
    virtual future<size_t> read_dma(uint64_t pos, void* buffer, size_t len, const io_priority_class& pc) = 0;
    virtual future<size_t> read_dma(uint64_t pos, std::vector<iovec> iov, const io_priority_class& pc) = 0;
    virtual future<temporary_buffer<uint8_t>> dma_read_bulk(uint64_t offset, size_t range_size, const io_priority_class& pc) = 0;
 
    virtual future<size_t> write_dma(uint64_t pos, const void* buffer, size_t len, const io_priority_class& pc, io_intent*) {
        return write_dma(pos, buffer, len, pc);
    }
    virtual future<size_t> write_dma(uint64_t pos, std::vector<iovec> iov, const io_priority_class& pc, io_intent*) {
        return write_dma(pos, std::move(iov), pc);
    }
    virtual future<size_t> read_dma(uint64_t pos, void* buffer, size_t len, const io_priority_class& pc, io_intent*) {
        return read_dma(pos, buffer, len, pc);
    }
    virtual future<size_t> read_dma(uint64_t pos, std::vector<iovec> iov, const io_priority_class& pc, io_intent*) {
        return read_dma(pos, std::move(iov), pc);
    }
    virtual future<temporary_buffer<uint8_t>> dma_read_bulk(uint64_t offset, size_t range_size, const io_priority_class& pc, io_intent*) {
        return dma_read_bulk(offset, range_size, pc);
    }
#endif
 
    virtual future<> flush() = 0;
    virtual future<struct stat> stat() = 0;
    virtual future<> truncate(uint64_t length) = 0;
    virtual future<> discard(uint64_t offset, uint64_t length) = 0;
    virtual future<int> ioctl(uint64_t cmd, void* argp) noexcept;
    virtual future<int> ioctl_short(uint64_t cmd, void* argp) noexcept;
    virtual future<int> fcntl(int op, uintptr_t arg) noexcept;
    virtual future<int> fcntl_short(int op, uintptr_t arg) noexcept;
    virtual future<> allocate(uint64_t position, uint64_t length) = 0;
    virtual future<uint64_t> size() = 0;
    virtual future<> close() = 0;
    virtual std::unique_ptr<file_handle_impl> dup();
    virtual subscription<directory_entry> list_directory(std::function<future<> (directory_entry de)> next) = 0;
    // due to https://github.com/scylladb/seastar/issues/1913, we cannot use
    // buffered generator yet.
    virtual coroutine::experimental::generator<directory_entry> experimental_list_directory();
};
 
future<shared_ptr<file_impl>> make_file_impl(int fd, file_open_options options, int oflags, struct stat st) noexcept;
 
 
class file {
    shared_ptr<file_impl> _file_impl;
public:
    file() noexcept : _file_impl(nullptr) {}
 
    file(shared_ptr<file_impl> impl) noexcept
            : _file_impl(std::move(impl)) {}
 
    explicit file(file_handle&& handle) noexcept;
 
    explicit operator bool() const noexcept { return bool(_file_impl); }
 
    file(const file& x) = default;
    file(file&& x) noexcept : _file_impl(std::move(x._file_impl)) {}
    file& operator=(const file& x) noexcept = default;
    file& operator=(file&& x) noexcept = default;
 
    // O_DIRECT reading requires that buffer, offset, and read length, are
    // all aligned. Alignment of 4096 was necessary in the past, but no longer
    // is - 512 is usually enough; But we'll need to use BLKSSZGET ioctl to
    // be sure it is really enough on this filesystem. 4096 is always safe.
    // In addition, if we start reading in things outside page boundaries,
    // we will end up with various pages around, some of them with
    // overlapping ranges. Those would be very challenging to cache.
 
    uint64_t disk_read_dma_alignment() const noexcept {
        return _file_impl->_disk_read_dma_alignment;
    }
 
    uint64_t disk_write_dma_alignment() const noexcept {
        return _file_impl->_disk_write_dma_alignment;
    }
 
    uint64_t disk_overwrite_dma_alignment() const noexcept {
        return _file_impl->_disk_overwrite_dma_alignment;
    }
 
    uint64_t memory_dma_alignment() const noexcept {
        return _file_impl->_memory_dma_alignment;
    }
 
    size_t disk_read_max_length() const noexcept {
        return _file_impl->_read_max_length;
    }
 
    size_t disk_write_max_length() const noexcept {
        return _file_impl->_write_max_length;
    }
 
#if SEASTAR_API_LEVEL < 7
    template <typename CharType>
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<size_t>
    dma_read(uint64_t aligned_pos, CharType* aligned_buffer, size_t aligned_len, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_read_impl(aligned_pos, reinterpret_cast<uint8_t*>(aligned_buffer), aligned_len, internal::maybe_priority_class_ref(pc), intent);
    }
#endif
 
    template <typename CharType>
    future<size_t>
    dma_read(uint64_t aligned_pos, CharType* aligned_buffer, size_t aligned_len, io_intent* intent = nullptr) noexcept {
        return dma_read_impl(aligned_pos, reinterpret_cast<uint8_t*>(aligned_buffer), aligned_len, internal::maybe_priority_class_ref(), intent);
    }
 
#if SEASTAR_API_LEVEL < 7
    template <typename CharType>
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<temporary_buffer<CharType>> dma_read(uint64_t pos, size_t len, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_read_impl(pos, len, internal::maybe_priority_class_ref(pc), intent).then([] (temporary_buffer<uint8_t> t) {
            return temporary_buffer<CharType>(reinterpret_cast<CharType*>(t.get_write()), t.size(), t.release());
        });
    }
#endif
 
    template <typename CharType>
    future<temporary_buffer<CharType>> dma_read(uint64_t pos, size_t len, io_intent* intent = nullptr) noexcept {
        return dma_read_impl(pos, len, internal::maybe_priority_class_ref(), intent).then([] (temporary_buffer<uint8_t> t) {
            return temporary_buffer<CharType>(reinterpret_cast<CharType*>(t.get_write()), t.size(), t.release());
        });
    }
 
    class eof_error : public std::exception {};
 
#if SEASTAR_API_LEVEL < 7
    template <typename CharType>
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<temporary_buffer<CharType>>
    dma_read_exactly(uint64_t pos, size_t len, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_read_exactly_impl(pos, len, internal::maybe_priority_class_ref(pc), intent).then([] (temporary_buffer<uint8_t> t) {
            return temporary_buffer<CharType>(reinterpret_cast<CharType*>(t.get_write()), t.size(), t.release());
        });
    }
#endif
 
    template <typename CharType>
    future<temporary_buffer<CharType>>
    dma_read_exactly(uint64_t pos, size_t len, io_intent* intent = nullptr) noexcept {
        return dma_read_exactly_impl(pos, len, internal::maybe_priority_class_ref(), intent).then([] (temporary_buffer<uint8_t> t) {
            return temporary_buffer<CharType>(reinterpret_cast<CharType*>(t.get_write()), t.size(), t.release());
        });
    }
 
#if SEASTAR_API_LEVEL < 7
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<size_t> dma_read(uint64_t pos, std::vector<iovec> iov, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_read_impl(pos, std::move(iov), internal::maybe_priority_class_ref(pc), intent);
    }
#endif
 
    future<size_t> dma_read(uint64_t pos, std::vector<iovec> iov, io_intent* intent = nullptr) noexcept {
        return dma_read_impl(pos, std::move(iov), internal::maybe_priority_class_ref(), intent);
    }
 
#if SEASTAR_API_LEVEL < 7
    template <typename CharType>
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<size_t> dma_write(uint64_t pos, const CharType* buffer, size_t len, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_write_impl(pos, reinterpret_cast<const uint8_t*>(buffer), len, internal::maybe_priority_class_ref(pc), intent);
    }
#endif
 
    template <typename CharType>
    future<size_t> dma_write(uint64_t pos, const CharType* buffer, size_t len, io_intent* intent = nullptr) noexcept {
        return dma_write_impl(pos, reinterpret_cast<const uint8_t*>(buffer), len, internal::maybe_priority_class_ref(), intent);
    }
 
#if SEASTAR_API_LEVEL < 7
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<size_t> dma_write(uint64_t pos, std::vector<iovec> iov, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_write_impl(pos, std::move(iov), internal::maybe_priority_class_ref(pc), intent);
    }
#endif
 
    future<size_t> dma_write(uint64_t pos, std::vector<iovec> iov, io_intent* intent = nullptr) noexcept {
        return dma_write_impl(pos, std::move(iov), internal::maybe_priority_class_ref(), intent);
    }
 
    future<> flush() noexcept;
 
    future<struct stat> stat() noexcept;
 
    future<> truncate(uint64_t length) noexcept;
 
    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;
 
    [[deprecated("This API was removed from the kernel")]]
    future<> set_file_lifetime_hint(uint64_t hint) noexcept;
 
    future<> set_inode_lifetime_hint(uint64_t hint) noexcept;
 
    [[deprecated("This API was removed from the kernel")]]
    future<uint64_t> get_file_lifetime_hint() noexcept;
 
    future<uint64_t> get_inode_lifetime_hint() noexcept;
 
    future<uint64_t> size() const noexcept;
 
    future<> close() noexcept;
 
    subscription<directory_entry> list_directory(std::function<future<> (directory_entry de)> next);
 
    // due to https://github.com/scylladb/seastar/issues/1913, we cannot use
    // buffered generator yet.
    coroutine::experimental::generator<directory_entry> experimental_list_directory();
 
#if SEASTAR_API_LEVEL < 7
    template <typename CharType>
    [[deprecated("Use scheduling_groups and API level >= 7")]]
    future<temporary_buffer<CharType>>
    dma_read_bulk(uint64_t offset, size_t range_size, const io_priority_class& pc, io_intent* intent = nullptr) noexcept {
        return dma_read_bulk_impl(offset, range_size, internal::maybe_priority_class_ref(pc), intent).then([] (temporary_buffer<uint8_t> t) {
            return temporary_buffer<CharType>(reinterpret_cast<CharType*>(t.get_write()), t.size(), t.release());
        });
    }
#endif
 
    template <typename CharType>
    future<temporary_buffer<CharType>>
    dma_read_bulk(uint64_t offset, size_t range_size, io_intent* intent = nullptr) noexcept {
        return dma_read_bulk_impl(offset, range_size, internal::maybe_priority_class_ref(), intent).then([] (temporary_buffer<uint8_t> t) {
            return temporary_buffer<CharType>(reinterpret_cast<CharType*>(t.get_write()), t.size(), t.release());
        });
    }
 
    file_handle dup();
private:
    future<temporary_buffer<uint8_t>>
    dma_read_bulk_impl(uint64_t offset, size_t range_size, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<size_t>
    dma_write_impl(uint64_t pos, const uint8_t* buffer, size_t len, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<size_t>
    dma_write_impl(uint64_t pos, std::vector<iovec> iov, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<temporary_buffer<uint8_t>>
    dma_read_impl(uint64_t pos, size_t len, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<size_t>
    dma_read_impl(uint64_t aligned_pos, uint8_t* aligned_buffer, size_t aligned_len, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<size_t>
    dma_read_impl(uint64_t pos, std::vector<iovec> iov, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<temporary_buffer<uint8_t>>
    dma_read_exactly_impl(uint64_t pos, size_t len, internal::maybe_priority_class_ref pc, io_intent* intent) noexcept;
 
    future<uint64_t> get_lifetime_hint_impl(int op) noexcept;
    future<> set_lifetime_hint_impl(int op, uint64_t hint) noexcept;
 
    friend class file_impl;
    friend class file_data_sink_impl;
    friend class file_data_source_impl;
};
 
template <std::invocable<file&> Func>
requires std::is_nothrow_move_constructible_v<Func>
auto with_file(future<file> file_fut, Func func) noexcept {
    static_assert(std::is_nothrow_move_constructible_v<Func>, "Func's move constructor must not throw");
    return file_fut.then([func = std::move(func)] (file f) mutable {
        return do_with(std::move(f), [func = std::move(func)] (file& f) mutable {
            return futurize_invoke(func, f).finally([&f] {
                return f.close();
            });
        });
    });
}
 
template <std::invocable<file&> Func>
requires std::is_nothrow_move_constructible_v<Func>
auto with_file_close_on_failure(future<file> file_fut, Func func) noexcept {
    static_assert(std::is_nothrow_move_constructible_v<Func>, "Func's move constructor must not throw");
    return file_fut.then([func = std::move(func)] (file f) mutable {
        return do_with(std::move(f), [func = std::move(func)] (file& f) mutable {
            return futurize_invoke(std::move(func), f).then_wrapped([&f] (auto ret) mutable {
                if (!ret.failed()) {
                    return ret;
                }
                return ret.finally([&f] {
                    // If f.close() fails, return that as nested exception.
                    return f.close();
                });
             });
         });
     });
}
 
 
class file_handle {
    std::unique_ptr<file_handle_impl> _impl;
private:
    explicit file_handle(std::unique_ptr<file_handle_impl> impl) : _impl(std::move(impl)) {}
public:
    file_handle(const file_handle&);
    file_handle(file_handle&&) noexcept;
    file_handle& operator=(const file_handle&);
    file_handle& operator=(file_handle&&) noexcept;
    file to_file() const &;
    file to_file() &&;
 
    friend class file;
};
 
 
class cancelled_error : public std::exception {
public:
    virtual const char* what() const noexcept {
        return "cancelled";
    }
};
 
SEASTAR_MODULE_EXPORT_END
 
}