buf0dblwr.h

Go to the documentation of this file.

/*****************************************************************************
 
Copyright (c) 1995, 2026, Oracle and/or its affiliates.
 
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License, version 2.0, as published by the
Free Software Foundation.
 
This program is designed to work with certain software (including
but not limited to OpenSSL) that is licensed under separate terms,
as designated in a particular file or component or in included license
documentation.  The authors of MySQL hereby grant you an additional
permission to link the program and your derivative works with the
separately licensed software that they have either included with
the program or referenced in the documentation.
 
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
for more details.
 
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
 
*****************************************************************************/
 
/** @file include/buf0dblwr.h
 Doublewrite buffer module
 
 Created 2011/12/19 Inaam Rana
 *******************************************************/
 
#ifndef buf0dblwr_h
#define buf0dblwr_h
 
#include "buf0types.h"
#include "fil0fil.h"
#include "log0recv.h"
#include "ut0byte.h"
 
/** Size of the doublewrite block in pages. */
#define DBLWR_V1_EXTENT_SIZE FSP_EXTENT_SIZE
 
/** Offset of the doublewrite buffer header on the trx system header page.  */
#define TRX_SYS_DBLWR_V1 (UNIV_PAGE_SIZE - 200)
 
/** 4-byte ver number which shows if we have created the doublewrite buffer. */
constexpr ulint DBLWR_VER = FSEG_HEADER_SIZE;
 
/** Page number of the first page in the first sequence of 64 (=
FSP_EXTENT_SIZE) consecutive pages in the doublewrite buffer. */
constexpr ulint DBLWR_V1_BLOCK1 = (4 + FSEG_HEADER_SIZE);
 
/** Page number of the first page in the second sequence of 64 consecutive
pages in the doublewrite buffer. */
constexpr ulint DBLWR_V1_BLOCK2 = (8 + FSEG_HEADER_SIZE);
 
namespace dblwr {
 
/** IO buffer in UNIV_PAGE_SIZE units and aligned on UNIV_PAGE_SIZE */
struct Buffer {
  /** Constructor
  @param[in]    n_pages                 Number of pages to create */
  explicit Buffer(size_t n_pages) noexcept
      : Buffer(n_pages, univ_page_size.physical()) {}
 
  /** Constructor
  @param[in]   n_pages   Number of pages to create
  @param[in]   phy_size  physical page size. */
  explicit Buffer(size_t n_pages, uint32_t phy_size) noexcept
      : m_phy_size(phy_size), m_n_bytes(n_pages * phy_size) {
    ut_a(n_pages > 0);
    m_ptr = static_cast<byte *>(ut::aligned_zalloc(m_n_bytes, phy_size));
 
    m_next = m_ptr;
  }
 
  /** Destructor */
  ~Buffer() noexcept {
    ut::aligned_free(m_ptr);
    m_ptr = nullptr;
  }
 
  /** Add the contents of ptr up to n_bytes to the buffer.
  @return false if it won't fit. Nothing is copied if it won't fit. */
  bool append(const void *ptr, size_t n_bytes) noexcept {
    ut_a(m_next >= m_ptr && m_next <= m_ptr + m_n_bytes);
 
    if (m_next + m_phy_size > m_ptr + m_n_bytes) {
      return false;
    }
 
    memcpy(m_next, ptr, n_bytes);
    m_next += m_phy_size;
 
    return true;
  }
 
  /** @return the start of the buffer to write from. */
  byte *begin() noexcept { return m_ptr; }
 
  /** @return the start of the buffer to write from. */
  const byte *begin() const noexcept { return m_ptr; }
 
  /** @return the size of of the buffer to write. */
  size_t size() const noexcept {
    ut_a(m_next >= m_ptr);
    return std::ptrdiff_t(m_next - m_ptr);
  }
 
  /** @return the capacity of the buffer in bytes. */
  size_t capacity() const noexcept { return m_n_bytes; }
 
  /** @return true if the buffer is empty. */
  bool empty() const noexcept { return size() == 0; }
 
  /** Empty the buffer. */
  void clear() noexcept { m_next = m_ptr; }
 
  /** Page size on disk (aka physical page size). */
  uint32_t m_phy_size;
 
  /** Write buffer used in writing to the doublewrite buffer,
  aligned to an address divisible by UNIV_PAGE_SIZE (which is
  required by Windows AIO) */
  byte *m_ptr{};
 
  /** Start of  next write to the buffer. */
  byte *m_next{};
 
  /** Size of the unaligned (raw) buffer. */
  const size_t m_n_bytes{};
 
