file.hpp

Go to the documentation of this file.

//===- include/pstore/os/file.hpp -------------------------*- mode: C++ -*-===//
//*   __ _ _       *
//*  / _(_) | ___  *
//* | |_| | |/ _ \ *
//* |  _| | |  __/ *
//* |_| |_|_|\___| *
//*                *
//===----------------------------------------------------------------------===//
//
// Part of the pstore project, under the Apache License v2.0 with LLVM Exceptions.
// See https://github.com/SNSystems/pstore/blob/master/LICENSE.txt for license
// information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef PSTORE_OS_FILE_HPP
#define PSTORE_OS_FILE_HPP

#include <cstdint>
#include <ctime>
#include <functional>

#ifdef _WIN32
#    define NOMINMAX
#    define WIN32_LEAN_AND_MEAN
#    include <Windows.h>
#endif

#include "pstore/adt/error_or.hpp"
#include "pstore/support/array_elements.hpp"
#include "pstore/support/error.hpp"

namespace pstore {

    class memory_mapper;
    class in_memory_mapper;

    namespace file {
        namespace details {

            // name from template
            // ~~~~~~~~~~~~~~~~~~
            template <typename RandomGenerator>
            std::string name_from_template (std::string const & tmpl, RandomGenerator rng) {
                // Walk backwards looking for the start of the sequence of 'X'
                // characters that form the end of the template string.
                auto const it = std::find_if (tmpl.rbegin (), tmpl.rend (),
                                              [] (char const c) { return c != 'X'; });
                // Build the result string starting from the non-template characters.
                std::string path;
                path.reserve (tmpl.length ());
                std::copy (tmpl.begin (), it.base (), std::back_inserter (path));

                // Replace the sequence of 'X's with random characters.
                auto num_x = std::distance (it.base (), tmpl.end ());
                while (num_x--) {
                    static char const alphabet[] = "abcdefghijklmnopqrstuvwxyz0123456789_";
                    static constexpr auto length =
                        static_cast<unsigned> (array_elements (alphabet)) - 1U;
                    auto const index = rng (length);
                    PSTORE_ASSERT (index >= 0 && index < length);
                    path.push_back (alphabet[index]);
                }
                PSTORE_ASSERT (path.length () == tmpl.length ());
                return path;
            }

            // split
            // ~~~~~
            template <typename WidthType, typename PointeeType, typename Function>
            std::size_t split (PointeeType * buffer, std::size_t size, Function const & function) {
                PSTORE_ASSERT (buffer != nullptr);

                static_assert (sizeof (PointeeType) == sizeof (std::uint8_t),
                               "PointeeType must be a byte wide type");
                static_assert (sizeof (std::size_t) >= sizeof (WidthType),
                               "WidthType must not be wider than size_t");
                static std::size_t const max = std::numeric_limits<WidthType>::max ();
                std::size_t result = 0;
                while (size > 0) {
                    auto const chunk_size = static_cast<WidthType> (std::min (max, size));
                    result += function (buffer, chunk_size);
                    buffer += chunk_size;
                    size -= chunk_size;
                }
                return result;
            }

            template <typename WidthType, typename Function>
            std::size_t split (void * const buffer, std::size_t const size,
                               Function const & function) {
                return split<WidthType> (static_cast<std::uint8_t *> (buffer), size, function);
            }
            template <typename WidthType, typename Function>
            std::size_t split (void const * const buffer, std::size_t const size,
                               Function const & function) {
                return split<WidthType> (static_cast<std::uint8_t const *> (buffer), size,
                                         function);
            }

        } // end namespace details


        class system_error : public std::system_error {
        public:
            system_error (std::error_code code, std::string const & user_message, std::string path);
            system_error (std::error_code code, gsl::czstring user_message, std::string path);

            system_error (system_error const &) = default;
            system_error (system_error &&) = default;

            ~system_error () noexcept override;

            system_error & operator= (system_error const &) = default;
            system_error & operator= (system_error &&) = default;

            std::string const & path () const noexcept { return path_; }

        private:
            std::string path_;

            template <typename MessageStringType>
            std::string message (MessageStringType const & user_message, std::string const & path);
        };


