SOS: Scalable Object Store  4.0.0
 All Classes Functions Variables Typedefs Enumerations Enumerator Groups Pages
Iterator Functions

Functions

sos_iter_t sos_index_iter_new (sos_index_t index)
 Create a SOS iterator from an index. More...
 
sos_iter_t sos_attr_iter_new (sos_attr_t attr)
 Create a SOS iterator from an attribute index. More...
 
void sos_iter_free (sos_iter_t iter)
 Release the resources associated with a SOS iterator. More...
 
int sos_iter_key_cmp (sos_iter_t iter, sos_key_t other)
 Compare iterator object's key with other key. More...
 
int sos_iter_find (sos_iter_t iter, sos_key_t key)
 Position the iterator at the specified key. More...
 
int sos_iter_find_first (sos_iter_t iter, sos_key_t key)
 Position the iterator at the first instance of the specified key. More...
 
int sos_iter_find_last (sos_iter_t iter, sos_key_t key)
 Position the iterator at the last instance of the specified key. More...
 
int sos_iter_inf (sos_iter_t i, sos_key_t key)
 Position the iterator at the infinum of the specified key. More...
 
int sos_iter_sup (sos_iter_t i, sos_key_t key)
 Position the iterator at the supremum of the specified key. More...
 
sos_attr_t sos_iter_attr (sos_iter_t i)
 Return the attribute associated with the iterator. More...
 
int sos_iter_flags_set (sos_iter_t i, sos_iter_flags_t flags)
 Set iterator behavior flags. More...
 
sos_iter_flags_t sos_iter_flags_get (sos_iter_t i)
 Get the iterator behavior flags. More...
 
uint64_t sos_iter_card (sos_iter_t i)
 Return the number of positions in the iterator. More...
 
uint64_t sos_iter_dups (sos_iter_t i)
 Return the number of duplicates in the index. More...
 
int sos_iter_pos_set (sos_iter_t i, sos_pos_t pos)
 Sets the current iterator position. More...
 
int sos_iter_pos_get (sos_iter_t i, sos_pos_t *pos)
 Returns the current iterator position. More...
 
int sos_iter_pos_put (sos_iter_t i, sos_pos_t pos)
 Indicates to the iterator that this position is no longer in-use. More...
 
int sos_pos_from_str (sos_pos_t *pos, const char *str)
 
const char * sos_pos_to_str (sos_pos_t pos)
 
void sos_pos_str_free (char *pos_str)
 
int sos_iter_next (sos_iter_t iter)
 Position the iterator at next object in the index. More...
 
int sos_iter_prev (sos_iter_t i)
 Retrieve the next object from the iterator. More...
 
int sos_iter_begin (sos_iter_t i)
 
int sos_iter_end (sos_iter_t i)
 
sos_key_t sos_iter_key (sos_iter_t iter)
 Return the key at the current iterator position. More...
 
sos_obj_t sos_iter_obj (sos_iter_t iter)
 Return the object at the current iterator position. More...
 
sos_obj_ref_t sos_iter_ref (sos_iter_t iter)
 Return the object reference at the current iterator position. More...
 
int sos_iter_entry_remove (sos_iter_t iter)
 Remove the index entry at the current iterator position. More...
 
sos_filter_t sos_filter_new (sos_iter_t iter)
 
void sos_filter_free (sos_filter_t f)
 
int sos_filter_cond_add (sos_filter_t f, sos_attr_t attr, enum sos_cond_e cond_e, sos_value_t value)
 Add a filter condition to the filter. More...
 
sos_filter_cond_t sos_filter_eval (sos_obj_t obj, sos_filter_t filt, int *ret)
 
sos_obj_t sos_filter_begin (sos_filter_t filt)
 Return the first matching object. More...
 
sos_obj_t sos_filter_next (sos_filter_t filt)
 Return the next matching object. More...
 
sos_obj_t sos_filter_skip (sos_filter_t filt, int count)
 
sos_obj_t sos_filter_prev (sos_filter_t filt)
 
sos_obj_t sos_filter_end (sos_filter_t filt)
 
int sos_filter_pos_set (sos_filter_t filt, const sos_pos_t pos)
 
int sos_filter_pos_get (sos_filter_t filt, sos_pos_t *pos)
 
int sos_filter_pos_put (sos_filter_t filt, const sos_pos_t pos)
 
sos_obj_t sos_filter_obj (sos_filter_t filt)
 
int sos_filter_flags_set (sos_filter_t filt, sos_iter_flags_t flags)
 

