FAM Library Functions

fam_library_init

int fam_library_init()

This function initiates the FAM library for operation.

fam_library_shutdown

void fam_library_shutdown()

This function shuts down the FAM library.

FAM Space Operation Functions

fam_space_req_new

fam_space_req* fam_space_req_new(const char* space)

This function allocates memory for a new FAM space request for the given space. FAM space requests are only used when carrying out FAM space-related operations: create, delete, and query keys.

fam_space_req_free

void fam_space_req_free(fam_space_req* request)

This function releases the memory allocated for a FAM space request.

fam_space_req_set_max_size

void fam_space_req_set_max_size(fam_space_req* request,
                                size_t max_size)

This function specifies the maximum size of the FAM space in kilobytes. The default is 1024 KB.

fam_space_req_set_parity_scheme

void fam_space_req_set_parity_scheme(fam_space_req* request,
                                     fam_parity_t parity_scheme)

This function sets the parity scheme for the FAM space.

fam_space_req_set_request_timeout

void fam_space_req_set_request_timeout(fam_space_req* request,
                                       size_t timeout)

This function specifies the maximum time in milliseconds the client is willing to wait for the FAM operation to complete. The default timeout is 60 sec (if 0 is passed for the timeout).

fam_space_req_set_max_retries

void fam_space_req_set_max_retries(fam_space_req* request,
                                   size_t retry_count)

This function sets the maximum number of times the FAM space request attempts to retry. The default number of retries is 5.

fam_space_req_space_name

const char* fam_space_req_space_name(fam_space_req* request)

This function returns the name of the FAM space associated with this FAM space request object.

fam_space_req_max_size

size_t fam_space_req_max_size(fam_space_req* request)

This function returns the maximum size specified for the FAM space on this FAM space request object.

fam_space_req_parity_scheme

fam_parity_t fam_space_req_parity_scheme(fam_space_req* request)

This function returns the parity scheme specified for the FAM space on this FAM space request object.

fam_space_req_request_timeout

size_t fam_space_req_request_timeout(fam_space_req* request)

This function returns the amount of time in milliseconds the FAM space request object waits for a request to the FAM to complete.

fam_space_req_max_retries

size_t fam_space_req_max_retries(fam_space_req* request)

This function returns the maximum number of times the FAM space request attempts to retry.

fam_space_req_result_code

int fam_space_req_result_code(fam_space_req* request)

This function returns the message code returned by the FAM space request. Use this function to retrieve more information from a failed space request.

fam_space_req_result_message

const char* fam_space_req_result_message(fam_space_req* request)

This function returns the text message associated with the error code. Use this function to retrieve more information from a failed FAM space request.

fam_space_create

int fam_space_create(fam_space_req* request)

This function creates a FAM space in the fabric using the settings specified in the FAM space request object.

fam_space_delete

int fam_space_delete(fam_space_req* request)

This function removes the FAM space from the fabric.

fam_space_exists

int fam_space_exists(fam_space_req* request)

This function verifies the FAM space exists in the fabric.

fam_space_query_keys_under_session

fab_array* fam_space_query_keys_under_session(fam_space_req* request,
                                              fam_session* session)

This function returns an array of strings that represents all keys that exist in the FAM space under the current session.

FAM Session Operation Functions

fam_session_new

fam_session* fam_session_new(const char* lock_id,
                             const char* session_version)

This is an advanced feature. This function creates a FAM session object with the specified version tag. Use it when you need to create a session outside the task.

fam_session_free

void fam_session_free(fam_session* session)

This session releases the memory associated with a FAM session.

fam_session_lock_id

const char* fam_session_lock_id(fam_session* session)

This function returns the id of the FAM session.

fam_session_version

const char* fam_session_version(fam_session* session)

This function returns the version tag of the FAM session object.

fam_session_lease_timeout

size_t fam_session_lease_timeout(fam_session* session)

This function returns the maximum amount of time in milliseconds that a session will exist before an automatic rollback occurs. For example, if a FAM operation is in flight, and a network outage occurrs, the FAM session will be automatically rolled back after the timeout, because a commit did not occur.

fam_session_set_lease_timeout

void fam_session_set_lease_timeout(fam_session* session,
                                   size_t lease_timeout)

