database.hpp

Go to the documentation of this file.

//===- include/pstore/core/database.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_CORE_DATABASE_HPP
#define PSTORE_CORE_DATABASE_HPP

#include "pstore/adt/sstring_view.hpp"
#include "pstore/core/file_header.hpp"
#include "pstore/core/hamt_map_fwd.hpp"
#include "pstore/core/storage.hpp"
#include "pstore/core/vacuum_intf.hpp"
#include "pstore/os/shared_memory.hpp"
#include "pstore/support/head_revision.hpp"

namespace pstore {

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

    class heartbeat;

    class database {
    public:
        enum class access_mode { read_only, writable, writeable_no_create };

        explicit database (std::string const & path, access_mode am,
                           bool access_tick_enabled = true);

        template <typename File>
        explicit database (std::shared_ptr<File> file,
                           std::unique_ptr<system_page_size_interface> && page_size,
                           std::unique_ptr<region::factory> && region_factory,
                           bool access_tick_enabled = true);

        template <typename File>
        explicit database (std::shared_ptr<File> file, bool access_tick_enabled = true)
                : database (file, std::make_unique<system_page_size> (),
                            region::get_factory (file, storage::full_region_size,
                                                 storage::min_region_size),
                            access_tick_enabled) {}

        database (database &&) = delete;
        database (database const &) = delete;

        virtual ~database () noexcept;

        database & operator= (database &&) = delete;
        database & operator= (database const &) = delete;


        std::uint64_t size () const noexcept { return size_.logical_size (); }

        std::string path () const { return storage_.file ()->path (); }

        file::file_base const * file () const { return storage_.file (); }
        file::file_base * file () { return storage_.file (); }

        static void build_new_store (file::file_base & file);

        void sync (unsigned revision = head_revision);

        typed_address<trailer> older_revision_footer_pos (unsigned revision) const;

        static constexpr bool small_files_enabled () noexcept {
            return region::small_files_enabled ();
        }

        std::unique_lock<file::range_lock> * upgrade_to_write_lock ();
        std::time_t latest_time () const {
            auto lt = this->file ()->latest_time ();
#ifdef _WIN32
            lt = std::max (lt, this->get_shared ()->time.load ());
#endif
            return lt;
        }
        bool is_writable () const noexcept { return storage_.file ()->is_writable (); }

        std::shared_ptr<void const> getro (address const addr, std::size_t const size) const {
            return this->get (addr, size, true /*initialized*/, false /*writable*/);
        }

        template <typename T,
                  typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
        std::shared_ptr<T const> getro (extent<T> const & ex) const {
            if (ex.addr.to_address ().absolute () % alignof (T) != 0) {
                raise (error_code::bad_alignment);
            }
            // Note that ex.size specifies the size in bytes of the data to be loaded, not the
            // number of elements of type T. For this reason we call the plain address version of
            // getro().
            return std::static_pointer_cast<T const> (this->getro (ex.addr.to_address (), ex.size));
        }

        template <typename T,
                  typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
        std::shared_ptr<T const> getro (typed_address<T> const addr) const {
            return this->getro (addr, std::size_t{1});
        }

        template <typename T,
                  typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
        std::shared_ptr<T const> getro (typed_address<T> const addr,
                                        std::size_t const elements) const {
            if (addr.to_address ().absolute () % alignof (T) != 0) {
                raise (error_code::bad_alignment);
            }
            return std::static_pointer_cast<T const> (
                this->getro (addr.to_address (), sizeof (T) * elements));
        }


        std::shared_ptr<void> getrw (address const addr, std::size_t const size) {
            return std::const_pointer_cast<void> (
                this->get (addr, size, true /*initialized*/, true /*writable*/));
        }

        template <typename T,
                  typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
        std::shared_ptr<T> getrw (extent<T> const & ex) {
            if (ex.addr.to_address ().absolute () % alignof (T) != 0) {
                raise (error_code::bad_alignment);
            }
            // Note that ex.size specifies the size in bytes of the data to be loaded, not the
            // number of elements of type T. For this reason we call the plain address version of
            // getro().
            return std::static_pointer_cast<T> (this->getrw (ex.addr.to_address (), ex.size));
        }

        template <typename T,
                  typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
        std::shared_ptr<T> getrw (typed_address<T> addr) {
            return this->getrw<T> (addr, std::size_t{1});
        }

        template <typename T,
                  typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
        std::shared_ptr<T> getrw (typed_address<T> const addr, std::size_t const elements) {
            if (addr.to_address ().absolute () % alignof (T) != 0) {
                raise (error_code::bad_alignment);
            }
            return std::static_pointer_cast<T> (
                this->getrw (addr.to_address (), sizeof (T) * elements));
        }

        // (Virtual for mocking.)
        virtual auto get (address addr, std::size_t size, bool initialized, bool writable) const
            -> std::shared_ptr<void const>;

        enum class vacuum_mode {
            disabled,
            immediate,
            background,
        };
        void set_vacuum_mode (vacuum_mode const mode) noexcept { vacuum_mode_ = mode; }
        vacuum_mode get_vacuum_mode () const noexcept { return vacuum_mode_; }

        class storage const & storage () const noexcept {
            return storage_;
        }

        void close ();

        header const & get_header () const noexcept { return *header_; }
        typed_address<trailer> footer_pos () const noexcept { return size_.footer_pos (); }

        unsigned get_current_revision () const { return get_footer ()->a.generation.load (); }

        std::string get_sync_name () const {
            PSTORE_ASSERT (sync_name_.length () > 0);
            return sync_name_;
        }