Detailed Description

Function Documentation

sos_iter_t sos_attr_iter_new ( sos_attr_t  attr)

Create a SOS iterator from an attribute index.

Create an iterator on the specified attribute. If there is no index defined on the iterator, the function will fail.

Parameters
attrThe schema attribute handle
Return values
sos_iter_tfor the specified attribute
NULLThe attribute is not indexed
sos_obj_t sos_filter_begin ( sos_filter_t  filt)

Return the first matching object.

Parameters
filtThe filter handle.
Return values
!NULLPointer to the matching sos_obj_t.
NULLNo object's matched all of the filter conditions.
int sos_filter_cond_add ( sos_filter_t  filt,
sos_attr_t  attr,
enum sos_cond_e  cond_e,
sos_value_t  value 
)

Add a filter condition to the filter.

The filter conditions affect which objects are returned by sos_filter_begin(), sos_filter_next(), etc...

Logically, all filter conditions are ANDed together to get a TRUE/FALSE answer when evaluating an object. If all filter conditions match, the sos_filter_xxx() iterator functions will return the object, otherwise, the next object in the index will be evaluated until a match is found or all objects in the index are exhausted.

Parameters
filtThe filter handle returned by sos_filter_new()
attrThe object attribute that will be evaluated by this condition
cond_eOne of the sos_cond_e comparison conditions
valueThe value used in the expression "object-attribute-value cond_e value"
Return values
0The condition was added successfully
ENOMEMThere was insufficient memory to allocate the filter condition
sos_obj_t sos_filter_next ( sos_filter_t  filt)

Return the next matching object.

Parameters
filtThe filter handle.
Return values
!NULLPointer to the matching sos_obj_t.
NULLNo object's matched all of the filter conditions.
sos_iter_t sos_index_iter_new ( sos_index_t  index)

Create a SOS iterator from an index.

Create an iterator on the specified index.

Parameters
indexThe index handle
Return values
sos_iter_tfor the specified index
NULLIf there was an error creating the iterator.
sos_attr_t sos_iter_attr ( sos_iter_t  iter)

Return the attribute associated with the iterator.

Parameters
iterThe iterator handle
Returns
A pointer to the attribute or NULL if the iterator is not associated with a schema attribute.
int sos_iter_begin ( sos_iter_t  i)

Position the iterator at the first object.

Parameters
iThe iterator handle
Returns
0 The iterator is positioned at the first object in the index
ENOENT The index is empty
uint64_t sos_iter_card ( sos_iter_t  iter)

Return the number of positions in the iterator.

Parameters
iterThe iterator handle
Returns
The cardinality of the iterator
uint64_t sos_iter_dups ( sos_iter_t  iter)

Return the number of duplicates in the index.

Returns
The count of duplicates
int sos_iter_end ( sos_iter_t  i)

Position the iterator at the last object in the index

Parameters
iThe iterator handle
Returns
0 The iterator is positioned at the last object in the index
ENOENT The index is empty
int sos_iter_entry_remove ( sos_iter_t  iter)

Remove the index entry at the current iterator position.

Removes the index entry at the current cursor position. After removal, the iterator points at the next entry if it exists, or empty if the tail was deleted.

Parameters
iterThe iterator handle
Returns
0 on success.
Error code on failure.
int sos_iter_find ( sos_iter_t  iter,
sos_key_t  key 
)

Position the iterator at the specified key.

If the index contains duplicate keys, the iterator will be positioned at the first instance of the specified key.

Parameters
iterHandle for the iterator.
keyThe key for the iterator. The appropriate index will be searched to find the object that matches the key.
Return values
0Iterator is positioned at matching object.
ENOENTNo matching object was found.
int sos_iter_find_first ( sos_iter_t  iter,
sos_key_t  key 
)

Position the iterator at the first instance of the specified key.

Parameters
iterHandle for the iterator.
keyThe key for the iterator. The appropriate index will be searched to find the object that matches the key.
Return values
0Iterator is positioned at matching object.
ENOENTNo matching object was found.
int sos_iter_find_last ( sos_iter_t  iter,
sos_key_t  key 
)

Position the iterator at the last instance of the specified key.

Parameters
iterHandle for the iterator.
keyThe key for the iterator. The appropriate index will be searched to find the object that matches the key.
Return values
0Iterator is positioned at matching object.
ENOENTNo matching object was found.
sos_iter_flags_t sos_iter_flags_get ( sos_iter_t  iter)

Get the iterator behavior flags.

