SOS: Scalable Object Store
4.0.0
|
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) |
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.
attr | The schema attribute handle |
sos_iter_t | for the specified attribute |
NULL | The attribute is not indexed |
sos_obj_t sos_filter_begin | ( | sos_filter_t | filt | ) |
Return the first matching object.
filt | The filter handle. |
!NULL | Pointer to the matching sos_obj_t. |
NULL | No 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.
filt | The filter handle returned by sos_filter_new() |
attr | The object attribute that will be evaluated by this condition |
cond_e | One of the sos_cond_e comparison conditions |
value | The value used in the expression "object-attribute-value cond_e value" |
0 | The condition was added successfully |
ENOMEM | There was insufficient memory to allocate the filter condition |
sos_obj_t sos_filter_next | ( | sos_filter_t | filt | ) |
Return the next matching object.
filt | The filter handle. |
!NULL | Pointer to the matching sos_obj_t. |
NULL | No 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.
index | The index handle |
sos_iter_t | for the specified index |
NULL | If there was an error creating the iterator. |
sos_attr_t sos_iter_attr | ( | sos_iter_t | iter | ) |
Return the attribute associated with the iterator.
iter | The iterator handle |
int sos_iter_begin | ( | sos_iter_t | i | ) |
Position the iterator at the first object.
i | The iterator handle |
uint64_t sos_iter_card | ( | sos_iter_t | iter | ) |
Return the number of positions in the iterator.
iter | The iterator handle |
uint64_t sos_iter_dups | ( | sos_iter_t | iter | ) |
Return the number of duplicates in the index.
int sos_iter_end | ( | sos_iter_t | i | ) |
Position the iterator at the last object in the index
i | The iterator handle |
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.
iter | The iterator handle |
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.
iter | Handle for the iterator. |
key | The key for the iterator. The appropriate index will be searched to find the object that matches the key. |
0 | Iterator is positioned at matching object. |
ENOENT | No 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.
iter | Handle for the iterator. |
key | The key for the iterator. The appropriate index will be searched to find the object that matches the key. |
0 | Iterator is positioned at matching object. |
ENOENT | No 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.
iter | Handle for the iterator. |
key | The key for the iterator. The appropriate index will be searched to find the object that matches the key. |
0 | Iterator is positioned at matching object. |
ENOENT | No matching object was found. |
sos_iter_flags_t sos_iter_flags_get | ( | sos_iter_t | iter | ) |
Get the iterator behavior flags.
iter | The iterator |
The | sos_iter_flags_t for the iterator |
int sos_iter_flags_set | ( | sos_iter_t | iter, |
sos_iter_flags_t | flags | ||
) |
Set iterator behavior flags.
i | The iterator |
flags | The iterator flags |
0 | The flags were set successfully |
EINVAL | The iterator or flags were invalid |
void sos_iter_free | ( | sos_iter_t | iter | ) |
Release the resources associated with a SOS iterator.
iter | The 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)
i | Pointer to the iterator |
key | The key. |
0 | if the iterator is positioned at the infinum |
ENOENT | if 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.
iter | The iterator handle |
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);
iter | The iterator handle |
other | The other key |
<0 | iter < other |
0 | iter == other |
>0 | iter > 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.
iter | The iterator handle |
0 | The iterator is positioned at the next object in the index |
ENOENT | No more entries in the index |
sos_obj_t sos_iter_obj | ( | sos_iter_t | i | ) |
Return the object at the current iterator position.
iter | The iterator handle |
int sos_iter_pos_get | ( | sos_iter_t | iter, |
sos_pos_t * | pos | ||
) |
Returns the current iterator position.
i | The iterator handle |
pos | The sos_pos_t that will receive the position value. |
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.
i | The iterator handle |
pos | The iterator cursor position |
0 | Success |
ENOENT | The 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.
i | The iterator handle |
pos | The iterator cursor position |
0 | Success |
ENOENT | The position was not found, or has already been used |
EINVAL | The 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.
i | Iterator handle |
sos_obj_ref_t sos_iter_ref | ( | sos_iter_t | i | ) |
Return the object reference at the current iterator position.
iter | The iterator handle |
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)
i | Pointer to the iterator |
key | The key. |
0 | The iterator is positioned at the supremum |
ENOENT | No supremum exists |