Stores
[Storage Structures]

Collaboration diagram for Stores:

---

Detailed Description

Indexes and files are special cases of "stores". A store is a linked list of extents, and an extent is a contiguous group of pages. So the store is the structure that holds together an ordered set of pages that can be used by a server and have an identifier (a store ID or stid_t).

Indexes and files of records are built on stores.

Stores have logging properties and other metadata associated with them.

The property that determines the logging level of the store is sm_store_property_t.

Methods that let you get and change the metatdata are:

• ss_m::get_store_property
• ss_m::set_store_property
• ss_m::get_store_info
• snum_t

When a transaction deletes a file or index, the deletion of the underlying stores is delayed until the transaction commits so that the pages allocated to the stores remain reserved (lest the transaction aborts). The deleting transaction could, in theory, reuse the pages for another store, but in practice that is not done. Instead, when a store is deleted, the store is marked for deletion an put in a list for the transaction to delete upon commit. At commit time, stores that have property t_load_file or t_insert_file are converted to t_regular.

Enumerations
enum	sm_store_property_t { , t_temporary = 0x2, t_load_file = 0x4, t_insert_file = 0x08 }
	Store property that controls logging of pages in the store. More...
Functions
static rc_t	ss_m::set_store_property (stid_t stid, store_property_t property)
	Change the store property of a file or index.
static rc_t	ss_m::get_store_property (stid_t stid, store_property_t &property)
	Get the store property of a file or index.
static rc_t	ss_m::get_store_info (const stid_t &stid, sm_store_info_t &info)
	Get various store information of a file or index.

---

Enumeration Type Documentation

enum sm_store_property_t

Store property that controls logging of pages in the store.

• t_regular: All pages in the store are fully logged for ACID properties.
• t_temporary: Structural changes to the store are guaranteed by logging but user data are not. In the case of indexes, the ihtegrity of the index is not guaranteed: only the integrity of the store is guaranteed. In the event of abort, the index must be destroyed. Temporary stores are destroyed when a volume is mounted or dismounted, so they do not survive restart, regardless whether a crash occurred.
• t_load_file: A store that is created with this property starts out as a t_tempory store and is converted to a t_regular store upon commit.
• t_insert_file: Updates to existing pages are fully logged (as if the store were t_regular), but pages allocated while the store has t_insert_file are not logged. This is useful for bulk-loading, e.g., a store is bulk-loaded in one transaction (t_load_file), which commits (now the file is t_regular); subsequent appends to the file would incur full logging, so the subsequent transaction can change the store's property to t_insert_file, append the data, and change the store's property back to t_regular.

     * ------------------------------------------------------------
     * ------------------------------------------------------------
     * Permissible uses of store property by storage manager client:
     * ------------------------------------------------------------
     * Create a btree index: | Change it to:
     *    t_tmp NO
     *    t_load_file YES    | tmp NO load_file NO insert_file NO regular YES
     *    t_insert_file YES  | tmp NO load_file NO insert_file YES regular YES
     *    t_regular YES      | tmp NO load_file NO insert_file NO regular YES
     *
     * Create an rtree index:
     *    t_tmp YES          | tmp NO load_file NO insert_file NO regular YES
     *    t_load_file YES    | tmp NO load_file NO insert_file NO regular YES
     *    t_insert_file YES  | tmp NO load_file NO insert_file YES regular YES
     *    t_regular YES      | tmp NO load_file NO insert_file NO regular YES
     *
     * Create a file:        | Change it to:
     *    t_tmp YES          | tmp NO load_file NO insert_file YES regular YES
     *    t_load_file YES    | tmp NO load_file NO insert_file YES regular YES
     *    t_insert_file YES  | tmp NO load_file NO insert_file YES regular YES
     *    t_regular YES      | tmp NO load_file NO insert_file YES regular YES
     * ------------------------------------------------------------
     * Effects of changing a file to regular:
     *    This causes the buffer pool to 
     *    force to disk all dirty pages for the store, and 
     *    to discard (evict from the buffer pool) all the store's 
     *    pages, clean or dirty.  When these pages are next read 
     *    into the buffer pool, they will be tagged as regular. 
     * ------------------------------------------------------------
     * Effects of commit:
     *    t_tmp              remains t_tmp  
     *    t_load_file        store is t_regular**
     *    t_insert_file      store is t_regular**
     *    t_regular          ACID
     *          ** Upon creation of such a store, the storage manager pushes
     *          this store on a list to traverse and convert to regular
     *          upon commit.
     *          Upon changing a store's property to t_insert_file,
     *          the storage manager pushes the store on this same list. 
     * ------------------------------------------------------------
     * Effects of abort on user data:
     *    t_tmp              undefined: client must remove store
     *    t_load_file        undefined: client must remove store
     *    t_insert_file      undefined: client must remove store
     *    t_regular          ACID
     * ------------------------------------------------------------
     * Effects of dismount/mount/restart:
     *    t_tmp              store removed
     *    t_load_file        undefined if not commited
     *    t_insert_file      undefined if not commited
     *    t_regular          ACID
     * ------------------------------------------------------------
     * 

Enumerator:

t_temporary	allowed only in create
t_load_file	allowed only in create, these files start out as temp and are converted to regular on commit
t_insert_file	current pages logged, new pages not logged EX lock is acquired on file. only valid with a normal file, not indices.

Definition at line 131 of file sm_int_3.h.

---

Function Documentation

static rc_t ss_m::set_store_property	(	stid_t	stid,
		store_property_t	property
	)			[static, inherited]

Change the store property of a file or index.

Parameters:

[in]	stid	File ID or index ID of the store to change.
[in]	property	Enumeration store_property_t (alias for smlevel_3::sm_store_property_t, q.v.)

The possible uses of store properties are described with smlevel_3::sm_store_property_t.

static rc_t ss_m::get_store_property	(	stid_t	stid,
		store_property_t &	property
	)			[static, inherited]

Get the store property of a file or index.

Parameters:

[in]	stid	File ID or index ID of the store of interest.
[in]	property	Reference to enumeration store_property_t (alias for smlevel_3::sm_store_property_t, q.v.)

The possible uses of store properties are described with smlevel_3::sm_store_property_t.

static rc_t ss_m::get_store_info	(	const stid_t &	stid,
		sm_store_info_t &	info
	)			[static, inherited]

Get various store information of a file or index.

Parameters:

[in]	stid	File ID or index ID of the store of interest.
[out]	info	Reference to sm_store_info_t into which to write the results.

Get internally stored information about a store.

---