This is the SHORE Storage Manager API. More...

#include <sm.h>

Inheritance diagram for ss_m:

Public Types
typedef smlevel_0::concurrency_t	concurrency_t

typedef smlevel_0::xct_state_t	xct_state_t

typedef sm_store_property_t	store_property_t

Public Member Functions
	ss_m (const sm_options &options)
	Initialize the storage manager. More...

	~ss_m ()
	Shut down the storage manager. More...

bool	startup ()

bool	shutdown ()

rc_t	_truncate_log ()

Static Public Member Functions
static void	set_shutdown_flag (bool clean)
	Cause the storage manager's shutting down do be done cleanly or to simulate a crash. More...

static void	set_shutdown_filthy (bool filthy)
	Cause the storage manager's shutting down to simulate a filthy crash, which worse than the dirty shutdown, because it truncates the log in order to make the log to represent an even dirtier state than the dirty shutdown. More...

static rc_t	log_file_was_archived (const char *logfile)
	Notify storage manager when a log file was archived by a LOG_WARN_CALLBACK_FUNC. More...

static rc_t	begin_xct (int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Begin a transaction. More...

static rc_t	begin_xct (sm_stats_t *stats, int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Begin an instrumented transaction. More...

static rc_t	begin_xct (tid_t &tid, int timeout=timeout_t::WAIT_SPECIFIED_BY_THREAD)
	Begin a transaction and return the transaction id. More...

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)
	Being a new system transaction which might be a nested transaction. More...

static rc_t	commit_xct (bool lazy=false, lsn_t *plastlsn=nullptr)
	Commit a transaction. More...

static rc_t	commit_xct (sm_stats_t &stats, bool lazy=false, lsn_t plastlsn=nullptr)
	Commit an instrumented transaction and get its statistics. More...

static rc_t	commit_sys_xct ()
	Commit a system transaction, which doesn't cause log sync. More...

static rc_t	chain_xct (sm_stats_t *&stats, bool lazy=false)
	Commit an instrumented transaction and start a new one. More...

static rc_t	chain_xct (bool lazy=false)
	Commit a transaction and start a new one, inheriting locks. More...

static rc_t	commit_xct_group (xct_t *list[], int listlen)
	Commit a group of transactions. More...

static rc_t	abort_xct (sm_stats_t *&stats)
	Abort an instrumented transaction and get its statistics. More...

static rc_t	abort_xct ()
	Abort a transaction. More...

static rc_t	save_work (sm_save_point_t &sp)
	Populate a save point. More...

static rc_t	rollback_work (const sm_save_point_t &sp)
	Roll back to a savepoint. More...

static uint32_t	num_active_xcts ()
	Return the number of transactions in active state. More...

static void	attach_xct (xct_t *x)
	Attach the given transaction to the currently-running smthread_t. More...

static void	detach_xct ()
	Detach any attached from the currently-running smthread_t. More...

static xct_t *	tid_to_xct (const tid_t &tid)
	Get the transaction structure for a given a transaction id. More...

static tid_t	xct_to_tid (const xct_t *x)
	Get the transaction ID for a given a transaction structure. More...

static rc_t	dump_xcts (ostream &o)
	Print transaction information to an output stream. More...

static xct_state_t	state_xct (const xct_t *x)
	Get the transaction state for a given transaction (structure). More...

static off_t	xct_log_space_needed ()
	Return the amount of log this transaction would consume if it rolled back.If a transaction aborts with eOUTOFLOGSPACE this function can be used in conjunction with xct_reserve_log_space to pre-allocate the needed amount of log space before retrying. More...

static rc_t	xct_reserve_log_space (off_t amt)
	Require the specified amount of log space to be available for this transaction before continuing.If a transaction risks running out of log space it can pre-request some or all of the needed amount before starting in order to improve its chances of success. Other new transactions will be unable to acquire log space before this request is granted (existing ones will be able to commit, unless they also run out of space, because that tends to free up log space and avoids wasting work). More...

static rc_t	checkpoint ()
	Take a checkpoint. More...

static rc_t	force_volume ()
	Force the buffer pool to flush to disk all pages for the given volume. More...

static rc_t	gather_xct_stats (sm_stats_t &stats, bool reset=false)
	Get a copy of the statistics from an attached instrumented transaction. More...

static rc_t	gather_stats (sm_stats_t &stats)
	Get a copy of the global statistics. More...

static rc_t	config_info (sm_config_info_t &info)
	Get a copy of configuration-dependent information. More...

static rc_t	set_disk_delay (u_int milli_sec)
	Set sleep time before I/O operations. More...

static rc_t	sync_log (bool block=true)
	Forces a log flush. More...

static rc_t	flush_until (lsn_t &anlsn, bool block=true)
	Forces a log flush until the given lsn. More...

static rc_t	get_curr_lsn (lsn_t &anlsn)
	Allowing to access info about the current lsn. More...

static rc_t	get_durable_lsn (lsn_t &anlsn)
	Allowing to access info about the durable lsn. More...

static void	dump_page_lsn_chain (std::ostream &o, const PageID &pid, const lsn_t &max_lsn)
	Pretty-prints the content of log file to the given stream in a way we can easily debug single-page recovery. More...

static void	dump_page_lsn_chain (std::ostream &o, const PageID &pid)
	Pretty-prints the content of log file to the given stream in a way we can easily debug single-page recovery. More...

static void	dump_page_lsn_chain (std::ostream &o)
	Pretty-prints the content of log file to the given stream in a way we can easily debug single-page recovery. More...

static rc_t	verify_volume (int hash_bits, verify_volume_result &result)
	Verifies consistency of all BTree indexes in the volume. More...

static rc_t	create_index (StoreID &stid)
	Create a B+-Tree index. More...

static rc_t	destroy_index (const StoreID &iid)
	Destroy a B+-Tree index. More...

static rc_t	touch_index (StoreID stid, uint64_t &page_count)
	Touches all pages in the B-tree index to load them into bufferpool. More...

static rc_t	create_assoc (StoreID stid, const w_keystr_t &key, const vec_t &el)
	Create an entry in a B+-Tree index. More...

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)
	Update record data of an entry in a B+-Tree index. More...