        class file_base {
        public:
            file_base (file_base &&) noexcept = default;
            file_base (file_base const &) = default;
            virtual ~file_base () noexcept;

            file_base & operator= (file_base &&) noexcept = default;
            file_base & operator= (file_base const &) = default;

            virtual bool is_open () const noexcept = 0;
            virtual void close () = 0;

            virtual bool is_writable () const noexcept = 0;

            virtual std::string path () const = 0;

            virtual void seek (std::uint64_t position) = 0;

            virtual std::uint64_t tell () = 0;

            virtual std::time_t latest_time () const = 0;


            template <typename SpanType, typename = typename std::enable_if<std::is_standard_layout<
                                             typename SpanType::element_type>::value>::type>
            std::size_t read_span (SpanType const & s) {
                auto const size = s.size_bytes ();
                PSTORE_ASSERT (size >= 0);
                using utype = typename std::make_unsigned<decltype (size)>::type;
                return this->read_buffer (s.data (), static_cast<utype> (s.size_bytes ()));
            }

            template <typename T,
                      typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
            void read (T * const t) {
                PSTORE_ASSERT (t != nullptr);
                if (this->read_buffer (t, sizeof (T)) != sizeof (T)) {
                    raise (error_code::did_not_read_number_of_bytes_requested);
                }
            }

            template <typename SpanType, typename = typename std::enable_if<std::is_standard_layout<
                                             typename SpanType::element_type>::value>::type>
            void write_span (SpanType const & s) {
                auto const bytes = s.size_bytes ();
                PSTORE_ASSERT (bytes >= 0);
                auto const ubytes =
                    static_cast<typename std::make_unsigned<decltype (bytes)>::type> (bytes);
                this->write_buffer (s.data (), ubytes);
            }

            template <typename T,
                      typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
            void write (T const & t) {
                this->write_buffer (&t, sizeof (T));
            }


            virtual std::uint64_t size () = 0;
            virtual void truncate (std::uint64_t size) = 0;


            enum class blocking_mode {
                non_blocking, 
                blocking,     
            };
            enum class lock_kind {
                shared_read,     
                exclusive_write, 
            };

            virtual bool lock (std::uint64_t offset, std::size_t size, lock_kind lt,
                               blocking_mode bl) = 0;

            virtual void unlock (std::uint64_t offset, std::size_t size) = 0;

        protected:
            file_base () noexcept = default;


            virtual std::size_t read_buffer (gsl::not_null<void *> buffer, std::size_t nbytes) = 0;

            virtual void write_buffer (gsl::not_null<void const *> buffer, std::size_t nbytes) = 0;

        };


        //*                                _            _      *
        //*   _ __ __ _ _ __   __ _  ___  | | ___   ___| | __  *
        //*  | '__/ _` | '_ \ / _` |/ _ \ | |/ _ \ / __| |/ /  *
        //*  | | | (_| | | | | (_| |  __/ | | (_) | (__|   <   *
        //*  |_|  \__,_|_| |_|\__, |\___| |_|\___/ \___|_|\_\  *
        //*                   |___/                            *

        class range_lock {
        public:
            range_lock () noexcept = default;
            range_lock (file_base * const file, std::uint64_t offset, std::size_t size,
                        file_base::lock_kind kind) noexcept;
            range_lock (range_lock const & other) = delete;
            range_lock (range_lock && other) noexcept;

            ~range_lock () noexcept;

            range_lock & operator= (range_lock && other) noexcept;
            range_lock & operator= (range_lock const &) = delete;

            bool lock ();

            bool try_lock ();

            void unlock ();

            file_base * file () noexcept { return file_; }
            file_base const * file () const noexcept { return file_; }

            std::uint64_t offset () const noexcept { return offset_; }
            std::size_t size () const noexcept { return size_; }
            file_base::lock_kind kind () const noexcept { return kind_; }
            bool is_locked () const noexcept { return locked_; }

        private:
            file_base * file_ = nullptr;
            std::uint64_t offset_ = 0U;
            std::size_t size_ = 0U;
            file_base::lock_kind kind_ = file_base::lock_kind::shared_read;
            bool locked_ = false;

