This section provides an overview of the 5800 system C client API. The following topics are discussed:
The 5800 system C API client supports two different access patterns: a synchronous “EZ” access very similar to the current Java implementation, and a more flexible, nonblocking access based on the POSIX model.
For this release, the nonblocking C API client is not implemented.
The C client library interacts with the 5800 system server entirely through an HTTP protocol.
Calls to the C API should be wrapped with retry logic so that their applications are resilient to transient failures that may be experienced when a node or switch fails while servicing an operation.
Both the synchronous and the nonsynchronous C APIs are fully thread-safe and can be used simultaneously in multiple threads from the same process. Each thread must call hc_session_create_ez to create its own session. Sessions must not be shared between threads.
Name resolution must be done in a single thread with the subsequent IP address passed to hc_session_create_ez, otherwise core dumps will occur if multiple name resolution threads call getaddrinfo at the same time.
The 5800 system C client library provides high performance and is highly scalable.
The synchronous C API performs its own calls to select() internally.
For the nonblocking C API (not yet implemented), access is provided to the underlying fd_set so that all pending I/O operations can be serviced by a single thread on the basis of status returned by the POSIX select() function, possibly after merging the 5800 system fd_set with some external, application-specific fd_set.
The 5800 system C client library generally follows the model of populating externally allocated data structures such as handles, buffers, and result arrays.
Some internal data structures are generated during XML document construction. These data structures are allocated and freed using the function pointers supplied to hc_init when initializing the library (see Initializing a Global Session).
Other data structures are allocated and returned to the user; these have corresponding functions to free them. For example, hc_session_create_ez and hc_session_free.
The C client library does not automatically refresh its in-memory schema definitions. If the schema is changed through the command-line interface (CLI), a new session must be created with a new call to hc_session_create_ez to access the schema changes.
A global session must be explicitly initialized with a call to hc_init and released with a call to hc_cleanup. Memory allocators and deallocators are supplied in the initialization function to control how memory allocation occurs. You will normally supply the standard malloc, free, and realloc functions for this functionality.
The heap memory allocator is defined as follows:
typedef void* (*allocator_t) (size_t size);
The heap memory deallocator is defined as follows:
typedef void (*deallocator_t) (void *p);
The heap memory reallocator is defined as follows:
typedef void (*reallocator_t) (void *p,size_t size);
The following function initializes a global session:
hcerr_t hc_init(allocator_t, deallocator_t, reallocator_t);
This function must be called once per process to initialize the memory functions used in the 5800 system C API. It also initializes global session properties.
A global session is initialized once per process, regardless of how many threads in that process are using the C API.
hc_init should be called once per process before any thread calls hc_session_create_ez. If hc_session_create_ez is called before hc_init, an implicit call is made to hc_init from that thread. But that call to hc_init is not interlocked with other threads, and it uses the C API shared library’s version of malloc and free, which might be different than the application’s version of malloc and free. It is strongly recommended that all applications call hc_init once per process with their own allocator and deallocator.
For more information on hc_session_create_ez , see hc_session_create_ez.
The following function terminates a global session:
void hc_cleanup();
All 5800 system store operations return a system record, which encapsulates information about the stored object. In particular, the system record contains the OID, which can be used to retrieve the stored object data or metadata.
typedef struct hc_system_record_ { char is_indexed; hc_oid oid; hc_digest_algo digest_algo; hc_digest data_digest; hc_long_t size; hc_long_t creation_time; hc_long_t deleted_time; char shredMode; } hc_system_record_t;
About the fields:
oid — The objectid for this object, equivalent to the system.object_id field.
digest_algo — Always set to "sha1" for this release. Equivalent to the system.object_hash_alg field.
data_digest — An array of bytes that represent the content digest of this object's data. Equivalent to the system.object_hash field.
size — The size of the data in this object, in bytes. Equivalent to the system.object_size field.
creation_time — The object creation time, expressed as number of milliseconds since the epoch. Equivalent to the system.object_ctime field.
deleted_time — The deletion time of this record, if any, as the number of milliseconds since the epoch.
shredMode — Not used in this release.
is_indexed — indicates, after a store_data or store_metadata operation, whether the metadata for the object was successfully inserted into the query engine, and the object is hence available for query. 0 if false, 1 if true.
Every function in the 5800 system C client library returns a result code of type hcerr_t. Any value other than HCERR_OK indicates a nonrecoverable error. See the hc.h file for specific error codes.