Parameters
iterThe iterator
Return values
Thesos_iter_flags_t for the iterator
int sos_iter_flags_set ( sos_iter_t  iter,
sos_iter_flags_t  flags 
)

Set iterator behavior flags.

Parameters
iThe iterator
flagsThe iterator flags
Return values
0The flags were set successfully
EINVALThe iterator or flags were invalid
void sos_iter_free ( sos_iter_t  iter)

Release the resources associated with a SOS iterator.

Parameters
iterThe iterator returned by sos_new_iter
int sos_iter_inf ( sos_iter_t  i,
sos_key_t  key 
)

Position the iterator at the infinum of the specified key.

Position the iterator at the object whose key is the greatest lower bound of the specified key.

If the infininum is a duplicate key, the cursor is positioned at the first instance of the key.

This behavior can be changed using the sos_iter_flags_set() function to set the SOS_ITER_F_INF_LAST_DUP option. This will cause this function to place the iterator position at the last duplicate. Note that this may break the axiom that INF(set) <= SUP(set)

Parameters
iPointer to the iterator
keyThe key.
Return values
0if the iterator is positioned at the infinum
ENOENTif the infinum does not exist
sos_key_t sos_iter_key ( sos_iter_t  iter)

Return the key at the current iterator position.

Return the key associated with the current iterator position. This key is persistent and reference counted. Use the sos_key_put() function to drop the reference given by this function when finished with the key.

Parameters
iterThe iterator handle
Returns
sos_key_t at the current position
int sos_iter_key_cmp ( sos_iter_t  iter,
sos_key_t  key 
)

Compare iterator object's key with other key.

This function compare the key of the object pointed by the iterator with the other key. This is a convenience routine and is equivalent to the following code sequence:

sos_key_t iter_key = sos_iter_key(iter);
int rc = sos_key_cmp(attr, iter_key, other);
sos_key_put(iter_key);
Parameters
iterThe iterator handle
otherThe other key
Return values
<0iter < other
0iter == other
>0iter > other
int sos_iter_next ( sos_iter_t  i)

Position the iterator at next object in the index.

Advance the iterator position to the next entry.

Parameters
iterThe iterator handle
Return values
0The iterator is positioned at the next object in the index
ENOENTNo more entries in the index
sos_obj_t sos_iter_obj ( sos_iter_t  i)

Return the object at the current iterator position.

Parameters
iterThe iterator handle
Returns
sos_obj_t at the current position
int sos_iter_pos_get ( sos_iter_t  iter,
sos_pos_t *  pos 
)

Returns the current iterator position.

Parameters
iThe iterator handle
posThe sos_pos_t that will receive the position value.
Returns
The current iterator position or 0 if position is invalid
int sos_iter_pos_put ( sos_iter_t  iter,
const sos_pos_t  pos 
)

Indicates to the iterator that this position is no longer in-use.

Parameters
iThe iterator handle
posThe iterator cursor position
Return values
0Success
ENOENTThe iterator position is invalid
int sos_iter_pos_set ( sos_iter_t  iter,
const sos_pos_t  pos 
)

Sets the current iterator position.

Set the iterator position at the location specified by the pos parameter. Pos objects are single use, which means that after they are used, the pos is deleted and cannot be reused.

Parameters
iThe iterator handle
posThe iterator cursor position
Return values
0Success
ENOENTThe position was not found, or has already been used
EINVALThe position object is for a different index
int sos_iter_prev ( sos_iter_t  i)

Retrieve the next object from the iterator.

Advance the iterator position to the previous entry.

Parameters
iIterator handle
Returns
0 The iterator is positioned at the previous entry
ENOENT If no more matching records were found.
sos_obj_ref_t sos_iter_ref ( sos_iter_t  i)

Return the object reference at the current iterator position.

Parameters
iterThe iterator handle
Returns
sos_obj_ref_t at the current position
int sos_iter_sup ( sos_iter_t  i,
sos_key_t  key 
)

Position the iterator at the supremum of the specified key.

Position the iterator at the object whose key is the least upper bound of the specified key.

If the supremum is a duplicate key, the cursor is positioned at the first instance of the key.

This behavior can be changed using the sos_iter_flags_set() function to set the SOS_ITER_F_SUP_LAST_DUP option. This will cause this function to place the iterator position at the last duplicate. Note that this may break the axiom that INF(set) <= SUP(set)

Parameters
iPointer to the iterator
keyThe key.
Return values
0The iterator is positioned at the supremum
ENOENTNo supremum exists