SOS: Scalable Object Store
4.0.0
|
Functions | |
sos_schema_t | sos_schema_new (const char *name) |
Create a schema. More... | |
void | sos_schema_free (sos_schema_t schema) |
sos_schema_t | sos_schema_dup (sos_schema_t schema) |
Create a copy of a schema. More... | |
size_t | sos_schema_count (sos_t sos) |
Return the number of schema in container. More... | |
int | sos_schema_add (sos_t sos, sos_schema_t schema) |
Add a schema to a container. More... | |
sos_schema_t | sos_schema_from_template (sos_schema_template_t t) |
Create a schema from a SOS template. More... | |
sos_schema_t | sos_schema_by_name (sos_t sos, const char *name) |
Find the schema with the specified name. More... | |
sos_schema_t | sos_schema_by_id (sos_t sos, uint32_t id) |
Find a schema by id. More... | |
void | sos_schema_print (sos_schema_t schema, FILE *fp) |
Print the schema to a File pointer. More... | |
int | sos_schema_delete (sos_t sos, const char *name) |
Remove a schema from a container. More... | |
sos_schema_t | sos_schema_first (sos_t sos) |
Return a handle to the first schema in the container. More... | |
sos_schema_t | sos_schema_next (sos_schema_t schema) |
Return a handle to the next schema in the container. More... | |
const char * | sos_schema_name (sos_schema_t schema) |
Returns the schema's name. More... | |
int | sos_schema_id (sos_schema_t schema) |
Return the schema's unique id. More... | |
int | sos_schema_attr_count (sos_schema_t schema) |
Return the number of attributes in the schema. More... | |
int | sos_schema_attr_add (sos_schema_t schema, const char *name, sos_type_t type,...) |
Add an attribute to a schema. More... | |
int | sos_schema_index_add (sos_schema_t schema, const char *attr_name) |
Add an index to an attribute. More... | |
int | sos_schema_index_modify (sos_schema_t schema, const char *name, const char *idx_type, const char *key_type, const char *idx_args) |
Modify the index for an attribute. More... | |
sos_attr_t | sos_schema_attr_by_name (sos_schema_t schema, const char *name) |
Find an attribute by name. More... | |
sos_attr_t | sos_schema_attr_by_id (sos_schema_t schema, int attr_id) |
Find an attribute by id. More... | |
sos_attr_t | sos_schema_attr_first (sos_schema_t schema) |
sos_attr_t | sos_schema_attr_last (sos_schema_t schema) |
sos_attr_t | sos_schema_attr_next (sos_attr_t attr) |
sos_attr_t | sos_schema_attr_prev (sos_attr_t attr) |
int | sos_attr_id (sos_attr_t attr) |
Return the attribute's ordinal ID. More... | |
const char * | sos_attr_name (sos_attr_t attr) |
Return the attribute's name. More... | |
sos_type_t | sos_attr_type (sos_attr_t attr) |
Return the attribute's type. More... | |
sos_index_t | sos_attr_index (sos_attr_t attr) |
Test if an attribute has an index. More... | |
size_t | sos_attr_size (sos_attr_t attr) |
Return the size of an attribute's data. More... | |
sos_schema_t | sos_attr_schema (sos_attr_t attr) |
Return the schema of an attribute. More... | |
sos_array_t | sos_attr_join_list (sos_attr_t attr) |
Return an array with the list of attributes in the join list. More... | |
int | sos_obj_attr_by_name_from_str (sos_obj_t sos_obj, const char *attr_name, const char *attr_value, char **endptr) |
Set an object attribute's value from a string. More... | |
size_t | sos_obj_attr_strlen (sos_obj_t obj, sos_attr_t attr) |
Return the length of the string required for the object value. More... | |
int | sos_attr_is_ref (sos_attr_t attr) |
Return !0 if the attribute is a reference. | |
int | sos_attr_is_array (sos_attr_t attr) |
Return !0 if the attribute is an array. | |
void * | sos_obj_ptr (sos_obj_t obj) |
Return a pointer to the object's data. More... | |
size_t | sos_array_count (sos_value_t val) |
sos_value_t | sos_array_new (sos_value_t val, sos_attr_t attr, sos_obj_t obj, size_t count) |
sos_obj_t | sos_array_obj_new (sos_t sos, sos_type_t type, size_t count) |
int | sos_value_is_array (sos_value_t v) |
Return !0 if the value is an array. | |
sos_type_t | sos_value_type (sos_value_t v) |
Return the value's type. More... | |
size_t | sos_value_size (sos_value_t value) |
Get the size of an attribute value. More... | |
void * | sos_value_as_key (sos_value_t value) |
char * | sos_obj_attr_to_str (sos_obj_t obj, sos_attr_t attr, char *str, size_t len) |
Format an object attribute as a string. More... | |
int | sos_obj_attr_from_str (sos_obj_t obj, sos_attr_t attr, const char *str, char **endptr) |
Set the object attribute from a string. More... | |
int sos_attr_id | ( | sos_attr_t | attr | ) |
Return the attribute's ordinal ID.
attr | The attribute handle. |
sos_index_t sos_attr_index | ( | sos_attr_t | attr | ) |
Test if an attribute has an index.
attr | The sos_attr_t handle |
sos_array_t sos_attr_join_list | ( | sos_attr_t | attr | ) |
Return an array with the list of attributes in the join list.
The function will return NULL if the attribute is not of the type SOS_TYPE_JOIN.
retval->count - The attribute count. retval->data.uint32_[0..count-1] - The id of each attribute
attr | The attribute handle |
const char * sos_attr_name | ( | sos_attr_t | attr | ) |
Return the attribute's name.
sos_schema_t sos_attr_schema | ( | sos_attr_t | attr | ) |
Return the schema of an attribute.
attr | The attribute handle |
size_t sos_attr_size | ( | sos_attr_t | attr | ) |
Return the size of an attribute's data.
attr | The sos_attr_t handle |
sos_type_t sos_attr_type | ( | sos_attr_t | attr | ) |
Return the attribute's type.
int sos_obj_attr_by_name_from_str | ( | sos_obj_t | sos_obj, |
const char * | attr_name, | ||
const char * | attr_value, | ||
char ** | endptr | ||
) |
Set an object attribute's value from a string.
This convenience function set's an object's attribute value specified as a string. The attribute to set is specified by name.
For example:
int rc = sos_obj_attr_by_name_from_str(an_obj, "my_int_attr", "1234"); if (!rc) printf("Success!!\n");
See the sos_obj_attr_from_str() function to set the value with a string if the attribute handle is known.
sos_obj | The object handle |
attr_name | The attribute name |
attr_value | The attribute value as a string |
endptr | Receives the point in the str argumeent where parsing stopped. This parameter may be NULL. |
0 | Success |
EINVAL | The string format was invalid for the attribute type |
ENOSYS | There is no string formatter for this attribute type |
int sos_obj_attr_from_str | ( | sos_obj_t | obj, |
sos_attr_t | attr, | ||
const char * | str, | ||
char ** | endptr | ||
) |
Set the object attribute from a string.
obj | The object handle |
attr | The attribute handle |
str | The input string value to parse |
endptr | Receives the point in the str argumeent where parsing stopped. This parameter may be NULL. |
0 | The string was successfully parsed and the value set |
EINVAL | The string was incorrectly formatted for this value type. |
size_t sos_obj_attr_strlen | ( | sos_obj_t | obj, |
sos_attr_t | attr | ||
) |
Return the length of the string required for the object value.
This function returns the size of the buffer required to hold the object attribute value if formatted as a string. This function is useful when allocating buffers used with the sos_obj_attr_to_str() function.
obj | The object handle |
attr | The attribute handle |
char* sos_obj_attr_to_str | ( | sos_obj_t | obj, |
sos_attr_t | attr, | ||
char * | str, | ||
size_t | len | ||
) |
Format an object attribute as a string.
obj | The object handle |
attr | The attribute handle |
str | Pointer to the string to receive the formatted value |
len | The size of the string in bytes. |
void* sos_obj_ptr | ( | sos_obj_t | obj | ) |
Return a pointer to the object's data.
This function returns a pointer to the object's internal data. The application is responsible for understanding the internal format. The application must call sos_obj_put() when finished with the object to avoid a memory leak.
This function is intended to be used when the schema of the object is well known by the application. If the application is generic for all objects, see the sos_value() functions.
obj |
void | * pointer to the objects's data |
int sos_schema_add | ( | sos_t | sos, |
sos_schema_t | schema | ||
) |
Add a schema to a container.
A a new schema to the container. A schema with the same name must not already exist in the container.
sos | The container handle |
schema | Pointer to the new schema |
0 | The schema was successfully added |
EEXIST | A schema with the same name already exists in the container. |
ENOMEM | Insufficient resources |
EINVAL | An invalid parameter was specified. |
int sos_schema_attr_add | ( | sos_schema_t | schema, |
const char * | name, | ||
sos_type_t | type, | ||
... | |||
) |
Add an attribute to a schema.
Add an attribute to a schema. The schema can only be modified if it is not already a member of the container.
rc = sos_schema_attr_add(s, "an_int32_attr", SOS_TYPE_INT32); rc = sos_schema_attr_add(s, "a_float_attr", SOS_TYPE_FLOAT); rc = sos_schema_attr_add(s, "a_struct_attr", SOS_TYPE_STRUCT, 24); // 24B untyped value rc = sos_schema_attr_add(s, "a_float_array", SOS_TYPE_FLOAT_ARRAY); // Arrays have strict element type, but variable length char *join[] = { "an_int32_attr", "a_float_attr" }; rc = sos_schema_attr_add(s, "a_join_key", SOS_TYPE_JOIN, 2, join); // An attribute that is composed of two other attributes
schema | The schema |
name | The attribute name |
type | The attribute type |
If the type is SOS_TYPE_STRUCT:
size | The size in bytes of the attribute. |
If the type is SOS_TYPE_JOIN:
count | The number of attributes in this key |
cmp_fn | Name of the key comparison function. If NULL, memcmp is used. |
a_1-N | Count additional arguments that specify the attribute names comprising the key |
0 | Success |
ENOMEM | Insufficient resources |
EEXIST | An attribute with that name already exists |
EINUSE | The schema is already a member of a container |
EINVAL | A parameter was invalid |
sos_attr_t sos_schema_attr_by_id | ( | sos_schema_t | schema, |
int | attr_id | ||
) |
Find an attribute by id.
This function is useful for iterating through all attributes in the schema as shown in the following code fragment:
for (i = 0; i < sos_schema_attr_count(schema); i++) { sos_attr_t attr = sos_schema_attr_by_id(i); ... code to manipulate attribute ... }
schema | The schema handle |
attr_id | The attribute's ordinal id |
sos_attr_t sos_schema_attr_by_name | ( | sos_schema_t | schema, |
const char * | name | ||
) |
Find an attribute by name.
schema | The schema handle |
name | The attribute's name |
int sos_schema_attr_count | ( | sos_schema_t | schema | ) |
Return the number of attributes in the schema.
This function returns the number of attributes in the schema. See the sos_schema_attr_by_id() function for an example that iterates through all attributes defined in the schema.
schema | The schema handle. |
The | number of attributes in the schema. |
sos_schema_t sos_schema_by_id | ( | sos_t | sos, |
uint32_t | id | ||
) |
Find a schema by id.
Each schema is assigned a unique identifier when it is created. Find the schema with the specified identifier. The schema returned may be used to create objects of this type in the container.
sos | The container handle |
id | The schema id |
A | pointer to the schema |
NULL | pointer if a schema with that name does not exist in the container |
sos_schema_t sos_schema_by_name | ( | sos_t | sos, |
const char * | name | ||
) |
Find the schema with the specified name.
Find the schema with the specified name. The schema returned may be used to create objects of this type in the container.
sos | The container handle |
name | The name of the schema |
size_t sos_schema_count | ( | sos_t | sos | ) |
Return the number of schema in container.
sos | The container handle |
The | number of schema in the container |
int sos_schema_delete | ( | sos_t | sos, |
const char * | name | ||
) |
Remove a schema from a container.
Remove the schema with the specified name from the container. If there are any objects in the container that use the specified schema, the schema cannot be deleted.
sos | The container handle |
name | The name of the container |
0 | The schema was successfully deleted |
EINUSE | An objects exists in the container that uses the specified schema |
ENOENT | No schema was found with the specified name |
sos_schema_t sos_schema_dup | ( | sos_schema_t | schema | ) |
Create a copy of a schema.
Create a replica of a schema that is not associated with a container. This function is useful for adding a schema from one container to another container.
schema |
A | pointer to the new schema |
NULL | Insufficient resources |
sos_schema_t sos_schema_first | ( | sos_t | sos | ) |
Return a handle to the first schema in the container.
sos | The SOS handle |
The | schema pointer |
NULL | If there are no schema defined in the container |
sos_schema_t sos_schema_from_template | ( | sos_schema_template_t | t | ) |
Create a schema from a SOS template.
This convenience function creates a SOS schema from a structure that specifies the schema name and an array of attribute definitions. For example:
struct sos_schema_template employee = { .name = "employee", .attrs = { { .name = "First", .TYPE = SOS_TYPE_BYTE_ARRAY }, { .name = "Last", .type = SOS_TYPE_BYTE_ARRAY, .indexed = 1 }, { .name = "Salary", .type = SOS_TYPE_FLOAT }, { NULL } // terminates attribute list } }; sos_schema_t schema = sos_schema_from_template(&employee);
t | Pointer to a template structure |
sos_schema_t | created from the structure definition. |
int sos_schema_id | ( | sos_schema_t | schema | ) |
Return the schema's unique id.
Every schema has a unique Id that is stored along with the object in the database. This a llows the object's type to be identified.
schema | The schema handle. |
The | schema Id |
int sos_schema_index_add | ( | sos_schema_t | schema, |
const char * | attr_name | ||
) |
Add an index to an attribute.
Marks an attribute as having a key-value index. The index is not actually created until the schema containing the attribute is added to the container.
schema | The schema handle |
attr_name | The attribute name |
0 | The index was succesfully added. |
ENOENT | The specified attribute does not exist. |
EINVAL | One or more parameters was invalid. |
int sos_schema_index_modify | ( | sos_schema_t | schema, |
const char * | name, | ||
const char * | idx_type, | ||
const char * | key_type, | ||
const char * | idx_args | ||
) |
Modify the index for an attribute.
By default an attribute index is a modified form of a B+Tree that efficiently handles duplicate keys. There are, however, other index types as well as user-defined indices. The type of index is specified as a string that identifies a shared library that implements the necessary index strategy routines, e.g. insert, delete, etc...
For keys, the default key type is associated with the attribute's data type, however, it is possible to implement user-defined key types. These are useful for indexing complex data types that are not understood as primitive types; for example a set of fields that are represented as a UINT64.
schema | The schema handle. |
name | The attribute name. |
idx_type | The index type name. This parameter cannot be null. |
key_type | The key type name. It may be null, in which case, the default key type for the attribute will be used. |
... | Some index types have additional parameters, for example, the BXTREE has an order parameter that specifies the number of entries in each BXTREE node. |
0 | The index was succesfully added. |
ENOENT | The specified attribute does not exist. |
EINVAL | One or more parameters was invalid. |
const char * sos_schema_name | ( | sos_schema_t | schema | ) |
Returns the schema's name.
schema | The schema handle. |
sos_schema_t sos_schema_new | ( | const char * | name | ) |
Create a schema.
A schema defines a SOS object. Every object in a SOS database is associated with a schema via an internal schema_id.
After a schema is created it must be associated with one or more containers. See the sos_schema_add() function to add a schema to a container so that objects of that type can subsequently be created in the container. Once a schema has been added, it can be looked up with the sos_schema_by_name() and sos_schema_by_id() functions.
Objects are created with the sos_obj_new() function. This function takes a schema-handle as it's argument. The schema-id is saved internally with the object data. An object is therefore self-describing.
name | The name of the schema. This name must be unique within the container. |
sos_schema_t sos_schema_next | ( | sos_schema_t | schema | ) |
Return a handle to the next schema in the container.
schema | The schema handle returned by sos_schema_first() or sos_schema_next() |
The | schema pointer |
NULL | If there are no more schema defined in the container |
void sos_schema_print | ( | sos_schema_t | schema, |
FILE * | fp | ||
) |
Print the schema to a File pointer.
This convenience function formats the schema definition in YAML and writes it to the specified FILE pointer. For example:
sos_schema_t schema = sos_container_find(sos, "Sample"); sos_schema_print(schema, stdout);
schema | The schema handle |
fp | The output FILE pointer |
size_t sos_value_size | ( | sos_value_t | value | ) |
Get the size of an attribute value.
value | The value handle |
sos_type_t sos_value_type | ( | sos_value_t | v | ) |
Return the value's type.