SOS: Scalable Object Store
4.0.0
|
Macros | |
#define | SOS_OBJ_BE 1 |
#define | SOS_OBJ_LE 2 |
#define | SOS_VALUE(_name_) struct sos_value_s _name_ ## __, *_name_ = &_name_ ## __; |
Functions | |
sos_obj_t | sos_obj_new (sos_schema_t schema) |
Allocate an object from the SOS object store. More... | |
sos_schema_t | sos_obj_schema (sos_obj_t obj) |
Returns an Object's schema. More... | |
int | sos_obj_copy (sos_obj_t dst, sos_obj_t src) |
Copy the data in one object to another. More... | |
sos_obj_ref_t | sos_obj_ref (sos_obj_t obj) |
sos_obj_t | sos_ref_as_obj (sos_t sos, sos_obj_ref_t ref) |
Return the object associated with the reference. More... | |
sos_obj_t | sos_obj_from_value (sos_t sos, sos_value_t ref_val) |
Return the object associated with the value. More... | |
void | sos_obj_delete (sos_obj_t obj) |
Release the storage consumed by the object in the SOS object store. More... | |
sos_obj_t | sos_obj_get (sos_obj_t obj) |
Take a reference on an object. More... | |
void | sos_obj_put (sos_obj_t obj) |
Drop a reference on an object. More... | |
int | sos_obj_index (sos_obj_t obj) |
Add an object to it's indexes. More... | |
int | sos_obj_remove (sos_obj_t obj) |
Remove an object from the SOS. More... | |
sos_value_t | sos_value_by_name (sos_value_t value, sos_schema_t schema, sos_obj_t obj, const char *name, int *attr_id) |
Initialize a value with an object's attribute data. More... | |
sos_value_t | sos_value_by_id (sos_value_t value, sos_obj_t obj, int attr_id) |
Initialize a value with an object's attribute data. More... | |
sos_obj_t | sos_array_obj_new (sos_t sos, sos_type_t type, size_t count) |
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. | |
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_value_t | sos_value_new () |
void | sos_value_free (sos_value_t v) |
void * | sos_obj_ptr (sos_obj_t obj) |
Return a pointer to the object's data. More... | |
sos_value_t | sos_value_init (sos_value_t value, sos_obj_t obj, sos_attr_t attr) |
Initialize a value with an object's attribute data. More... | |
sos_value_t | sos_value_copy (sos_value_t dst, sos_value_t src) |
sos_value_t | sos_value (sos_obj_t obj, sos_attr_t attr) |
Return a value for the specified object's attribute. More... | |
void | sos_value_put (sos_value_t value) |
Drop a reference on a value object. More... | |
sos_value_data_t | sos_obj_attr_data (sos_obj_t obj, sos_attr_t attr, sos_obj_t *arr_obj) |
Returns a pointer into the memory of an object. More... | |
int | sos_value_cmp (sos_value_t a, sos_value_t b) |
Compare two value. More... | |
int | sos_value_is_array (sos_value_t value) |
Return !0 if the value is an array. | |
sos_type_t | sos_value_type (sos_value_t value) |
Return the value's type. More... | |
size_t | sos_value_size (sos_value_t value) |
Get the size of an attribute value. More... | |
size_t | sos_value_memcpy (sos_value_t value, void *buf, size_t buflen) |
Set an object value from a buffer. More... | |
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... | |
size_t | sos_value_strlen (sos_value_t v) |
Return the length of the string required for the value. More... | |
const char * | sos_value_to_str (sos_value_t value, char *str, size_t len) |
Format a value as a string. More... | |
int | sos_value_from_str (sos_value_t value, const char *str, char **endptr) |
Set the value from a string. More... | |
char * | sos_obj_attr_by_name_to_str (sos_obj_t sos_obj, const char *attr_name, char *str, size_t len) |
#define SOS_OBJ_BE 1 |
An object is a persistent instance of attribute values described by a schema. While a schema is a collection of attributes, an object is a collection of values. Each value in the object is described by an attribute in the schema. The attribute identifies the type of each value in the object.
sos_value_data_t sos_obj_attr_data | ( | sos_obj_t | obj, |
sos_attr_t | attr, | ||
sos_obj_t * | arr_obj | ||
) |
Returns a pointer into the memory of an object.
This function returns a pointer directly into the memory of an object. The attr parameter specifies which attribute in the object is to be accessed.
If the attribute is an array, the array object to which the attribute refers is returned in the arr_obj parameter if provided. This is because the memory pointed to by the return value has a reference on the array object and the caller is responsible for releasing that reference when the memory is no longer in use.
If the arr_obj pointer is NULL and the attr parameter is an array, this function will assert.
obj | The object handle |
attr | The attribute handle |
arr_obj | Pointer to a sos_obj_t handle. |
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. |
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. |
int sos_obj_copy | ( | sos_obj_t | dst_obj, |
sos_obj_t | src_obj | ||
) |
Copy the data in one object to another.
Copy all of the data from the object specified by src_obj
to the object specified by dst_obj
. The objects do not need to be in the same container. If src_obj
contains array attributes, an array of the required size is allocated in the destination object and the data copied.
The objects do not need to have the same schema, however, the type of the attributes in src_obj
must match the types of the attributes in the same order in dst_obj
.
dst_obj | The object to copy to |
src_obj | The object to copy from |
0 | The object data was sucessfully copied |
EINVAL | The source and destination object attributes object attributes don't match |
ENOMEM | There were insufficient resources to assign the object |
void sos_obj_delete | ( | sos_obj_t | obj | ) |
Release the storage consumed by the object in the SOS object store.
Deletes the object and any arrays to which the object refers. It does not delete an object that is referred to by this object, i.e. SOS_TYPE_OBJ_REF attribute values.
This function does not drop any references on the memory resources for this object. Object references must still be dropped with the sos_obj_put() function.
obj | Pointer to the object |
sos_obj_t sos_obj_from_value | ( | sos_t | sos, |
sos_value_t | ref_val | ||
) |
Return the object associated with the value.
This function will return a sos_obj_t for the object that is referred to by ref_val. Use the function sos_ref_as_obj() to obtain an object from a raw sos_obj_ref_t
value.
sos | The container handle |
ref_val | A value handle to an attribute of type SOS_TYPE_OBJ |
The | object to which the reference refers. |
NULL | The reference did not point to a well formed object, or the schema in the object header was not part of the container. |
sos_obj_t sos_obj_get | ( | sos_obj_t | obj | ) |
Take a reference on an object.
SOS objects are reference counted. This function takes a reference on a SOS object and returns a pointer to the object. The typical calling sequence is:
sos_obj_t my_obj_ptr = sos_obj_get(obj);
This allows for the object to be safely pointed to from multiple places. The sos_obj_put() function is used to drop a reference on a SOS object. For example:
sos_obj_put(my_obj_ptr); my_obj_ptr = NULL;
obj | The SOS object handle |
The | object handle |
int sos_obj_index | ( | sos_obj_t | obj | ) |
Add an object to it's indexes.
Add an object to all the indices defined in it's schema. This function should only be called after all attributes that have indexes have had their values set.
obj | Handle for the object to add |
0 | Success |
-1 | An error occurred. Refer to errno for detail. |
sos_obj_t sos_obj_new | ( | sos_schema_t | schema | ) |
Allocate an object from the SOS object store.
This call will automatically extend the size of the backing store to accomodate the new object. This call will fail if there is insufficient disk space. Use the sos_obj_index() to add the object to all indices defined by it's object class.
See the sos_schema_by_name() function call for information on how to obtain a schema handle.
schema | The schema handle |
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 |
void sos_obj_put | ( | sos_obj_t | obj | ) |
Drop a reference on an object.
SOS objects are reference counted. The memory consumed by the object is not released until all references have been dropped. This refers only to references in main memory. The object will continue to exist in persistent storage. See the sos_obj_delete() function for information on removing an object from persistent storage.
obj | The object handle. If NULL, this function is a no-op. |
int sos_obj_remove | ( | sos_obj_t | obj | ) |
Remove an object from the SOS.
This removes an object from all indexes of which it is a member. The object itself is not destroyed. Use the sos_obj_delete() function to release the storage consumed by the object itself.
obj | Handle for the object to remove |
sos_schema_t sos_obj_schema | ( | sos_obj_t | obj | ) |
Returns an Object's schema.
obj | The object handle |
The | schema used to create the object. |
sos_obj_t sos_ref_as_obj | ( | sos_t | sos, |
sos_obj_ref_t | ref | ||
) |
Return the object associated with the reference.
This function will return a sos_obj_t for the object that is referred to by 'ref'. Use the function sos_obj_from_value() to obtain an object from a sos_value_t value.
sos | The container handle |
ref | The object reference |
The | object to which the reference refers. |
NULL | The reference did not point to a well formed object, or the schema in the object header was not part of the container. |
sos_value_t sos_value | ( | sos_obj_t | obj, |
sos_attr_t | attr | ||
) |
Return a value for the specified object's attribute.
This function returns a sos_value_t for an object's attribute. The reference on this value should be dropped with sos_value_put() when the application is finished with the value.
obj | The object handle |
attr | The attribute handle |
sos_value_t sos_value_by_id | ( | sos_value_t | value, |
sos_obj_t | obj, | ||
int | attr_id | ||
) |
Initialize a value with an object's attribute data.
Returns the sos_value_t for the attribute with the specified id.
value | Pointer to the value to be initialized |
obj | The SOS object handle |
attr_id | The Id for the attribute. |
Pointer | to the sos_value_t handle |
NULL | if the specified attribute does not exist. |
sos_value_t sos_value_by_name | ( | sos_value_t | value, |
sos_schema_t | schema, | ||
sos_obj_t | obj, | ||
const char * | name, | ||
int * | attr_id | ||
) |
Initialize a value with an object's attribute data.
Returns an object value handle for the specified attribute name. If the attr_id
parameter is non-null, the parameter is filled in with associated attribute id.
value | Pointer to the value to be initialized |
schema | The schema handle |
obj | The object handle |
name | The attribute name |
attr_id | A pointer to the attribute id |
Pointer | to the sos_value_t handle |
NULL | if the specified attribute does not exist. |
int sos_value_cmp | ( | sos_value_t | a, |
sos_value_t | b | ||
) |
Compare two value.
Compares a
and b
and returns <0 if a < b, 0 if a == b, and >0 if a > b
a | The lhs |
b | The rhs |
int sos_value_from_str | ( | sos_value_t | v, |
const char * | str, | ||
char ** | endptr | ||
) |
Set the value from a string.
v | The value 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. |
sos_value_t sos_value_init | ( | sos_value_t | val, |
sos_obj_t | obj, | ||
sos_attr_t | attr | ||
) |
Initialize a value with an object's attribute data.
The returned value has a reference on the parameter object obj
. The caller must call sos_value_put() when the value is no longer in use.
val | Pointer to the value to be initialized |
obj | The object handle |
attr | The attribute handle |
The | value handle |
size_t sos_value_memcpy | ( | sos_value_t | val, |
void * | buf, | ||
size_t | buflen | ||
) |
Set an object value from a buffer.
Set the value from an untyped void buffer. If the buflen is too large to fit, only sos_value_size() bytes will be written.
val | The value handle |
buf | The buffer containing the data |
buflen | The number of bytes to write from the buffer |
The | number of bytes written |
void sos_value_put | ( | sos_value_t | value | ) |
Drop a reference on a value object.
value | The value handle. |
size_t sos_value_size | ( | sos_value_t | value | ) |
Get the size of an attribute value.
value | The value handle |
size_t sos_value_strlen | ( | sos_value_t | v | ) |
Return the length of the string required for the value.
This function returns the size of the string required to hold the attribute value if formatted as a string. This function is useful when allocating buffers used with the sos_obj_attr_to_str() function. The returned value does not include the byte required to contain the terminating '\0'.
v | The value handle |
const char* sos_value_to_str | ( | sos_value_t | v, |
char * | str, | ||
size_t | len | ||
) |
Format a value as a string.
v | The value handle |
str | Pointer to the string to receive the formatted value |
len | The size of the string in bytes. |
sos_type_t sos_value_type | ( | sos_value_t | v | ) |
Return the value's type.