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

Macros

#define SOS_INDEX_RT_OPT_MP_UNSAFE   1
 
#define SOS_INDEX_RT_OPT_VISIT_ASYNC   2
 

Typedefs

typedef int(* sos_ins_cb_fn_t )(sos_index_t index, sos_key_t key, int missing, sos_obj_ref_t *ref, void *arg)
 
typedef enum sos_visit_action sos_visit_action_t
 
typedef sos_visit_action_t(* sos_visit_cb_fn_t )(sos_index_t index, sos_key_t key, sos_idx_data_t *idx_data, int found, void *arg)
 
typedef uint32_t sos_index_rt_opt_t
 
typedef struct
sos_container_index_iter_s
sos_container_index_iter_t
 

Enumerations

enum  sos_visit_action { SOS_VISIT_ADD = ODS_VISIT_ADD, SOS_VISIT_DEL = ODS_VISIT_DEL, SOS_VISIT_UPD = ODS_VISIT_UPD, SOS_VISIT_NOP = ODS_VISIT_NOP }
 

Functions

sos_obj_t sos_obj_find (sos_attr_t attr, sos_key_t key)
 
int sos_index_new (sos_t sos, const char *name, const char *idx_type, const char *key_type, const char *args)
 Create a new Index. More...
 
sos_index_t sos_index_open (sos_t sos, const char *name)
 Open an existing Index. More...
 
int sos_index_rt_opt_set (sos_index_t index, sos_index_rt_opt_t opt,...)
 
int sos_index_insert (sos_index_t index, sos_key_t key, sos_obj_t obj)
 Add an object to an index. More...
 
int sos_index_remove (sos_index_t index, sos_key_t key, sos_obj_t obj)
 Remove a key from an index. More...
 
int sos_index_visit (sos_index_t index, sos_key_t key, sos_visit_cb_fn_t cb_fn, void *arg)
 Visit the key entry in the index. More...
 
sos_obj_t sos_index_find (sos_index_t index, sos_key_t key)
 Find an object in the index by it's key. More...
 
int sos_index_find_ref (sos_index_t index, sos_key_t key, sos_obj_ref_t *ref)
 Find a key in the index and return the ref. More...
 
sos_obj_t sos_index_find_inf (sos_index_t index, sos_key_t key)
 Find the infinum (greatest lower bound) of the specified key. More...
 
sos_obj_t sos_index_find_sup (sos_index_t index, sos_key_t key)
 Find the supremum (least upper bound) of the specified key. More...
 
int sos_index_commit (sos_index_t index, sos_commit_t flags)
 Commit an Index's data to stable storage. More...
 
int sos_index_close (sos_index_t index, sos_commit_t flags)
 Close the index and commit changes to storage. More...
 
size_t sos_index_key_size (sos_index_t index)
 Return the size of the index's key. More...
 
sos_key_t sos_index_key_new (sos_index_t index, size_t size)
 Create a key based on the specified index or size. More...
 
int sos_index_key_from_str (sos_index_t index, sos_key_t key, const char *str)
 Set the value of a key from a string. More...
 
const char * sos_index_key_to_str (sos_index_t index, sos_key_t key)
 Return a string representation of the key value. More...
 
int sos_index_key_cmp (sos_index_t index, sos_key_t a, sos_key_t b)
 Compare two keys using the index's compare function. More...
 
void sos_index_print (sos_index_t index, FILE *fp)
 
const char * sos_index_name (sos_index_t index)
 Return the index's name. More...
 
int sos_index_stat (sos_index_t index, sos_index_stat_t sb)
 Return the statistics of the Index. More...
 
void sos_container_index_list (sos_t sos, FILE *fp)
 
sos_container_index_iter_t sos_container_index_iter_new (sos_t sos)
 
void sos_container_index_iter_free (sos_container_index_iter_t iter)
 
sos_index_t sos_container_index_iter_first (sos_container_index_iter_t iter)
 
sos_index_t sos_container_index_iter_next (sos_container_index_iter_t iter)
 

Detailed Description

Enumeration Type Documentation

Enumerator
SOS_VISIT_DEL 

Add the key and set it's data to idx_data

SOS_VISIT_UPD 

Delete the key

SOS_VISIT_NOP 

Update the index data for key

Function Documentation

int sos_index_close ( sos_index_t  index,
sos_commit_t  flags 
)

Close the index and commit changes to storage.

index The index handle flags The commit flags: SOS_COMMIT_SYNC, SOS_COMMIT_ASYNC

Return values
0Success
!0A unix errno
int sos_index_commit ( sos_index_t  index,
sos_commit_t  flags 
)

Commit an Index's data to stable storage.

Parameters
indexThe Index handle
flagsThe commit flags
Return values
0Success
!0A Unix error code
sos_obj_t sos_index_find ( sos_index_t  index,
sos_key_t  key 
)

Find an object in the index by it's key.

Parameters
indexThe index handle
keyThe key
Return values
!NULLThe object associated with the key
NULLThe object was not found
sos_obj_t sos_index_find_inf ( sos_index_t  index,
sos_key_t  key 
)