  // Disable copying
  Buffer(const Buffer &) = delete;
  Buffer(Buffer &&) = delete;
  Buffer &operator=(Buffer &&) = delete;
  Buffer &operator=(const Buffer &) = delete;
};
 
}  // namespace dblwr
 
#ifndef UNIV_HOTBACKUP
 
// Forward declaration
class buf_page_t;
class Double_write;
 
namespace dblwr {
 
/** Double write files location. */
extern std::string dir;
 
#ifdef UNIV_DEBUG
/** Crash the server after writing this page to the data file. */
extern page_id_t Force_crash;
#endif /* UNIV_DEBUG */
 
/** Startup the background thread(s) and create the instance.
@return DB_SUCCESS or error code */
[[nodiscard]] dberr_t open() noexcept;
 
/** Enable the doublewrite reduced mode by creating the necessary dblwr files
and in-memory structures
@return DB_SUCCESS or error code */
[[nodiscard]] dberr_t enable_reduced() noexcept;
 
/** Check and open the reduced doublewrite files if necessary
@return DB_SUCCESS or error code */
[[nodiscard]] dberr_t reduced_open() noexcept;
 
/** Shutdown the background thread and destroy the instance */
void close() noexcept;
 
/** Force a write of all pages in the queue.
@param[in] flush_type           FLUSH LIST or LRU_LIST flush request.
@param[in] buf_pool_index       Buffer pool instance for which called. */
void force_flush(buf_flush_t flush_type, uint32_t buf_pool_index) noexcept;
 
/** Force a write of all pages in all dblwr segments (reduced or regular)
This is used only when switching the doublewrite mode dynamically */
void force_flush_all() noexcept;
 
/** Writes a page to the doublewrite buffer on disk, syncs it,
then writes the page to the datafile.
@param[in]  flush_type          Flush type
@param[in]      bpage                       Buffer block to write
@param[in]      sync                        True if sync IO requested
@return DB_SUCCESS or error code */
[[nodiscard]] dberr_t write(buf_flush_t flush_type, buf_page_t *bpage,
                            bool sync) noexcept;
 
/** Obtain the encrypted frame and store it in bpage->m_io_frame
@param[in,out]  bpage  the buffer page containing the unencrypted frame.
@param[in,out]  type   i/o operation type.
@return the memory block containing the compressed + encrypted frame. */
[[nodiscard]] file::Block *get_encrypted_frame(buf_page_t *bpage,
                                               IORequest &type) noexcept;
 
/** Updates the double write buffer when a write request is completed.
@param[in] bpage               Block that has just been writtent to disk.
@param[in] flush_type          Flush type that triggered the write. */
void write_complete(buf_page_t *bpage, buf_flush_t flush_type) noexcept;
 
/** Delete or adjust the dblwr file size if required. */
void reset_files() noexcept;
 
namespace v1 {
/** Read the boundaries of the legacy dblwr buffer extents.
@return DB_SUCCESS or error code. */
[[nodiscard]] dberr_t init() noexcept;
 
/** Create the dblwr data structures in the system tablespace.
@return DB_SUCCESS or error code. */
[[nodiscard]] dberr_t create() noexcept;
 
/** Check if the read is of a page inside the legacy dblwr buffer.
@param[in] page_no              Page number to check.
@return true if offset inside legacy dblwr buffer. */
[[nodiscard]] bool is_inside(page_no_t page_no) noexcept;
 
}  // namespace v1
}  // namespace dblwr
 
#endif /* !UNIV_HOTBACKUP */
 