static rc_t	put_assoc (StoreID stid, const w_keystr_t &key, const vec_t &el)
	Put record data of an entry in a B+-Tree index. More...

static rc_t	overwrite_assoc (StoreID stid, const w_keystr_t &key, const char *el, smsize_t offset, smsize_t elen)
	This function finds the given key, updates the specific part of element if found. More...

static rc_t	destroy_assoc (StoreID stid, const w_keystr_t &key)
	Remove an entry from a B+-Tree index. More...

static rc_t	find_assoc (StoreID stid, const w_keystr_t &key, void *el, smsize_t &elen, bool &found)
	Find an entry associated with a key in a B+-Tree index. More...

static rc_t	defrag_index_page (btree_page_h &page)
	Defrags the given page to remove holes and ghost records in the page. More...

static rc_t	verify_index (StoreID stid, int hash_bits, bool &consistent)
	Verifies the integrity of B-Tree index using the fence-key bitmap technique. More...

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)

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)
	Acquire a lock. More...

static rc_t	activate_archiver ()

static const sm_options &	get_options ()

Static Public Attributes
static sm_options	_options

Private Member Functions
void	_construct_once ()

void	_destruct_once ()

void	_do_restart ()

void	_finish_recovery ()

void	_set_option_logsize ()

Static Private Member Functions
static xct_t *	_new_xct (sm_stats_t *stats, int timeout, bool sys_xct, bool single_log_sys_xct=false)

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, 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)

static store_flag_t	_make_store_flag (store_property_t property)

Static Private Attributes
static int	_instance_cnt = 0

Friends
class	prologue_rc_t

class	log_entry

class	coordinator

class	tape_t

Detailed Description

This is the SHORE Storage Manager API.

Most of the API for using the storage manager is through this interface class.

Member Typedef Documentation

§ concurrency_t

typedef smlevel_0::concurrency_t ss_m::concurrency_t

§ store_property_t

typedef sm_store_property_t ss_m::store_property_t

§ xct_state_t

typedef smlevel_0::xct_state_t ss_m::xct_state_t

Constructor & Destructor Documentation

§ ss_m()

ss_m::ss_m ( const sm_options & options )

Initialize the storage manager.

Parameters

[in] options Start-up parameters.

When an ss_m object is created, the storage manager initializes itself and, if the sthreads package has not already been initialized by virtue of an sthread_t running, the sthreads package is initialized now.

The log is read and recovery is performed (MHLPS), and control returns to the caller, after which time storage manager threads (instances of smthread_t) may be constructed and storage manager may be used.

The storage manager is used by invoking its static methods. You may use them as follows:

ss_m *UNIQ = new ss_m();
W_DO(UNIQ->mount_vol(...))
    // or
W_DO(ss_m::mount_vol(...))

).

Only one ss_m object may be extant at any time. If you try to create another while the one exists, a fatal error will occur (your program will choke with a message about your mistake).