            bool lock_impl (file_base::blocking_mode mode);

#ifdef PSTORE_HAVE_IS_TRIVIALLY_COPYABLE
            static_assert (
                std::is_trivially_copyable<decltype (file_)>::value,
                "file_ is not trivially copyable: use std::move() in move ctor and assign");
            static_assert (
                std::is_trivially_copyable<decltype (offset_)>::value,
                "offset_ is not trivially copyable: use std::move() in move ctor and assign");
            static_assert (
                std::is_trivially_copyable<decltype (size_)>::value,
                "size_ is not trivially copyable: use std::move() in move ctor and assign");
            static_assert (
                std::is_trivially_copyable<decltype (kind_)>::value,
                "kind_ is not trivially copyable: use std::move() in move ctor and assign");
            static_assert (
                std::is_trivially_copyable<decltype (locked_)>::value,
                "locked_ is not trivially copyable: use std::move() in move ctor and assign");
#endif // PSTORE_HAVE_IS_TRIVIALLY_COPYABLE
        };



        //*   _                                                     *
        //*  (_)_ __    _ __ ___   ___ _ __ ___   ___  _ __ _   _   *
        //*  | | '_ \  | '_ ` _ \ / _ \ '_ ` _ \ / _ \| '__| | | |  *
        //*  | | | | | | | | | | |  __/ | | | | | (_) | |  | |_| |  *
        //*  |_|_| |_| |_| |_| |_|\___|_| |_| |_|\___/|_|   \__, |  *
        //*                                                 |___/   *
        class in_memory final : public file_base {
        public:
            using memory_mapper = pstore::in_memory_mapper;

            in_memory (std::shared_ptr<void> const & buffer, std::uint64_t const length,
                       std::uint64_t const eof = 0, bool const writable = true) noexcept
                    : buffer_ (std::static_pointer_cast<std::uint8_t> (buffer))
                    , length_ (length)
                    , eof_ (eof)
                    , writable_ (writable) {

                PSTORE_ASSERT (buffer != nullptr);
                PSTORE_ASSERT (eof <= length);
            }

            void close () override {}
            bool is_open () const noexcept override { return true; }
            bool is_writable () const noexcept override { return writable_; }
            std::string path () const override;

            void seek (std::uint64_t position) override;
            std::uint64_t tell () override { return pos_; }

            std::uint64_t size () override { return eof_; }
            void truncate (std::uint64_t size) override;
            std::time_t latest_time () const override;


            bool lock (std::uint64_t const /*offset*/, std::size_t const /*size*/,
                       lock_kind const /*lt*/, blocking_mode const /*bl*/) override {
                return true;
            }
            void unlock (std::uint64_t const /*offset*/, std::size_t const /*size*/) override {}

            std::shared_ptr<void> data () { return buffer_; }

            std::size_t read_buffer (gsl::not_null<void *> buffer, std::size_t nbytes) override;

            void write_buffer (gsl::not_null<void const *> ptr, std::size_t nbytes) override;

        private:
            std::shared_ptr<std::uint8_t> buffer_;

            std::uint64_t const length_;

            std::uint64_t eof_;

            bool writable_;

            std::uint64_t pos_ = UINT64_C (0);

            void check_writable () const;
        };


        //*    __ _ _        _                     _ _        *
        //*   / _(_) | ___  | |__   __ _ _ __   __| | | ___   *
        //*  | |_| | |/ _ \ | '_ \ / _` | '_ \ / _` | |/ _ \  *
        //*  |  _| | |  __/ | | | | (_| | | | | (_| | |  __/  *
        //*  |_| |_|_|\___| |_| |_|\__,_|_| |_|\__,_|_|\___|  *
        //*                                                   *
        class file_handle final : public file_base {
        public:
            using memory_mapper = pstore::memory_mapper;

            enum class create_mode {
                create_new,    
                open_existing, 
                open_always 
            };

            enum class present_mode {
                allow_not_found,

                must_exist
            };
            enum class writable_mode {
                read_only,
                read_write,
            };

            struct unique {};
            struct temporary {};


            file_handle () = default;
            explicit file_handle (std::string path) noexcept
                    : path_{std::move (path)} {}
            file_handle (file_handle const &) = delete;
            file_handle (file_handle && other) noexcept;

            ~file_handle () noexcept override;

