kinetic-c  v0.12.0
Seagate Kinetic Protocol Client Library for C
Enumerations | Functions | Variables
kinetic_client.c File Reference
#include "kinetic_types_internal.h"
#include "kinetic_version_info.h"
#include "kinetic_client.h"
#include "kinetic_allocator.h"
#include "kinetic_session.h"
#include "kinetic_controller.h"
#include "kinetic_operation.h"
#include "kinetic_builder.h"
#include "kinetic_logger.h"
#include "kinetic_response.h"
#include "kinetic_bus.h"
#include "kinetic_memory.h"
#include <stdlib.h>
#include <sys/time.h>

Go to the source code of this file.

Enumerations

enum  GET_COMMAND
 

Functions

KineticVersionInfo KineticClient_Version (void)
 Gets current version info of kinetic-c library. More...
 
KineticClient * KineticClient_Init (KineticClientConfig *config)
 Initializes the Kinetic API and configures logging. More...
 
void KineticClient_Shutdown (KineticClient *const client)
 Performs shutdown/cleanup of the kinetic-c client library. More...
 
KineticStatus KineticClient_CreateSession (KineticSessionConfig *const config, KineticClient *const client, KineticSession **session)
 Creates a session with the Kinetic Device per specified configuration. More...
 
KineticStatus KineticClient_DestroySession (KineticSession *const session)
 Closes the connection to a host. More...
 
KineticStatus KineticClient_GetTerminationStatus (KineticSession *const session)
 Returns the reason reported in the case of the Kinetic device terminating a session in the case of a catastrophic error occurring. More...
 
KineticStatus KineticClient_NoOp (KineticSession *const session)
 Executes a NOOP operation to test whether the Kinetic Device is operational. More...
 
KineticStatus KineticClient_Put (KineticSession *const session, KineticEntry *const entry, KineticCompletionClosure *closure)
 Executes a PUT operation to store/update an entry on the Kinetic Device. More...
 
KineticStatus KineticClient_Flush (KineticSession *const session, KineticCompletionClosure *closure)
 Executes a FLUSHALLDATA operation to flush pending PUTs or DELETEs. More...
 
static bool has_key (KineticEntry *const entry)
 
static bool has_value_buffer (KineticEntry *const entry)
 
static KineticStatus handle_get_command (GET_COMMAND cmd, KineticSession *const session, KineticEntry *const entry, KineticCompletionClosure *closure)
 
KineticStatus KineticClient_Get (KineticSession *const session, KineticEntry *const entry, KineticCompletionClosure *closure)
 Executes a GET operation to retrieve an entry from the Kinetic Device. More...
 
KineticStatus KineticClient_GetPrevious (KineticSession *const session, KineticEntry *const entry, KineticCompletionClosure *closure)
 Executes a GETPREVIOUS operation to retrieve the next entry from the Kinetic Device. More...
 
KineticStatus KineticClient_GetNext (KineticSession *const session, KineticEntry *const entry, KineticCompletionClosure *closure)
 Executes a GETNEXT operation to retrieve the next entry from the Kinetic Device. More...
 
KineticStatus KineticClient_Delete (KineticSession *const session, KineticEntry *const entry, KineticCompletionClosure *closure)
 Executes a DELETE operation to delete an entry from the Kinetic Device. More...
 
KineticStatus KineticClient_GetKeyRange (KineticSession *const session, KineticKeyRange *range, ByteBufferArray *keys, KineticCompletionClosure *closure)
 Executes a GETKEYRANGE operation to retrieve a set of keys in the range specified range from the Kinetic Device. More...
 
KineticStatus KineticClient_P2POperation (KineticSession *const session, KineticP2P_Operation *const p2pOp, KineticCompletionClosure *closure)
 Executes a PEER2PEERPUSH operation allows a client to instruct a Kinetic Device to copy a set of keys (and associated value and metadata) to another Kinetic Device. More...
 

Variables

static const KineticVersionInfo VersionInfo
 

Enumeration Type Documentation

Enumerator
CMD_GET 
CMD_GET_NEXT 
CMD_GET_PREVIOUS 

Definition at line 209 of file kinetic_client.c.

Function Documentation

KineticVersionInfo KineticClient_Version ( void  )

Gets current version info of kinetic-c library.

Returns
Returns a pointer to static version info

Definition at line 42 of file kinetic_client.c.

References VersionInfo.

KineticClient* KineticClient_Init ( KineticClientConfig config)

Initializes the Kinetic API and configures logging.