namespace dblwr {
 
/** Number of pages per doublewrite thread/segment of the dblwr file.  Refer
to the system variable --innodb-doublewrite-pages for more details. */
extern ulong n_pages;
 
const uint32_t REDUCED_BATCH_PAGE_SIZE = 8192;
 
/* 20-byte header.
Fields        : [batch id][checksum][data len][batch type][unused  ]
Field Width   : [4 bytes ][4 bytes ][2 bytes ][  1 byte  ][ 9 bytes]
Field Offsets : [   0    ][   4    ][    8   ][    10    ][   11   ] */
const uint32_t RB_BATCH_ID_SIZE = 4;
const uint32_t RB_CHECKSUM_SIZE = 4;
const uint32_t RB_DATA_LEN_SIZE = 2;
const uint32_t RB_BATCH_TYPE_SIZE = 1;
const uint32_t RB_UNUSED_BYTES_SIZE = 9;
 
/* Offsets of the header fields. */
constexpr const uint32_t RB_OFF_BATCH_ID = 0;
constexpr const uint32_t RB_OFF_CHECKSUM = RB_OFF_BATCH_ID + RB_BATCH_ID_SIZE;
constexpr const uint32_t RB_OFF_DATA_LEN = RB_OFF_CHECKSUM + RB_CHECKSUM_SIZE;
constexpr const uint32_t RB_OFF_BATCH_TYPE = RB_OFF_DATA_LEN + RB_DATA_LEN_SIZE;
constexpr const uint32_t RB_OFF_UNUSED = RB_OFF_BATCH_TYPE + RB_BATCH_TYPE_SIZE;
 
constexpr const uint32_t REDUCED_HEADER_SIZE =
    RB_BATCH_ID_SIZE     /* BATCH_ID */
    + RB_CHECKSUM_SIZE   /* CHECKSUM */
    + RB_DATA_LEN_SIZE   /* DATA_LEN */
    + RB_BATCH_TYPE_SIZE /* BATCH_TYPE */
    + 9 /* UNUSED BYTES */;
 
constexpr const uint32_t REDUCED_ENTRY_SIZE =
    sizeof(space_id_t) + sizeof(page_no_t) + sizeof(lsn_t);
 
constexpr const uint32_t REDUCED_DATA_SIZE =
    REDUCED_BATCH_PAGE_SIZE - REDUCED_HEADER_SIZE;
 
constexpr const uint32_t REDUCED_MAX_ENTRIES =
    REDUCED_DATA_SIZE / REDUCED_ENTRY_SIZE;
 
/** When --innodb-doublewrite=DETECT_ONLY, page contents are not written to the
dblwr buffer. Only the following Reduced_entry information is stored in the
dblwr buffer. */
struct Reduced_entry {
  space_id_t m_space_id;
  page_no_t m_page_no;
  lsn_t m_lsn;
 
  Reduced_entry(buf_page_t *bpage);
 
  Reduced_entry(space_id_t space_id, page_no_t page_no, lsn_t lsn)
      : m_space_id(space_id), m_page_no(page_no), m_lsn(lsn) {}
 
  byte *write(byte *ptr) {
    uint16_t offset = 0;
    mach_write_to_4(ptr + offset, m_space_id);
    offset += sizeof(m_space_id);
 
    mach_write_to_4(ptr + offset, m_page_no);
    offset += sizeof(m_page_no);
 
    mach_write_to_8(ptr + offset, m_lsn);
    offset += sizeof(m_lsn);
 
    return ptr + offset;
  }
};
 
struct Mode {
  /** The operating mode of doublewrite. The modes ON, TRUEE and
  DETECT_AND_RECOVER are equal to one another. The modes OFF and FALSEE are
  equal to one another.
 
  @note If you change order or add new values, please update
  innodb_doublewrite_names enum in handler/ha_innodb.cc */
  enum mode_t {
    /** Equal to FALSEE. In this mode, dblwr is disabled. */
    OFF,
 
    /** Equal to TRUEE and DETECT_AND_RECOVER modes. */
    ON,
 
    /** In this mode, dblwr is used only to detect torn writes.  At code level,
    this mode is also called as reduced mode. It is called reduced because the
    number of bytes written to the dblwr file is reduced in this mode. */
    DETECT_ONLY,
 
    /** This mode is synonymous with ON, TRUEE. */
    DETECT_AND_RECOVER,
 
    /** Equal to OFF mode. Intentionally wrong spelling because of compilation
    issues on Windows. */
    FALSEE,
 
    /** Equal to ON, DETECT_AND_RECOVER mode. Intentionally wrong spelling
    because of compilation issues on Windows platform. */
    TRUEE
  };
 
  /** Check if doublewrite is enabled.
  @param[in]     mode    dblwr ENUM
  @return true    if dblwr is enabled. */
  static inline bool is_enabled_low(ulong mode);
 
  /** Check if the doublewrite mode is disabled.
  @param[in]     mode    dblwr ENUM
  @return true if dblwr mode is OFF. */
  static inline bool is_disabled_low(ulong mode);
 
  /** Check if the doublewrite mode is detect-only (aka reduced).
  @param[in]     mode    dblwr ENUM
  @return true if dblwr mode is DETECT_ONLY. */
  static inline bool is_reduced_low(ulong mode);
 
  /** Check if the dblwr mode provides atomic writes.
  @return true if mode is ON, TRUEE or DETECT_AND_RECOVER.
  @return false if mode is OFF, FALSE or DETECT_ONLY. */
  static inline bool is_atomic(ulong mode);
 
