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

Functions

int sos_container_new (const char *path, int o_mode)
 Create a Container. More...
 
int sos_container_delete (sos_t c)
 Delete storage associated with a Container. More...
 
int sos_container_commit (sos_t sos, sos_commit_t flags)
 Flush outstanding changes to persistent storage. More...
 
void sos_index_info (sos_index_t index, FILE *fp)
 
int print_schema (struct rbn *n, void *fp_, int level)
 
void sos_container_info (sos_t sos, FILE *fp)
 Print container information. More...
 
int sos_container_lock_info (const char *path, FILE *fp)
 Print container lock information. More...
 
int sos_container_lock_cleanup (const char *path)
 Release locks held by dead processes. More...
 
void sos_inuse_obj_info (sos_t sos, FILE *outp)
 
void sos_free_obj_info (sos_t sos, FILE *outp)
 
sos_t sos_container_open (const char *path_arg, sos_perm_t o_perm)
 Open a Container. More...
 
int sos_container_move (const char *path_arg, const char *new_path)
 Move a container. More...
 
int sos_container_stat (sos_t sos, struct stat *sb)
 Return information about a container. More...
 
void sos_container_close (sos_t sos, sos_commit_t flags)
 Close a Container. More...
 
sos_obj_t sos_obj_new (sos_schema_t schema)
 Allocate an object from the SOS object store. More...
 
int sos_obj_copy (sos_obj_t dst_obj, sos_obj_t src_obj)
 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...
 
sos_schema_t sos_obj_schema (sos_obj_t obj)
 Returns an Object's schema. 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_remove (sos_obj_t obj)
 Remove an object from the SOS. More...
 
int sos_obj_index (sos_obj_t obj)
 Add an object to it's indexes. 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...
 
char * sos_obj_attr_by_name_to_str (sos_obj_t sos_obj, const char *attr_name, char *str, size_t len)
 

Detailed Description

Function Documentation

void sos_container_close ( sos_t  sos,
sos_commit_t  flags 
)

Close a Container.

This function commits changes to stable storage and releases all in-memory resources associated with the container.

If SOS_COMMIT_SYNC is specified in the flags parameter, the function will wait until the changes are commited before returning.

Parameters
sosThe SOS container handle
flagsThe commit flags
int sos_container_commit ( sos_t  sos,
sos_commit_t  flags 
)

Flush outstanding changes to persistent storage.

This function commits the index changes to stable storage. If SOS_COMMIT_SYNC is specified in the flags parameter, the function will wait until the changes are commited to stable stroage before returning.

Parameters
sosThe SOS container handle
flagsThe commit flags
int sos_container_delete ( sos_t  c)

Delete storage associated with a Container.

Removes all resources associated with the Container. The sos_t handle must be provided (requiring an open) because it is necessary to know the associated Indices in order to be able to know the names of the associated files. sos_destroy() will also close sos, as the files should be closed before begin removed.

Parameters
cThe container handle
Return values
0The container was deleted
EPERMThe user has insufficient privilege
EINUSEThe container is in-use by other clients
void sos_container_info ( sos_t  sos,
FILE *  fp 
)

Print container information.

Prints information about the container to the specified FILE pointer.

Parameters
sosThe container handle
fpThe FILE pointer
int sos_container_lock_cleanup ( const char *  path)

Release locks held by dead processes.

It is possible for a process to die while holding container locks. This renders the container inaccessible. This function will release locks held by dead processes.

Parameters
sosThe container handle
int sos_container_lock_info ( const char *  path,
FILE *  fp 
)

Print container lock information.

Prints information about the locks held on the container to a FILE pointer.

Parameters
sosThe container handle
fpThe FILE pointer
int sos_container_move ( const char *  path_arg,
const char *  new_path 
)

Move a container.

Changes the path data that the container keeps internally for partitions.

Parameters
pathPathname to the Container. See sos_container_new()
new_pathPathname where the containter was copied.
int sos_container_new ( const char *  path,
int  o_mode 
)

Create a Container.

Creates a SOS container. The o_flags and o_mode parameters accept the same values and have the same meaning as the corresponding parameters to the open() system call.

Containers are logically maintained in a Unix filesystem namespace. The specified path must be unique for the Container and all sub-directories in the path up to, but not including the basename() must exist.

Parameters
pathPathname for the Container.
o_modeThe file mode for the Container.
Return values
0The container was successfully created.
EINVALA parameter was invalid
EPERMThe user has insufficient permission
EEXISTA container already exists at the specified path
sos_t sos_container_open ( const char *  path_arg,
sos_perm_t  o_perm 
)

Open a Container.

Open a SOS container. If successfull, the c parameter will contain a valid sos_t handle on exit.

Parameters
pathPathname for the Container. See sos_container_new()
o_permThe requested read/write permissions
Return values
!NULLThe sos_t handle for the container.
NULLAn error occured, consult errno for the reason.
int sos_container_stat ( sos_t  sos,
struct stat *  sb 
)

Return information about a container.

Fills a Unix struct stat buffer with information about a container's meta data.

Parameters
sosThe container handle
sbThe struct stat buffer
Return values
0Success
!0A Unix error code
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.

Parameters
sos_objThe object handle
attr_nameThe attribute name
attr_valueThe attribute value as a string
endptrReceives the point in the str argumeent where parsing stopped. This parameter may be NULL.
Return values
0Success
EINVALThe string format was invalid for the attribute type
ENOSYSThere is no string formatter for this attribute type
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_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.