Parameters
configA configuration struct.
Returns
Returns a pointer to a KineticClient. You need to pass this pointer to KineticClient_CreateSession() to create new connections. Once you are finished will the KineticClient, and there are no active connections. The pointer should be release with KineticClient_Shutdown()

Definition at line 47 of file kinetic_client.c.

References KINETIC_CLIENT_DEFAULT_MAX_THREADPOOL_THREADS, KINETIC_CLIENT_DEFAULT_READER_THREADS, KineticBus_Init(), KineticCalloc(), KineticFree(), KineticLogger_Init(), KineticClientConfig::logFile, KineticClientConfig::logLevel, KineticClientConfig::maxThreadpoolThreads, and KineticClientConfig::readerThreads.

void KineticClient_Shutdown ( KineticClient *const  client)

Performs shutdown/cleanup of the kinetic-c client library.

Parameters
clientThe pointer returned from KineticClient_Init

Definition at line 69 of file kinetic_client.c.

References KineticBus_Shutdown(), KineticFree(), and KineticLogger_Close().

KineticStatus KineticClient_CreateSession ( KineticSessionConfig *const  config,
KineticClient *const  client,
KineticSession **  session 
)

Creates a session with the Kinetic Device per specified configuration.

Parameters
configKineticSessionConfig structure which must be configured by the client prior to creating the device connection. .host Host name or IP address to connect to .port Port to establish socket connection on .clusterVersion Cluster version to use for the session .identity Identity to use for the session .hmacKey Key to use for HMAC calculations (NULL-terminated string) .pin PIN to use for PIN-based operations
clientThe KineticClient pointer returned from KineticClient_Init()
sessionPointer to a KineticSession pointer that will be populated with the allocated/created session upon success.
Returns
Returns the resulting KineticStatus, and session will be populated with a pointer to the session instance upon success. The client should call KineticClient_DestroySession() in order to shutdown a connection and cleanup resources when done using a KineticSession.

Definition at line 76 of file kinetic_client.c.

References ByteArray::data, KineticSessionConfig::hmacKey, KineticSessionConfig::host, KINETIC_STATUS_HMAC_REQUIRED, KINETIC_STATUS_HOST_EMPTY, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_SESSION_EMPTY, KINETIC_STATUS_SESSION_INVALID, KINETIC_STATUS_SUCCESS, KineticAllocator_FreeSession(), KineticAllocator_NewSession(), KineticSession_Connect(), KineticSession_Create(), ByteArray::len, LOG0, LOGF0, and KineticSessionConfig::port.

KineticStatus KineticClient_DestroySession ( KineticSession *const  session)

Closes the connection to a host.

Parameters
sessionThe connected KineticSession to close. The session instance will be freed by this call after closing the connection, so the pointer should not longer be used.
Returns
Returns the resulting KineticStatus.

Definition at line 126 of file kinetic_client.c.

References KINETIC_STATUS_SESSION_INVALID, KINETIC_STATUS_SUCCESS, KineticSession_Destroy(), KineticSession_Disconnect(), and LOG0.

KineticStatus KineticClient_GetTerminationStatus ( KineticSession *const  session)

Returns the reason reported in the case of the Kinetic device terminating a session in the case of a catastrophic error occurring.

Parameters
sessionThe KineticSession to query.
Returns
Returns the status reported prior to termination or KINTEIC_STATUS_SUCCESS if not terminated.

Definition at line 140 of file kinetic_client.c.

References KineticSession_GetTerminationStatus().

KineticStatus KineticClient_NoOp ( KineticSession *const  session)

Executes a NOOP operation to test whether the Kinetic Device is operational.

Parameters
sessionThe connected KineticSession to use for the operation.
Returns
Returns the resulting KineticStatus.

Definition at line 145 of file kinetic_client.c.

References KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildNoop(), and KineticController_ExecuteOperation().

KineticStatus KineticClient_Put ( KineticSession *const  session,
KineticEntry *const  entry,
KineticCompletionClosure closure 
)

Executes a PUT operation to store/update an entry on the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation.
entryKey/value entry for object to store. 'value' must specify the data to be stored. If a closure is provided this pointer must remain valid until the closure callback is called.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus.

Definition at line 156 of file kinetic_client.c.

References ByteBuffer::array, ByteArray::data, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_SUCCESS, KineticAllocator_FreeOperation(), KineticAllocator_NewOperation(), KineticBuilder_BuildPut(), KineticController_ExecuteOperation(), ByteArray::len, and KineticEntry::value.

KineticStatus KineticClient_Flush ( KineticSession *const  session,
KineticCompletionClosure closure 
)

Executes a FLUSHALLDATA operation to flush pending PUTs or DELETEs.

