sm.h

Go to the documentation of this file.

/*
 * (c) Copyright 2011-2014, Hewlett-Packard Development Company, LP
 */

/* -*- mode:C++; c-basic-offset:4 -*-
     Shore-MT -- Multi-threaded port of the SHORE storage manager

                       Copyright (c) 2007-2009
      Data Intensive Applications and Systems Labaratory (DIAS)
               Ecole Polytechnique Federale de Lausanne

                         All Rights Reserved.

   Permission to use, copy, modify and distribute this software and
   its documentation is hereby granted, provided that both the
   copyright notice and this permission notice appear in all copies of
   the software, derivative works or modified versions, and any
   portions thereof, and that both notices appear in supporting
   documentation.

   This code 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. THE AUTHORS
   DISCLAIM ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER
   RESULTING FROM THE USE OF THIS SOFTWARE.
*/

/*<std-header orig-src='shore' incl-file-exclusion='SM_H'>

 $Id: sm.h,v 1.322 2010/10/27 17:04:23 nhall Exp $

SHORE -- Scalable Heterogeneous Object REpository

Copyright (c) 1994-99 Computer Sciences Department, University of
                      Wisconsin -- Madison
All Rights Reserved.

Permission to use, copy, modify and distribute this software and its
documentation is hereby granted, provided that both the copyright
notice and this permission notice appear in all copies of the
software, derivative works or modified versions, and any portions
thereof, and that both notices appear in supporting documentation.

THE AUTHORS AND THE COMPUTER SCIENCES DEPARTMENT OF THE UNIVERSITY
OF WISCONSIN - MADISON ALLOW FREE USE OF THIS SOFTWARE IN ITS
"AS IS" CONDITION, AND THEY DISCLAIM ANY LIABILITY OF ANY KIND
FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.

This software was developed with support by the Advanced Research
Project Agency, ARPA order number 018 (formerly 8230), monitored by
the U.S. Army Research Laboratory under contract DAAB07-91-C-Q518.
Further funding for this work was provided by DARPA through
Rome Research Laboratory Contract No. F30602-97-2-0247.

*/

#ifndef __SM_H
#define __SM_H

#include "w_defines.h"

/*  -- do not edit anything above this line --   </std-header>*/

/*
 *  Stuff needed by value-added servers.  NOT meant to be included by
 *  internal SM .c files, except to the extent that they need these
 *  definitions used in the API.
 */

#ifndef __SM_BASE_H

#include "sm_base.h"

#endif // __SM_BASE_H

#include "smstats.h" // declares sm_stats_t and sm_config_info_t
#include "lsn.h"
#include <string>
#include "sm_options.h"

#include <boost/filesystem.hpp>

/* DOXYGEN Documentation : */

/********************************************************************/

class fixable_page_h;
class btree_page_h;
class xct_t;
class vec_t;
class log_m;
class lock_m;
class btree_m;
class pool_m;
class dir_m;
class chkpt_m;
class lid_m;
class sm_stats_cache_t;
class prologue_rc_t;
class w_keystr_t;
class verify_volume_result;
class lil_global_table;
struct okvl_mode;
class key_ranges_map;

class sm_save_point_t : public lsn_t {
public:
    sm_save_point_t() : _tid(0) {};

    friend ostream& operator<<(ostream& o, const sm_save_point_t& p) {
        return o << p._tid << ':' << (const lsn_t&)p;
    }

    friend istream& operator>>(istream& i, sm_save_point_t& p) {
        char ch;
        return i >> p._tid >> ch >> (lsn_t&)p;
    }

    tid_t tid() const {
        return _tid;
    }

private:
    friend class ss_m;

    tid_t _tid;
};

class sm_store_info_t;
class log_entry;
class coordinator;
class tape_t;

class ss_m : public smlevel_top {
    friend class prologue_rc_t;
    friend class log_entry;
    friend class coordinator;
    friend class tape_t;

public:

    typedef smlevel_0::concurrency_t concurrency_t;

    typedef smlevel_0::xct_state_t xct_state_t;

    typedef sm_store_property_t store_property_t;

#ifdef COMMENT
    //
    // Below is most of the interface for the SHORE Storage Manager.
    // The rest is located in smthread.h
    //