            file_handle & operator= (file_handle && rhs) noexcept;
            file_handle & operator= (file_handle const &) = delete;


            void open (create_mode create, writable_mode writable,
                       present_mode present = present_mode::allow_not_found);
            void open (unique, std::string const & directory);

            void open (temporary const t) {
                return open (t, file_handle::get_temporary_directory ());
            }
            void open (temporary, std::string const & directory);


            static std::string get_temporary_directory ();

            bool is_open () const noexcept override { return file_ != invalid_oshandle; }
            bool is_writable () const noexcept override { return is_writable_; }
            std::string path () const override { return path_; }

            void close () override;

            void seek (std::uint64_t position) override;
            std::uint64_t tell () override;
            std::uint64_t size () override;
            void truncate (std::uint64_t size) override;
            bool rename (std::string const & new_name);

            std::time_t latest_time () const override;

            bool lock (std::uint64_t offset, std::size_t size, lock_kind kind,
                       blocking_mode block) override;
            void unlock (std::uint64_t offset, std::size_t size) override;

#ifdef _WIN32
            using oshandle = HANDLE;
            // TODO: making invalid_oshandle constexpr results in it having the value 0 (rather than
            // -1).
            static oshandle const invalid_oshandle;
#else
            using oshandle = int;
            static constexpr oshandle invalid_oshandle = -1;
#endif

            oshandle raw_handle () noexcept { return file_; }

        private:
            std::size_t read_buffer (gsl::not_null<void *> buffer, std::size_t nbytes) override;
            void write_buffer (gsl::not_null<void const *> buffer, std::size_t nbytes) override;
            void ensure_open ();
            static error_or<oshandle> close_noex (oshandle const file);

#ifdef _WIN32
#else
            static int lock_reg (int fd, int cmd, short type, off_t offset, short whence,
                                 off_t len);
#endif
            std::string path_ = "<unknown>";
            oshandle file_ = invalid_oshandle;
            bool is_writable_ = false;

#ifdef PSTORE_HAVE_IS_TRIVIALLY_COPYABLE
            static_assert (
                std::is_trivially_copyable<decltype (file_)>::value,
                "file_ is not trivially copyable: use std::move() in rvalue ref ctor and assign");
            static_assert (std::is_trivially_copyable<decltype (is_writable_)>::value,
                           "is_writable_ is not trivially copyable: use std::move() in rvalue ref "
                           "ctor and assign");
#endif // PSTORE_HAVE_IS_TRIVIALLY_COPYABLE
        };

        // ensure_open
        // ~~~~~~~~~~~
        inline void file_handle::ensure_open () {
            if (!this->is_open ()) {
                raise (std::errc::bad_file_descriptor);
            }
        }

        std::ostream & operator<< (std::ostream & os, file_handle const & fh);


        //*       _      _      _              _                      *
        //*    __| | ___| | ___| |_ ___ _ __  | |__   __ _ ___  ___   *
        //*   / _` |/ _ \ |/ _ \ __/ _ \ '__| | '_ \ / _` / __|/ _ \  *
        //*  | (_| |  __/ |  __/ ||  __/ |    | |_) | (_| \__ \  __/  *
        //*   \__,_|\___|_|\___|\__\___|_|    |_.__/ \__,_|___/\___|  *
        //*                                                           *
        class deleter_base {
        public:
            using unlink_proc = std::function<void (std::string const &)>;

            virtual ~deleter_base () noexcept;

            // No copying, moving, or assignment
            deleter_base (deleter_base const &) = delete;
            deleter_base (deleter_base &&) noexcept = delete;
            deleter_base & operator= (deleter_base const &) = delete;
            deleter_base & operator= (deleter_base &&) noexcept = delete;

            void unlink ();

            void release () noexcept { released_ = true; }

        protected:
            explicit deleter_base (std::string path, unlink_proc unlinker);

        private:
            std::string path_;

            unlink_proc unlinker_;

            bool released_ = false;
        };


        bool exists (std::string const & path);

        void unlink (std::string const & path, bool allow_noent = false);

    } // end namespace file
} // end namespace pstore

#if defined(_WIN32)
#    include "file_win32.hpp"
#else
#    include "file_posix.hpp"
#endif

#endif // PSTORE_OS_FILE_HPP