This function sets the maximum amount of time in milliseconds that a session will exist before an automatic rollback occurs. For example, if a FAM operation is in flight, and a network outage occurrs, the FAM session will be automatically rolled back after the timeout, because a commit did not occur.

fam_session_space_count

int fam_session_space_count(fam_session* session)

This function returns the number of spaces accessed during the session.

fam_session_result_code

int fam_session_result_code(fam_session* session)

This function returns the message code from the session. Use this function to retrieve more information about a session error.

fam_session_result_message

const char* fam_session_result_message(fam_session* session)

This function returns the text message associated with the error code. Use this function to retrieve more about a session error.

fam_commit

int fam_commit(fam_session* session)

This function commits the data manipulations performed in the specified session.

fam_rollback

int fam_rollback(fam_session* session)

This function rolls back the data manipulations performed in the specified session and returns the data to the last commit.
Note. The FAM does not keep past versions of the data. When data is locked, a copy is created. Once data has been committed, by sending the commit function or by the successful completion of a task, that copy is deleted. You can not go back to a previous version of data whose changes have been committed.

fam_session_invalidate

int fam_session_invalidate(fam_session* session)

This is an advanced feature. This function invalidates the specified session and executes a data rollback which does not release the lock.

fam_commit_prep

int fam_commit_prep(fam_session* session)

This function is not required to commit your data. It is the first phase of a two-phase commit protocol and serves as a useful mechanism for minimizing the chance of commit failure.

FAM Data Operation Functions

fam_req_new

fam_req* fam_req_new(const char* space,
                     const char* key,
                     fam_session* session)

This function creates a new FAM request object. FAM request objects are used when carrying out FAM data-related operations: get, read, write, erase, push, pop, and unpop

fam_req_free

void fam_req_free(fam_req* request)

This function releases the memory associated with the FAM request object.

fam_req_set_request_timeout

void fam_req_set_request_timeout(fam_req* request,
                                 size_t timeout)

This function specifies the amount of time in milliseconds the FAM request object waits for a request to the FAM to complete.

fam_req_request_timeout

size_t fam_req_request_timeout(fam_req* request)

This function returns the amount of time in milliseconds the FAM request object waits for a request to the FAM to complete.

fam_req_set_max_retries

void fam_req_set_max_retries(fam_req* request,
                             size_t retry_count)

This function sets the maximum number of times the FAM request attempts to retry.

fam_req_max_retries

size_t fam_req_max_retries(fam_req* request)

This function returns the maximum number of times the FAM request attempts to retry.

fam_req_result_code

int fam_req_result_code(fam_req* request)

This function returns the message code from the session. Use this function to retrieve more information from a failed FAM request.

fam_req_result_message

const char* fam_req_result_message(fam_req* request)

This function returns the text message associated with the error code. Use this function to retrieve more information from a failed FAM request.

fam_get

fab_value* fam_get(fam_req* request)

This function reserves a lock on the FAM data associated with the specified key and returns the data. Note: all other operations destined for this key outside current session will block until the lock gets released by calling fam_commit or fam_rollback.

fam_read

fab_value* fam_read(fam_req* request)

This function returns the FAM data associated with the specified key without placing a lock on it.

fam_write

int fam_write(fam_req* request,
              fab_value* value)

This function writes the data for the specified key to the FAM space. The space size utilized by the FAM will only change upon calling fam_commit or fam_rollback. Note: This operation will release the lock on the data if you attempt to exceed the FAM space capacity.

fam_erase

int fam_erase(fam_req* request)

This function deletes FAM data associated with the specified key. Note: the space size utilized by the FAM will only change upon calling fam_commit or fam_rollback.

fam_queue_push

int fam_queue_push(fam_req* request,
                   fab_value* value)

This function adds data to the end of the specified FAM queue. Note: the space size utilized by the FAM will only change upon calling fam_commit or fam_rollback.

fam_queue_pop

fab_value* fam_queue_pop(fam_req* request)

This function returns data from the front of a FAM queue, removes the data from the queue, and places a lock on the queue.

fam_queue_unpop

int fam_queue_unpop(fam_req* request)

This function adds the data that was removed in the previous pop function to the front of a FAM queue and removes the lock.