        std::string shared_memory_name () const { return this->get_sync_name () + ".pst"; }

        virtual address allocate (std::uint64_t bytes, unsigned align);

        virtual void truncate (std::uint64_t size);

        void set_new_footer (typed_address<trailer> new_footer_pos);

        void protect (address const first, address const last) { storage_.protect (first, last); }

        static bool crc_checks_enabled ();

        void set_id (uuid const & id) noexcept { header_->set_id (id); }

        shared const * get_shared () const;
        shared * get_shared ();

        //  \warning This function is dangerous. It returns a non-const index from a const
        //  database.
        std::shared_ptr<index::index_base> &
        get_mutable_index (enum pstore::trailer::indices const which) const {
            return indices_[static_cast<std::underlying_type<decltype (which)>::type> (which)];
        }
        std::shared_ptr<trailer const> get_footer () const {
            return this->getro (this->footer_pos ());
        }

    private:
        class storage storage_;
        std::shared_ptr<header> header_;
        file::range_lock range_lock_;
        std::unique_lock<file::range_lock> lock_;

        vacuum_mode vacuum_mode_ = vacuum_mode::disabled;
        bool modified_ = false;
        bool closed_ = false;

        class sizes {
        public:
            sizes () noexcept = default;
            constexpr explicit sizes (typed_address<trailer> const footer_pos) noexcept
                    : footer_pos_{footer_pos}
                    , logical_{footer_pos_.absolute () + sizeof (trailer)} {}

            typed_address<trailer> footer_pos () const noexcept { return footer_pos_; }
            std::uint64_t logical_size () const noexcept { return logical_; }

            void update_footer_pos (typed_address<trailer> const new_footer_pos) noexcept {
                PSTORE_ASSERT (new_footer_pos.absolute () >= leader_size);
                footer_pos_ = new_footer_pos;
                logical_ = std::max (logical_, footer_pos_.absolute () + sizeof (trailer));
            }

            void update_logical_size (std::uint64_t const new_logical_size) noexcept {
                PSTORE_ASSERT (new_logical_size >= footer_pos_.absolute () + sizeof (trailer));
                logical_ = std::max (logical_, new_logical_size);
            }

            void truncate_logical_size (std::uint64_t const new_logical_size) noexcept {
                PSTORE_ASSERT (new_logical_size >= footer_pos_.absolute () + sizeof (trailer));
                logical_ = new_logical_size;
            }

        private:
            typed_address<trailer> footer_pos_ = typed_address<trailer>::null ();

            std::uint64_t logical_ = 0;
        };
        sizes size_;

        mutable std::array<std::shared_ptr<index::index_base>,
                           static_cast<unsigned> (trailer::indices::last)>
            indices_;
        std::string sync_name_;
        static constexpr auto const sync_name_length = std::size_t{20};


        shared_memory<shared> shared_;
        std::shared_ptr<heartbeat> heartbeat_;

        void clear_index_cache ();

        address first_writable_address () const;

        auto get_spanning (address addr, std::size_t size, bool initialized, bool writable) const
            -> std::shared_ptr<void const>;



        template <typename File>
        static typed_address<trailer> get_footer_pos (File & file);

        static std::string build_sync_name (header const & header);


        void map_bytes (std::uint64_t new_size);

        static auto open (std::string const & path, access_mode am)
            -> std::shared_ptr<file::file_handle>;

        void finish_init (bool access_tick_enabled);
    };


    // (ctor)
    // ~~~~~~
    template <typename File>
    database::database (std::shared_ptr<File> file,
                        std::unique_ptr<system_page_size_interface> && page_size,
                        std::unique_ptr<region::factory> && region_factory,
                        bool const access_tick_enabled)
            : storage_{std::move (file), std::move (page_size), std::move (region_factory)}
            , size_{database::get_footer_pos (*file)} {

        this->finish_init (access_tick_enabled);
    }


    // get_footer_pos [static]
    // ~~~~~~~~~~~~~~
    template <typename File>
    auto database::get_footer_pos (File & file) -> typed_address<trailer> {
        static_assert (std::is_base_of<file::file_base, File>::value,
                       "File type must be derived from file::file_base");
        PSTORE_ASSERT (file.is_open ());

        std::aligned_storage<sizeof (header), alignof (header)>::type header_storage{};
        auto h = reinterpret_cast<header *> (&header_storage);
        file.seek (0);
        file.read (h);

        auto const dtor = [] (header * const p) { p->~header (); };
        std::unique_ptr<header, decltype (dtor)> deleter (h, dtor);

#if PSTORE_SIGNATURE_CHECKS_ENABLED
        if (h->a.signature1 != header::file_signature1 ||
            h->a.signature2 != header::file_signature2) {
            raise (error_code::header_corrupt, file.path ());
        }
#endif
        if (h->a.header_size != sizeof (class header) || h->a.version[0] != header::major_version ||
            h->a.version[1] != header::minor_version) {
            raise (error_code::header_version_mismatch, file.path ());
        }
        if (!h->is_valid ()) {
            raise (pstore::error_code::header_corrupt, file.path ());
        }

        typed_address<trailer> const result = h->footer_pos.load ();
        std::uint64_t const footer_offset = result.absolute ();
        std::uint64_t const file_size = file.size ();
        if (footer_offset < leader_size || file_size < leader_size + sizeof (trailer) ||
            footer_offset > file_size - sizeof (trailer)) {
            raise (error_code::header_corrupt, file.path ());
        }
        return result;
    }

} // namespace pstore

#endif // PSTORE_CORE_DATABASE_HPP