    //
    // TEMPORARY FILES/INDEXES
    //
    // When a file or index is created there is a tmp_flag parameter
    // that when true indicates that the file is temporary.
    // Operations on a temporary file are not logged and the
    // file will be gone the next time the volume is mounted.
    //
    // TODO: IMPLEMENTATION NOTE on Temporary Files/Indexes:
    //        Temp files cannot be trusted after transaction abort.
    //            They should be marked for removal.
    //
    // CODE STRUCTURE:
    //    Almost all ss_m functions begin by creating a prologue object
    //    whose constructor and descructor check for many common errors.
    //    In addition most ss_m::OP() functions now call an ss_m::_OP()
    //    function to do the real work.  The ss_m::OP functions should
    //    not be called by other ss_m functions, instead the corresponding
    //    ss_m::_OP function should be used.
    //

#endif /* COMMENT */

public:
    ss_m(const sm_options& options);

    ~ss_m();

    // Manually start the store if the store is not running already.
    // Only one instance of store can be running at any time.
    // The function starts the store using the input parameters from sm constructor,
    // no change allowed after the ss_m constructor
    // Internal settings will be reset, i.e. shutting_down, shutdown_clean flags
    // Return: true if store started successfully
    //             false if store was running already
    bool startup();

    // Manually stop a running store.  If the store was not running, no-op.
    // Only one instance of store can be running at any time.
    // The shutdown process obeys the internal settings,
    // i.e. shutting_down, shutdown_clean flags
    // Return: if store shutdown successfully or was not running
    bool shutdown();

    static void set_shutdown_flag(bool clean);

    static void set_shutdown_filthy(bool filthy);

    static rc_t log_file_was_archived(const char* logfile);

    rc_t _truncate_log();

private:
//    void                _construct_once(LOG_WARN_CALLBACK_FUNC x=nullptr,
//                                           LOG_ARCHIVED_CALLBACK_FUNC y=nullptr);
    void _construct_once();

    void _destruct_once();

    void _do_restart();

    void _finish_recovery();

    // Used for cosntructing xct object depending on chosen implementation
    static xct_t* _new_xct(
            sm_stats_t* stats,
            int timeout,
            bool sys_xct,
            bool single_log_sys_xct = false);

public:
    static rc_t begin_xct(
            int timeout = timeout_t::WAIT_SPECIFIED_BY_THREAD);

    static rc_t begin_xct(
            sm_stats_t* stats,  // allocated by caller
            int timeout = timeout_t::WAIT_SPECIFIED_BY_THREAD);

    static rc_t begin_xct(
            tid_t& tid,
            int timeout = timeout_t::WAIT_SPECIFIED_BY_THREAD);

    static rc_t begin_sys_xct(
            bool single_log_sys_xct = false,
            sm_stats_t* stats = nullptr,
            int timeout = timeout_t::WAIT_SPECIFIED_BY_THREAD);

    static rc_t commit_xct(
            bool lazy = false,
            lsn_t* plastlsn = nullptr);

    static rc_t commit_xct(
            sm_stats_t*& stats,
            bool lazy = false,
            lsn_t* plastlsn = nullptr);

    static rc_t commit_sys_xct();

    static rc_t chain_xct(
            sm_stats_t*& stats,    /* in w/new, out w/old */
            bool lazy = false);

    static rc_t chain_xct(bool lazy = false);

    static rc_t commit_xct_group(
            xct_t* list[],
            int listlen);

    static rc_t abort_xct(sm_stats_t*& stats);

    static rc_t abort_xct();

    static rc_t save_work(sm_save_point_t& sp);

    static rc_t rollback_work(const sm_save_point_t& sp);

    static uint32_t num_active_xcts();

    static void attach_xct(xct_t* x) {
        smthread_t::attach_xct(x);
    }

    static void detach_xct() {
        xct_t* x = smthread_t::xct();
        if (x) {
            smthread_t::detach_xct(x);
        }
    }

    static xct_t* tid_to_xct(const tid_t& tid);

    static tid_t xct_to_tid(const xct_t* x);

    static rc_t dump_xcts(ostream& o);

    static xct_state_t state_xct(const xct_t* x);

    static off_t xct_log_space_needed();

    static rc_t xct_reserve_log_space(off_t amt);

    static rc_t checkpoint();

    static rc_t force_volume();

    static rc_t dump_buffers(ostream& o);

    static rc_t dump_locks(ostream& o);

    static rc_t dump_locks(); // defaults to std::cout

    static rc_t gather_xct_stats(
            sm_stats_t& stats,
            bool reset = false);

    static rc_t gather_stats(
            sm_stats_t& stats
                            );

    static rc_t config_info(sm_config_info_t& info);

    static rc_t set_disk_delay(u_int milli_sec);

    static rc_t sync_log(bool block = true);

    static rc_t flush_until(lsn_t& anlsn, bool block = true);

    static rc_t get_curr_lsn(lsn_t& anlsn);

    static rc_t get_durable_lsn(lsn_t& anlsn);