Parameters
sessionThe connected KineticSession to use for the operation.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus.

Definition at line 184 of file kinetic_client.c.

References KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildFlush(), and KineticController_ExecuteOperation().

static bool has_key ( KineticEntry *const  entry)
static

Definition at line 199 of file kinetic_client.c.

References ByteBuffer::array, ByteArray::data, and KineticEntry::key.

static bool has_value_buffer ( KineticEntry *const  entry)
static

Definition at line 204 of file kinetic_client.c.

References ByteBuffer::array, ByteArray::data, and KineticEntry::value.

static KineticStatus handle_get_command ( GET_COMMAND  cmd,
KineticSession *const  session,
KineticEntry *const  entry,
KineticCompletionClosure closure 
)
static
KineticStatus KineticClient_Get ( KineticSession *const  session,
KineticEntry *const  entry,
KineticCompletionClosure closure 
)

Executes a GET operation to retrieve an entry from the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation.
entryKey/value entry for object to retrieve. 'value' will be populated unless 'metadataOnly' is set to 'true'. If a closure is provided this pointer must remain valid until the closure callback is called.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus.

Definition at line 253 of file kinetic_client.c.

References CMD_GET, and handle_get_command().

KineticStatus KineticClient_GetPrevious ( KineticSession *const  session,
KineticEntry *const  entry,
KineticCompletionClosure closure 
)

Executes a GETPREVIOUS operation to retrieve the next entry from the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation.
entryKey/value entry for object to retrieve. 'value' will be populated unless 'metadataOnly' is set to 'true'. The key and value fields will be populated with the previous key and its corresponding value, according to lexicographical byte order. If a closure is provided this pointer must remain valid until the closure callback is called.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus.

Definition at line 260 of file kinetic_client.c.

References CMD_GET_PREVIOUS, and handle_get_command().

KineticStatus KineticClient_GetNext ( KineticSession *const  session,
KineticEntry *const  entry,
KineticCompletionClosure closure 
)

Executes a GETNEXT operation to retrieve the next entry from the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation.
entryKey/value entry for object to retrieve. 'value' will be populated unless 'metadataOnly' is set to 'true'. The key and value fields will be populated with the next key and its corresponding value, according to lexicographical byte order. If a closure is provided this pointer must remain valid until the closure callback is called.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus.

Definition at line 267 of file kinetic_client.c.

References CMD_GET_NEXT, and handle_get_command().

KineticStatus KineticClient_Delete ( KineticSession *const  session,
KineticEntry *const  entry,
KineticCompletionClosure closure 
)

Executes a DELETE operation to delete an entry from the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation.
entryKey/value entry for object to delete. 'value' is not used for this operation.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus.

Definition at line 274 of file kinetic_client.c.

References KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildDelete(), and KineticController_ExecuteOperation().

KineticStatus KineticClient_GetKeyRange ( KineticSession *const  session,
KineticKeyRange range,
ByteBufferArray keys,
KineticCompletionClosure closure 
)

Executes a GETKEYRANGE operation to retrieve a set of keys in the range specified range from the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation
rangeKineticKeyRange specifying keys to return
keysByteBufferArray to store the retrieved keys. If a closure is provided, this must point to valid memory until the closure callback is called.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns 0 upon success, -1 or the Kinetic status code upon failure

Definition at line 291 of file kinetic_client.c.

References ByteBufferArray::buffers, ByteBufferArray::count, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildGetKeyRange(), and KineticController_ExecuteOperation().

KineticStatus KineticClient_P2POperation ( KineticSession *const  session,
KineticP2P_Operation *const  p2pOp,
KineticCompletionClosure closure 
)

Executes a PEER2PEERPUSH operation allows a client to instruct a Kinetic Device to copy a set of keys (and associated value and metadata) to another Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation
p2pOpKineticP2P_Operation pointer. This pointer needs to remain valid during the duration of the operation. The results of P2P operation(s) will be stored in the resultStatus field of this structure.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns 0 upon success, -1 or the Kinetic status code upon failure. Note that P2P operations can be nested. This status code pertains to the initial top-level P2P operation. You'll need to check the resultStatus in the p2pOp structure to check the status of the individual P2P operations.

Definition at line 312 of file kinetic_client.c.

References KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticBuilder_BuildP2POperation(), and KineticController_ExecuteOperation().

Variable Documentation

const KineticVersionInfo VersionInfo
static
Initial value:
= {
.version = "0.12.0" ,
.protocolVersion = "3.0.5" ,
.repoCommitHash = "" ,
}

Definition at line 36 of file kinetic_client.c.