  /** Convert the dblwr mode into a string representation.
  @param[in]  mode  the dblwr mode.
  @return string representation of the dblwr mode. */
  static const char *to_string(ulong mode);
 
  /** Check if the mode transition is from enabled to disabled.
  @param[in]  new_value  the new value of dblwr mode.
  @return true if mode transition is from enabled to disabled. */
  static inline bool is_enabled_to_disabled(ulong new_value);
 
  /** Check if the mode transition is from disabled to enabled.
  @param[in]  new_value  the new value of dblwr mode.
  @return true if mode transition is from disabled to enabled. */
  static inline bool is_disabled_to_enabled(ulong new_value);
 
  /** Check if the mode transition is equivalent.
  @param[in]  new_value  the new value of dblwr mode.
  @return true if mode transition is equivalent. */
  static bool is_same(ulong new_value);
};
 
bool Mode::is_atomic(ulong mode) {
  return mode == ON || mode == TRUEE || mode == DETECT_AND_RECOVER;
}
 
bool Mode::is_enabled_low(ulong mode) {
  return mode == ON || mode == TRUEE || mode == DETECT_AND_RECOVER ||
         mode == DETECT_ONLY;
}
 
bool Mode::is_disabled_low(ulong mode) { return mode == OFF || mode == FALSEE; }
 
bool Mode::is_reduced_low(ulong mode) { return mode == DETECT_ONLY; }
 
/** DBLWR mode. */
extern ulong g_mode;
 
/** true if DETECT_ONLY (aka reduced) mode is inited */
extern bool is_reduced_inited;
 
/** Check if doublewrite is enabled.
@return true    if dblwr mode is ON, DETECT_ONLY, DETECT_AND_RECOVER
@return false   if dblwr mode is OFF. */
inline bool is_enabled() { return Mode::is_enabled_low(g_mode); }
 
/** Check if the doublewrite mode is detect-only (aka reduced).
@return true if dblwr mode is DETECT_ONLY. */
inline bool is_reduced() { return Mode::is_reduced_low(g_mode); }
 
/** Check if the doublewrite mode is disabled.
@return true if dblwr mode is OFF. */
inline bool is_disabled() { return Mode::is_disabled_low(g_mode); }
 
bool Mode::is_enabled_to_disabled(ulong new_value) {
  return is_enabled() && Mode::is_disabled_low(new_value);
}
 
bool Mode::is_disabled_to_enabled(ulong new_value) {
  return is_disabled() && Mode::is_enabled_low(new_value);
}
 
/** @return string version of dblwr numeric values
@param[in]     mode    dblwr ENUM */
const char *to_string(ulong mode);
 
/** Number of files to use for the double write buffer. Refer to the system
variable --innodb-doublewrite-files for more details. */
extern ulong n_files;
 
/** Maximum number of pages to write in one batch. */
extern ulong batch_size;
 
/** Toggle the doublewrite buffer. */
void set();
 
namespace recv {
 
class Pages;
 
/** Create the recovery dblwr data structures
@param[out]     pages           Pointer to newly created instance */
void create(Pages *&pages) noexcept;
 
/** Load the doublewrite buffer pages.
@param[in,out] pages           For storing the doublewrite pages read
                               from the double write buffer
@return DB_SUCCESS or error code */
[[nodiscard]] dberr_t load(Pages *pages) noexcept;
 
/** Restore corrupted pages of the tablespace from the double write buffer.
Iterates over the supplied double write buffer pages, but only ones that are not
corrupted, searching for mentions of pages from the specified space, and for
each such page checks if tablespace file contains a corrupted version of it and
if so, restores it from the backup in image found in double write buffer page,
unless this is impossible because the double write buffer page does not contain
the body (in reduced, detect-only mode). In case of any errors (IO errors, out
of bounds space access) we crash the server.
@param[in,out] pages Pages from the doublewrite buffer
@param[in] space Tablespace to restore pages in. */
void recover(Pages &pages, fil_space_t &space) noexcept;
 
/** Checks if content of the first page provided from the specified space
requires recovery from the Double-write Buffer. If the supplied @p page_content
has a valid not corrupted page, no action is taken. If it is not, then we try to
get a non-corrupted copy from the Double-write Buffer. If there are any entries
in the Reduced Double-write pages list, we may crash.
@param[in] pages        The Double-write pages read from the Double-write
                        Buffer.
@param[in] space_id     ID of the space to be checked.
@param[in] page_size    Page size structure to use for the tablespace page
                        manipulation.
@param[in] file_path    Path of a file to be used for error reporting.
@param[in] page_content Content of the first page of the specified tablespace
                        read from the disk. The buffer must hold at least
                        `page_size.physical()` bytes.
@return pointer to @p page_content if the page does not require recovery,
pointer to page contents from the Double-write Buffer or nullptr if
page_content is corrupted, but there's no valid image of it in the
Double-write Buffer to restore it from */
[[nodiscard]] const byte *get_first_page_content_for_recovery(
    const recv::Pages &pages, space_id_t space_id, page_size_t page_size,
    const std::string &file_path, const byte *page_content);
 
/** Check if some pages from the double write buffer could not be
restored because of the missing tablespace IDs.
@param[in]      pages           Pages to check */
void check_missing_tablespaces(const Pages *pages) noexcept;
 
/** Free the recovery dblwr data structures
@param[out]     pages           Instance of the Pages to free. */
void destroy(Pages *&pages) noexcept;
 
/** Redo recovery configuration. */
class DBLWR {
 public:
  /** Constructor. */
  explicit DBLWR() noexcept { create(m_pages); }
 