The callback argument given to the storage manager constructor is called when the storage manager determines that it is in danger of running out of log space. Heuristics are used to guess when this is the case.

If the function warn archives and removes log files, the function get must be provided to restore those log files when the storage manager needs them.

For details and examples, see smlevel_0::LOG_WARN_CALLBACK_FUNC, smlevel_0::LOG_ARCHIVED_CALLBACK_FUNC, and SSMLOG.

§ ~ss_m()

ss_m::~ss_m ( )

Shut down the storage manager.

When the storage manager object is deleted, it shuts down. Thereafter it is not usable until another ss_m object is constructed.

Member Function Documentation

§ _abort_xct()

rc_t ss_m::_abort_xct ( sm_stats_t *& stats )

staticprivate

§ _begin_xct()

rc_t ss_m::_begin_xct	(	sm_stats_t *	stats,
		tid_t &	tid,
		int	timeout,
		bool	sys_xct = `false`,
		bool	single_log_sys_xct = `false`
	)

staticprivate

§ _chain_xct()

rc_t ss_m::_chain_xct	(	sm_stats_t *&	stats,
		bool	lazy
	)

staticprivate

§ _commit_xct()

rc_t ss_m::_commit_xct	(	sm_stats_t *&	stats,
		bool	lazy,
		lsn_t *	plastlsn
	)

staticprivate

§ _commit_xct_group()

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

staticprivate

§ _construct_once()

void ss_m::_construct_once ( )

§ activate_archiver()

rc_t ss_m::activate_archiver ( )

static

§ checkpoint()

rc_t ss_m::checkpoint ( )

static

Take a checkpoint.

Note: For debugging only!

Force the storage manager to take a checkpoint. Checkpoints are fuzzy : they can be taken while most other storage manager activity is happening, even though they have to be serialized with respect to each other, and with respect to a few other activities.

This is thread-safe.

§ config_info()

rc_t ss_m::config_info ( sm_config_info_t & info )

static

Get a copy of configuration-dependent information.

Parameters

[out] info A pre-allocated structure.

§ create_assoc()

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

static

§ dump_xcts()

rc_t ss_m::dump_xcts ( ostream & o )

static

Print transaction information to an output stream.

Parameters

[in] o Stream to which to write the information.

This is for debugging only, and is not thread-safe.

§ flush_until()

rc_t ss_m::flush_until	(	lsn_t &	anlsn,
		bool	block = `true`
	)

static

Forces a log flush until the given lsn.

§ force_volume()

static rc_t ss_m::force_volume ( )

static

Force the buffer pool to flush to disk all pages for the given volume.

§ get_curr_lsn()

rc_t ss_m::get_curr_lsn ( lsn_t & anlsn )

static

Allowing to access info about the current lsn.

§ get_durable_lsn()

rc_t ss_m::get_durable_lsn ( lsn_t & anlsn )

static

Allowing to access info about the durable lsn.

§ get_lil_global_table()

lil_global_table * ss_m::get_lil_global_table ( )

static

Returns the global lock table object for light-weight intent locks.

§ get_options()

static const sm_options& ss_m::get_options ( )

inlinestatic

§ lock()

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

static

Acquire a lock.

Parameters

[in]	n	Lock id of the entity to lock. There are conversions from record ids, volume ids, store ids, and page ids to lockid_t.
[in]	m	Desired lock mode. Values: EX, SH.
[in]	check_only	if true, the lock goes away right after grant. default false.
[in]	timeout	Milliseconds willing to block. See int.

§ log_file_was_archived()

static rc_t ss_m::log_file_was_archived ( const char * logfile )

static

Notify storage manager when a log file was archived by a LOG_WARN_CALLBACK_FUNC.

Parameters

[in] logfile Character string name of file archived.

§ open_store()

rc_t ss_m::open_store	(	StoreID	stid,
		PageID &	root_pid,
		bool	for_update = `false`
	)

static

Starts reading a given store and returns its root page ID. If this is called in transaction with lock enabled, this takes an intent lock on it.

Parameters

for_update whether to take IX or IS lock on the store.

§ open_store_nolock()

rc_t ss_m::open_store_nolock	(	StoreID	stid,
		PageID &	root_pid
	)

static

This version doesn't take a lock.

§ set_disk_delay()

static rc_t ss_m::set_disk_delay ( u_int milli_sec )

static

Set sleep time before I/O operations.

This method sets a milli_sec delay to occur before each disk read/write operation. This is for debugging. It is useful in discovering thread sync bugs. This delay applies to all threads.

