scan_index_i Class Reference
[Scanning B+-Tree Indexes]

Inherits smlevel_top, and xct_dependent_t.

Collaboration diagram for scan_index_i:

[legend]List of all members.

---

Detailed Description

Iterator over an index.

To iterate over the {key,value} pairs in an index, construct an instance of this class, and use its next() method to advance the cursor and the curr() method to copy out keys and values into server-space. It is unwise to delete or insert associations while you have a scan open on the index (in the same transaction).

Example code:

 stid_t fid(1,7);
 scan_index_i scan(fid,             
                scan_index_i::ge, vec_t::neg_inf,
                scan_index_i::le, vec_t::pos_inf, false,
                ss_m::t_cc_kvl);
 bool         eof(false);
 do {
    w_rc_t rc = scan.next(eof);
    if(rc.is_error()) {
       // handle error
       ...
    }
    if(eof) break;

   // get the key len and element len
   W_DO(scan.curr(NULL, klen, NULL, elen));

   // Create vectors for the given lengths.
   vec_t key(keybuf, klen);
   vec_t elem(&info, elen);

   // Get the key and element value
   W_DO(scan.curr(&key, klen, &elem, elen));
    ...
 } while (1);

Examples:

create_rec.cpp, log_exceed.cpp, sort_stream.cpp, and vtable_example.cpp.

Definition at line 160 of file scan.h.

Public Member Functions
NORET	scan_index_i (const stid_t &stid, cmp_t c1, const cvec_t &bound1, cmp_t c2, const cvec_t &bound2, bool include_nulls=false, concurrency_t cc=t_cc_kvl, lock_mode_t mode=SH)
	Construct an iterator.
rc_t	curr (vec_t *key, smsize_t &klen, vec_t *el, smsize_t &elen)
rc_t	next (bool &eof)
void	finish ()
bool	eof ()
	If false, curr() may be called.
tid_t	xid () const
	If false, curr() may be called.
ndx_t	ndx () const
const rc_t &	error_code () const

---

Constructor & Destructor Documentation

NORET scan_index_i::scan_index_i	(	const stid_t &	stid,
		cmp_t	c1,
		const cvec_t &	bound1,
		cmp_t	c2,
		const cvec_t &	bound2,
		bool	include_nulls = false,
		concurrency_t	cc = t_cc_kvl,
		lock_mode_t	mode = SH
	)

Construct an iterator.

Parameters:

[in]	stid	ID of the B-Tree to be scanned.
[in]	c1	Comparison type to be used in the scan for lower bound comparison : eq, gt, ge, lt, le
[in]	bound1	Lower bound
[in]	c2	Comparison type to be used in the scan for upper bound comparison : eq, gt, ge, lt, le
[in]	bound2	Upper bound
[in]	include_nulls	If true, we will consider null keys as satisfying the condition.
[in]	cc	Can be used to override the concurrency_t stored in the store descriptor (see ss_m::get_store_info and sm_store_info_t)) in a few situations.
[in]	mode	Can be used to override the mode in which the store is locked.

The following table describes the way these two values are used. The columns represent the values of this parameter, cc. The rows represent the value with which the store was created, and may be determined with ss_m::get_store_info. The table entries tell what kinds of locks are acquired on the store and on the key-value pairs.

        cc | t_cc_none | t_cc_modkvl | t_cc_im   | t_cc_kvl  | t_cc_file
Created    |
-------------------------------------------------------------------
t_cc_none  | IS/none   | IS/modkvl   | IS/im     | IS/kvl    | SH/none
-------------------------------------------------------------------
t_cc_modkvl| IS/none   | IS/none     | IS/modkvl | IS/modkvl | SH/none  
-------------------------------------------------------------------
t_cc_im    | IS/im     | IS/im       | IS/im     | IS/im     | SH/file 
-------------------------------------------------------------------
t_cc_kvl   | IS/kvl    | IS/kvl      | IS/kvl    | IS/kvl    | SH/file
-------------------------------------------------------------------
t_cc_file  | error     | error       | error     | error     | SH/none
-------------------------------------------------------------------
      

The protocol t_cc_modkvl is a modified key-value locking protocol created for the Paradise project, and behaves as follows: -only allow "eq" comparsons : bound1 : eq X and boudn2: eq X -grabs an SH lock on the bound X, whether or not the index is unique

The protocol t_cc_im treats the value part of a key-value pair as a record id, and it acquires a lock on the record rather than on they key-value pair. Otherwise it is like normal key-value locking.

Although they are called "lower bound" and "upper bound", technically the two conditions can be reversed, for example, c1= le, bound1= vec_t::pos_inf and c2= ge, bound2= vec_t::neg_inf.

---

Member Function Documentation

rc_t scan_index_i::curr	(	vec_t *	key,
		smsize_t &	klen,
		vec_t *	el,
		smsize_t &	elen
	)			[inline]

brief Get the key and value where the cursor points.

Parameters:

[out]	key	Pointer to vector supplied by caller. curr() writes into this vector. A null pointer indicates that the caller is not interested in the key.
[out]	klen	Pointer to sm_size_t variable. Length of key is written here.
[out]	el	Pointer to vector supplied by caller. curr() writes into this vector. A null pointer indicates that the caller is not interested in the value.
[out]	elen	Pointer to sm_size_t variable. Length of value is written here.

Definition at line 243 of file scan.h.

rc_t scan_index_i::next

(

bool &

eof

)

[inline]

brief Move to the next key-value pair in the index.

Parameters:

[out]

eof

True is returned if there are no more pairs in the index. If false, curr() may be called.

Definition at line 256 of file scan.h.

References w_rc_t::reset().

Here is the call graph for this function:

void scan_index_i::finish

(

)

Free the resources used by this iterator. Called by desctructor if necessary.

---

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

• src/sm/scan.h

---