  /** Destructor */
  ~DBLWR() noexcept { destroy(m_pages); }
 
  /** @return true if empty. */
  bool empty() const noexcept { return (m_pages == nullptr); }
 
  /** Load the doublewrite buffer pages. Doesn't create the doublewrite
  @return DB_SUCCESS or error code */
  [[nodiscard]] dberr_t load() noexcept { return (dblwr::recv::load(m_pages)); }
 
#ifndef UNIV_HOTBACKUP
  /** Restore corrupted pages of the tablespace from the double write buffer.
  Iterates over the previously loaded double write buffer pages, but only ones
  that are not corrupted, searching for mentions of pages from the specified
  space, and for each such page checks if tablespace file contains a corrupted
  version of it and if so, restores it from the backup in image found in double
  write buffer page, unless this is impossible because the double write buffer
  page does not contain the body (in reduced, detect-only mode). In case of any
  errors (IO errors, out of bounds space access) we crash the server.
  @param[in] space Tablespace to restore pages in. */
  void recover(fil_space_t &space) noexcept {
    dblwr::recv::recover(*m_pages, space);
  }
 
  /** Checks if content of the first page provided from the specified space
  requires recovery from the Double-write Buffer. If the supplied @p
  page_content has a valid not corrupted page, no action is taken. If it is not,
  then we try to get a non-corrupted copy from the Double-write Buffer. If there
  are any entries in the Reduced Double-write pages list, we may crash.
  @param[in] space_id     ID of the space to be checked.
  @param[in] page_size    Page size structure to use for the tablespace page
                          manipulation.
  @param[in] file_path    Path of a file to be used for error reporting.
  @param[in] page_content Content of the first page of the specified tablespace
                          read from the disk. The buffer must hold at least
                          `page_size.physical()` bytes.
  @return pointer to @p page_content if the page does not require recovery, a
  pointer to page contents from the Double-write Buffer or nullptr if
  page_content is corrupted, but there's no valid image of it in the
  Double-write Buffer to restore it from */
  const byte *get_first_page_content_for_recovery(
      space_id_t space_id, page_size_t page_size, const std::string &file_path,
      const byte *page_content) noexcept {
    return dblwr::recv::get_first_page_content_for_recovery(
        *m_pages, space_id, page_size, file_path, page_content);
  }
 
  /** Check if some pages from the double write buffer
  could not be restored because of the missing tablespace IDs. */
  void check_missing_tablespaces() noexcept {
    dblwr::recv::check_missing_tablespaces(m_pages);
  }
 
  /** Note that recovery is complete. Adjust the file sizes if necessary. */
  void recovered() noexcept { dblwr::reset_files(); }
#endif /* !UNIV_HOTBACKUP */
 
  /** Disable copying. */
  DBLWR(const DBLWR &) = delete;
  DBLWR(DBLWR &&) = delete;
  DBLWR &operator=(DBLWR &&) = delete;
  DBLWR &operator=(const DBLWR &) = delete;
 
 private:
  /** Pages read from the double write file. */
  Pages *m_pages{};
};
}  // namespace recv
 
#ifdef UNIV_DEBUG
/** Check if the dblwr files contain encrypted pages.
@return true if dblwr file contains any encrypted pages,
        false if dblwr file contains no encrypted pages. */
[[nodiscard]] bool has_encrypted_pages() noexcept;
#endif /* UNIV_DEBUG */
}  // namespace dblwr
 
#endif /* buf0dblwr_h */