§ set_shutdown_filthy()

void ss_m::set_shutdown_filthy ( bool filthy )

static

Cause the storage manager's shutting down to simulate a filthy crash, which worse than the dirty shutdown, because it truncates the log in order to make the log to represent an even dirtier state than the dirty shutdown.

Note: This method is not thread-safe, only one thread should use this at any time, presumably just before shutting down.

§ set_shutdown_flag()

void ss_m::set_shutdown_flag ( bool clean )

static

Cause the storage manager's shutting down do be done cleanly or to simulate a crash.

Parameters

[in] clean True means shut down gracefully, false means simulate a crash.

When the storage manager's destructor is called the buffer pool is flushed to disk, unless this method is called with clean == false.

Note: If this method is used, it must be called after the storage manager is constructed if it is to take effect. Each time the storage manager is constructed, the state associated with this is set to true, i.e., "shut down properly".; This method is not thread-safe, only one thread should use this at any time, presumably just before shutting down.

§ shutdown()

bool ss_m::shutdown ( )

§ startup()

bool ss_m::startup ( )

§ sync_log()

rc_t ss_m::sync_log ( bool block = true )

static

Forces a log flush.

§ verify_volume()

rc_t ss_m::verify_volume	(	int	hash_bits,
		verify_volume_result &	result
	)

static

Verifies consistency of all BTree indexes in the volume.

Unlike verify_index() this method sequentially scans all pages in this volume to efficiently conduct the batch-verification. However, you cannot have concurrent update operations while you are running this verification. It might cause deadlocks! To allow concurrent transaction while verifying, consider using _ux_verify_tree().

Parameters

[in]	hash_bits	the number of bits we use for hashing per BTree, at most 31.
[out]	result	Results of the verification.

See also: _ux_verify_tree(); verify_index()

§ xct_log_space_needed()

static off_t ss_m::xct_log_space_needed ( )

static

Return the amount of log this transaction would consume if it rolled back.If a transaction aborts with eOUTOFLOGSPACE this function can be used in conjunction with xct_reserve_log_space to pre-allocate the needed amount of log space before retrying.

§ xct_reserve_log_space()

static rc_t ss_m::xct_reserve_log_space ( off_t amt )

static

Require the specified amount of log space to be available for this transaction before continuing.If a transaction risks running out of log space it can pre-request some or all of the needed amount before starting in order to improve its chances of success. Other new transactions will be unable to acquire log space before this request is granted (existing ones will be able to commit, unless they also run out of space, because that tends to free up log space and avoids wasting work).

Friends And Related Function Documentation

§ coordinator

friend class coordinator

friend

§ log_entry

friend class log_entry

friend

§ prologue_rc_t

friend class prologue_rc_t

friend

§ tape_t

friend class tape_t

friend

Member Data Documentation

§ _instance_cnt

int ss_m::_instance_cnt = 0

staticprivate

§ _options

sm_options ss_m::_options

static

Start-up parameters for the storage engine.

The documentation for this class was generated from the following files:

src/sm/sm.h
src/sm/sm.cpp
src/sm/smindex.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

§ concurrency_t

§ store_property_t

§ xct_state_t

Constructor & Destructor Documentation

§ ss_m()

§ ~ss_m()

Member Function Documentation

§ _abort_xct()

§ _begin_xct()

§ _chain_xct()

§ _commit_xct()

§ _commit_xct_group()

§ _construct_once()

§ _destruct_once()

§ _do_restart()

§ _finish_recovery()

§ _get_store_info()

§ _get_store_property()

§ _make_store_flag()

§ _new_xct()

§ _rollback_work()

§ _save_work()

§ _set_option_logsize()

§ _set_store_property()

§ _truncate_log()

§ activate_archiver()

§ checkpoint()

§ config_info()

§ create_assoc()

§ dump_xcts()

§ flush_until()

§ force_volume()

§ get_curr_lsn()

§ get_durable_lsn()

§ get_lil_global_table()

§ get_options()

§ lock()

§ log_file_was_archived()

§ open_store()

§ open_store_nolock()

§ set_disk_delay()

§ set_shutdown_filthy()

§ set_shutdown_flag()

§ shutdown()

§ startup()

§ sync_log()

§ verify_volume()

§ xct_log_space_needed()

§ xct_reserve_log_space()

Friends And Related Function Documentation

§ coordinator

§ log_entry

§ prologue_rc_t

§ tape_t

Member Data Documentation

§ _instance_cnt

§ _options