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

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)
 

Detailed Description

Macro Definition Documentation

#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.

Function Documentation

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.

Parameters
objThe object handle
attrThe attribute handle
arr_objPointer 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.

Parameters
objThe object handle
attrThe attribute handle
strThe input string value to parse
endptrReceives the point in the str argumeent where parsing stopped. This parameter may be NULL.
Return values
0The string was successfully parsed and the value set
EINVALThe 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.

Parameters
objThe object handle
attrThe attribute handle
strPointer to the string to receive the formatted value
lenThe size of the string in bytes.
Returns
A pointer to the str argument or NULL if there was a formatting error.
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.

Parameters
dst_objThe object to copy to
src_objThe object to copy from
Return values
0The object data was sucessfully copied
EINVALThe source and destination object attributes object attributes don't match
ENOMEMThere 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.

Parameters
objPointer 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.

Parameters
sosThe container handle
ref_valA value handle to an attribute of type SOS_TYPE_OBJ
Return values
Theobject to which the reference refers.
NULLThe 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;
Parameters
objThe SOS object handle
Return values
Theobject 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.

Parameters
objHandle for the object to add
Return values
0Success
-1An 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.

Parameters
schemaThe schema handle
Returns
Pointer to the new object
NULL if there is an error
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.

Parameters
obj
Return values
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.

Parameters
objThe 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.

Parameters
objHandle for the object to remove
Returns
0 on success.
Error code on error.
sos_schema_t sos_obj_schema ( sos_obj_t  obj)

Returns an Object's schema.

Parameters
objThe object handle
Return values
Theschema 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.

Parameters
sosThe container handle
refThe object reference
Return values
Theobject to which the reference refers.
NULLThe 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.

Parameters
objThe object handle
attrThe attribute handle
Returns
The value of the object's attribute.
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.

Parameters
valuePointer to the value to be initialized
objThe SOS object handle
attr_idThe Id for the attribute.
Return values
Pointerto the sos_value_t handle
NULLif 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.

Parameters
valuePointer to the value to be initialized
schemaThe schema handle
objThe object handle
nameThe attribute name
attr_idA pointer to the attribute id
Return values
Pointerto the sos_value_t handle
NULLif 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

Parameters
aThe lhs
bThe rhs
Returns
The result as described above
int sos_value_from_str ( sos_value_t  v,
const char *  str,
char **  endptr 
)

Set the value from a string.

Parameters
vThe value handle
strThe input string value to parse
endptrReceives the point in the str argumeent where parsing stopped. This parameter may be NULL.
Return values
0The string was successfully parsed and the value set
EINVALThe 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.

Parameters
valPointer to the value to be initialized
objThe object handle
attrThe attribute handle
Return values
Thevalue 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.

Parameters
valThe value handle
bufThe buffer containing the data
buflenThe number of bytes to write from the buffer
Return values
Thenumber of bytes written
void sos_value_put ( sos_value_t  value)

Drop a reference on a value object.

Parameters
valueThe value handle.
size_t sos_value_size ( sos_value_t  value)

Get the size of an attribute value.

Parameters
valueThe value handle
Returns
The size of the attribute value in bytes
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'.

Parameters
vThe value handle
Returns
The size of the string in bytes.
const char* sos_value_to_str ( sos_value_t  v,
char *  str,
size_t  len 
)

Format a value as a string.

Parameters
vThe value handle
strPointer to the string to receive the formatted value
lenThe size of the string in bytes.
Returns
A pointer to the str argument or NULL if there was a formatting error.
sos_type_t sos_value_type ( sos_value_t  v)

Return the value's type.

Returns
The type