    static void dump_page_lsn_chain(std::ostream& o, const PageID& pid,
                                    const lsn_t& max_lsn);

    static void dump_page_lsn_chain(std::ostream& o, const PageID& pid);

    static void dump_page_lsn_chain(std::ostream& o);

    static rc_t verify_volume(
            int hash_bits, verify_volume_result& result);



    //
    // Functions for B+tree Indexes
    //
    static rc_t create_index(
            StoreID& stid
                            );

    static rc_t destroy_index(const StoreID& iid);

    static rc_t print_index(StoreID stid);
    static rc_t touch_index(StoreID stid, uint64_t& page_count);

    static rc_t create_assoc(
            StoreID stid,
            const w_keystr_t& key,
            const vec_t& el
                            );

    static rc_t create_assoc(
            StoreID stid,
            const vec_t& key,
            const vec_t& el
                            );

    static rc_t update_assoc(
            StoreID stid,
            const w_keystr_t& key,
            const vec_t& el
                            );

    static rc_t put_assoc(
            StoreID stid,
            const w_keystr_t& key,
            const vec_t& el
                         );

    static rc_t overwrite_assoc(
            StoreID stid,
            const w_keystr_t& key,
            const char* el, smsize_t offset, smsize_t elen);

    static rc_t destroy_assoc(
            StoreID stid,
            const w_keystr_t& key
                             );

    static rc_t find_assoc(
            StoreID stid,
            const w_keystr_t& key,
            void* el,
            smsize_t& elen,
            bool& found
                          );

    static rc_t defrag_index_page(btree_page_h& page);

    static rc_t verify_index(StoreID stid, int hash_bits, bool& consistent);

    static rc_t open_store(StoreID stid, PageID& root_pid,
                           bool for_update = false);

    static rc_t open_store_nolock(StoreID stid, PageID& root_pid);

    /*****************************************************************
     * Locking related functions
     *
     * NOTE: there are standard conversions from PageID, and
     *       StoreID to lockid_t, so wherever a lockid_t parameter is
     *         specified a PageID or StoreID can be used.
     *
     *****************************************************************/

    static lil_global_table* get_lil_global_table();

    static rc_t lock(
            const lockid_t& n,
            const okvl_mode& m,
            bool check_only = false,
            int timeout = timeout_t::WAIT_SPECIFIED_BY_XCT
                    );

    static rc_t activate_archiver();

    static sm_options _options;

    static const sm_options& get_options() {
        return _options;
    }

private:

    static int _instance_cnt;

    void _set_option_logsize();

    static rc_t _set_store_property(
            StoreID stid,
            store_property_t property);

    static rc_t _get_store_property(
            StoreID stid,
            store_property_t& property);

    static rc_t _begin_xct(
            sm_stats_t* stats,  // allocated by caller
            tid_t& tid,
            int timeout,
            bool sys_xct = false,
            bool single_log_sys_xct = false);

    static rc_t _commit_xct(
            sm_stats_t*& stats,
            bool lazy,
            lsn_t* plastlsn);

    static rc_t _commit_xct_group(
            xct_t* list[],
            int listlen);

    static rc_t _chain_xct(
            sm_stats_t*& stats,
            bool lazy);

    static rc_t _abort_xct(
            sm_stats_t*& stats);

    static rc_t _save_work(sm_save_point_t& sp);

    static rc_t _rollback_work(const sm_save_point_t& sp);

    static rc_t _get_store_info(
            const StoreID& stid,
            sm_store_info_t& info);

    //
    // The following functions deal with files of records.
    //

    static store_flag_t _make_store_flag(store_property_t property);
    // reverse function:
    // static store_property_t    _make_store_property(uint32_t flag);
    // is in dir_vol_m

};

class sm_store_info_t {
public:
    sm_store_info_t() :
            store(0),
            root(0) {}

    ~sm_store_info_t() {}

    StoreID store;

    PageID root;
};

ostream& operator<<(ostream& o, const sm_stats_t& s);

template<class ostream>
ostream& operator<<(ostream& o, const sm_config_info_t& s) {
    o << "  page_size " << s.page_size
      << "  lg_rec_page_space " << s.lg_rec_page_space
      << "  buffer_pool_size " << s.buffer_pool_size
      << "  max_btree_entry_size " << s.max_btree_entry_size
      << "  logging " << s.logging;
    return o;
}

#ifndef __VEC_T_H
#include "vec_t.h"
#endif // __VEC_T_H

/*<std-footer incl-file-exclusion='SM_H'>  -- do not edit anything below this line -- */

#endif // __SM_H /*</std-footer>*/