Find the infinum (greatest lower bound) of the specified key.

Parameters
indexThe index handle
keyThe key
Return values
!NULLThe object associated with the key
NULLThe object was not found
int sos_index_find_ref ( sos_index_t  index,
sos_key_t  key,
sos_obj_ref_t ref 
)

Find a key in the index and return the ref.

Parameters
indexThe index handle
keyThe key
refPointer to sos_obj_ref_t
Return values
0The key was found and ref contains the data
ENOENTThe key was not found
sos_obj_t sos_index_find_sup ( sos_index_t  index,
sos_key_t  key 
)

Find the supremum (least upper bound) of the specified key.

Parameters
indexThe index handle
keyThe key
Return values
!NULLThe object associated with the key
NULLThe object was not found
int sos_index_insert ( sos_index_t  index,
sos_key_t  key,
sos_obj_t  obj 
)

Add an object to an index.

Parameters
indexThe index handle
keyThe key
objThe object to which the key will refer
Return values
0Success
EINVALThe object or index is invalid
!0A Unix error code
int sos_index_key_cmp ( sos_index_t  index,
sos_key_t  a,
sos_key_t  b 
)

Compare two keys using the index's compare function.

Parameters
indexThe index handle
aThe first key
bThe second key
Returns
<0 a < b
0 a == b
>0 a > b
int sos_index_key_from_str ( sos_index_t  index,
sos_key_t  key,
const char *  str 
)

Set the value of a key from a string.

Parameters
indexThe index handle
keyThe key
strPointer to a string
Return values
0if successful
-1if there was an error converting the string to a value
sos_key_t sos_index_key_new ( sos_index_t  index,
size_t  size 
)

Create a key based on the specified index or size.

Create a new SOS key for the specified index. If the size is specified, the index parameter is ignored and the key is based on the specified size.

Parameters
indexThe index handle
sizeThe desired key size
Return values
Apointer to the new key or NULL if there is an error
size_t sos_index_key_size ( sos_index_t  index)

Return the size of the index's key.

Returns the native size of the index's key values. If the key value is variable size, this function returns -1. See the sos_key_len() and sos_key_size() functions for the current size of the key's value and the size of the key's buffer respectively.

Returns
The native size of the index's keys in bytes
const char* sos_index_key_to_str ( sos_index_t  index,
sos_key_t  key 
)

Return a string representation of the key value.

Parameters
indexThe index handle
keyThe key
Returns
A const char * representation of the key value.
const char* sos_index_name ( sos_index_t  index)

Return the index's name.

Parameters
indexThe index handle
Return values
Theindex name
int sos_index_new ( sos_t  sos,
const char *  name,
const char *  idx_type,
const char *  key_type,
const char *  idx_args 
)

Create a new Index.

Parameters
sosThe container handle
nameThe unique index name
idx_typeThe index type, e.g. "BXTREE"
key_typeThe key type, e.g. "UINT64"
idx_argsThe index type specific arguments, e.g. "ORDER=5" for a B+Tree
Return values
0Success
!0A Unix error code
sos_index_t sos_index_open ( sos_t  sos,
const char *  name 
)

Open an existing Index.

Parameters
sosThe container handle
nameThe unique index name
Return values
0Success
!0A Unix error code
int sos_index_remove ( sos_index_t  index,
sos_key_t  key,
sos_obj_t  obj 
)

Remove a key from an index.

Remove a key/value from the index. Note that the function takes an object as a paramter. This is necessary to discriminate when multiple objects are referred to by the same key.

Parameters
indexThe index handle
keyThe key
objThe specific object to which the key will refer
Return values
0Success
!0A Unix error code
int sos_index_stat ( sos_index_t  index,
sos_index_stat_t  sb 
)

Return the statistics of the Index.

Parameters
indexThe index handle
Return values
0Success
!0A Unix errno
int sos_index_visit ( sos_index_t  index,
sos_key_t  key,
sos_visit_cb_fn_t  cb_fn,
void *  arg 
)

Visit the key entry in the index.

Find the key in the index and call the visit callback function with the index, the key, a 1 or 0 to indicate if the key was found, a pointer to a sos_idx_data_t structure, and the ctxt passed to sos_index_update(). If the found parameter to the cb_fn() is 1, the the idx_data structure contains the index data for the key. If the found parameter is 0, the contents of this structure are undefined.

The cb_fn() must return one of the following value:

  • SOS_VISIT_ADD - Add the key and set the key data to the contents of the idx_data structure. This return value is ignored if found is true and sos_index_visit() will return EINVAL.
  • SOS_VISIT_DEL - Delete the key from the index. If found is false, this value is ignored and sos_index_visit() will return EINVAL.
  • SOS_VISIT_UPD - Update the index data at this key with the contents of the idx_data structure. If found is false, this value is ignored and sos_index_visit() will return EINVAL.
  • SOS_VISIT_NOP - Do nothing