smax-clib v1.0
A C/C++ client library for SMA-X
Loading...
Searching...
No Matches
smax.c File Reference

SMA-X is a software implementation for SMA shared data, and is the base layer for the software reflective memory (RM) emulation, and DSM replacement. It works by communicating TCP/IP messages to a central Redis server. More...

Macros

#define _POSIX_C_SOURCE   199309
 For clock_gettime()
 

Functions

int smaxAddConnectHook (void(*setupCall)(void))
 
int smaxAddDisconnectHook (void(*cleanupCall)(void))
 
int smaxConnect ()
 
int smaxConnectTo (const char *server)
 
int smaxDisconnect ()
 
char * smaxGetHostName ()
 
char ** smaxGetKeys (const char *table, int *n)
 
char * smaxGetProgramID ()
 
RedissmaxGetRedis ()
 
int smaxIsConnected ()
 
boolean smaxIsPipelined ()
 
boolean smaxIsVerbose ()
 
int smaxKeyCount (const char *table)
 
int smaxPull (const char *table, const char *key, XType type, int count, void *value, XMeta *meta)
 
int smaxReconnect ()
 
int smaxRemoveConnectHook (void(*setupCall)(void))
 
int smaxRemoveDisconnectHook (void(*cleanupCall)(void))
 
int smaxReset ()
 
int smaxSetAuth (const char *username, const char *password)
 
int smaxSetDB (int idx)
 
void smaxSetHostName (const char *name)
 
int smaxSetPipelineConsumer (void(*f)(RESP *))
 
int smaxSetPipelined (boolean isEnabled)
 
int smaxSetSentinel (const RedisServer *servers, int nServers)
 
int smaxSetServer (const char *host, int port)
 
int smaxSetTcpBuf (int size)
 
void smaxSetVerbose (boolean value)
 
int smaxShare (const char *table, const char *key, const void *value, XType type, int count)
 
int smaxShareArray (const char *table, const char *key, const void *ptr, XType type, int ndim, const int *sizes)
 
int smaxShareField (const char *table, const XField *f)
 
int smaxShareStruct (const char *id, const XStructure *s)
 

Variables

char * GET_STRUCT
 SHA1 key for calling HGetStruct LUA script.
 
char * HGET_WITH_META
 SHA1 key for calling HGetWithMeta LUA script.
 
char * HMSET_WITH_META
 SHA1 key for calling HMSetWithMeta LUA script.
 
char * HSET_WITH_META
 SHA1 key for calling HSetWithMeta LUA script.
 

Detailed Description

SMA-X is a software implementation for SMA shared data, and is the base layer for the software reflective memory (RM) emulation, and DSM replacement. It works by communicating TCP/IP messages to a central Redis server.

Date
Jan 26, 2018
Author
Attila Kovacs

There is also extra functionality, for configuring, performance tweaking, verbosity control, and some convenience methods (e.g. data serialization/deserialization).

Function Documentation

◆ smaxAddConnectHook()

int smaxAddConnectHook ( void(*)(void)  setupCall)

Add a callback function for when SMA-X is connected. It's a wrapper to redisxAddConnectHook().

Parameters
setupCallCallback function
Returns
X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().
See also
smaxRemoveConnectHook()
smaxConnect()
smaxConnectTo()

References redisxAddConnectHook(), smaxError(), smaxGetRedis(), X_NO_INIT, and X_SUCCESS.

◆ smaxAddDisconnectHook()

int smaxAddDisconnectHook ( void(*)(void)  cleanupCall)

Add a callback function for when SMA-X is disconnected. It's a wrapper to redisxAddDisconnectHook().

Parameters
cleanupCallCallback function
Returns
X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().
See also
smaxRemoveDisconnectHook()
smaxDisconnect()

References redisxAddDisconnectHook(), smaxError(), smaxGetRedis(), X_NO_INIT, and X_SUCCESS.

◆ smaxConnect()

int smaxConnect ( )

Initializes the SMA-X sharing library in this runtime instance, and connects to the SMA-X server. If the server was not explicitly configure previously it will try the default server (SMAX_DEFAULT_HOSTNAME = "smax"), or else localhost (127.0.0.1).

Returns
X_SUCCESS If the library was successfully initialized X_ALREADY_OPEN If SMA-X sharing was already open. X_NO_SERVICE If the there was an issue establishing the necessary network connection(s). X_NAME_INVALID If the redis server name lookup failed. X_NULL If the Redis IP address is NULL
See also
smaxSetServer()
smaxSetSentinel()
smaxSetAuth()
smaxConnectTo()
smaxDisconnect()
smaxReconnect()
smaxIsConnected()

References redisxConnect(), redisxInit(), redisxInitSentinel(), redisxSelectDB(), redisxSetHostname(), redisxSetPassword(), redisxSetPort(), redisxSetSocketErrorHandler(), redisxSetTcpBuf(), redisxSetUser(), SMAX_DEFAULT_HOSTNAME, SMAX_SENTINEL_SERVICENAME, smaxAddConnectHook(), smaxAddDisconnectHook(), smaxGetProgramID(), smaxIsConnected(), smaxLazyFlush(), smaxReleaseWaits(), smaxSetPipelineConsumer(), smaxSetResilient(), smaxSocketErrorHandler(), TRUE, X_NO_INIT, X_SUCCESS, x_trace(), and xvprintf.

◆ smaxConnectTo()

int smaxConnectTo ( const char *  server)

Initializes the SMA-X sharing library in this runtime instance with the specified Redis server. SMA-X is initialized in resilient mode, so that we'll automatically attempt to reconnect to the Redis server if the connection is severed (once it was established). If that is not the desired behavior, you should call smaxSetResilient(FALSE) after connecting.

Parameters
serverSMA-X Redis server name or IP address, e.g. "127.0.0.1".
Returns
X_SUCCESS If the library was successfully initialized X_NO_SERVICE If the there was an issue establishing the necessary network connection(s).
See also
smaxConnect()
smaxDisconnect()
smaxReconnect()
smaxIsConnected()
smaxSetResilient()

References smaxConnect(), smaxSetServer(), and X_SUCCESS.

◆ smaxDisconnect()

int smaxDisconnect ( )

Disables the SMA-X sharing capability, closing underlying network connections.

Returns
X_SUCCESS (0) if the sharing was properly ended. X_NO_INIT if SMA-X was has not been started prior to this call.
See also
smaxConnect()
smaxConnectTo()
smaxReconnect()
smaxIsConnected()

References redisxDisconnect(), smaxIsConnected(), x_error(), X_NO_INIT, X_SUCCESS, and xvprintf.

◆ smaxGetHostName()

char * smaxGetHostName ( )

Returns the host name on which this program is running. It returns a reference to the same static variable every time. As such you should never call free() on the returned value. Note, that only the leading part of the host name is returned, so for a host that is registered as 'somenode.somedomain' only 'somenode' is returned.

Returns
The host name string (leading part only).
See also
smaxSetHostName()

References xStringCopyOf().

◆ smaxGetKeys()

char ** smaxGetKeys ( const char *  table,
int *  n 
)

Returns a snapshot of the key names stored in a given Redis hash table, ot NULL if there was an error.

Parameters
tableHost name or owner ID whose variable to count.
[out]nPointer to which the number of keys (>=0) or an error (<0) is returned. An error returned by redisxGetKeys(), or else:

X_NO_INIT if the SMA-X sharing was not initialized, e.g. via smaxConnect(). X_GROUP_INVALID if the table name is invalid. X_NULL if the output 'n' pointer is NULL.

Returns
An array of pointers to the names of Redis keys.
See also
smaxKeyCount()

References redisxGetKeys(), smaxError(), smaxGetRedis(), x_error(), X_NO_INIT, x_trace_null(), and xvprintf.

◆ smaxGetProgramID()

char * smaxGetProgramID ( )

Returns the SMA-X program ID.

Returns
The SMA-X program ID as <hostname>:<programname>, e.g. "hal9000:statusServer".

References smaxGetHostName(), and xGetAggregateID().

◆ smaxGetRedis()

Redis * smaxGetRedis ( )

Returns the Redis connection information for SMA-X

Returns
The structure containing the Redis connection data.
See also
smaxConnect()
smaxConnectTo()
smaxIsConnected()

◆ smaxIsConnected()

int smaxIsConnected ( )

Checks whether SMA-X sharing is currently open (by a preceding call to smaxConnect() call.

See also
smaxConnect()
smaxConnectTo()
smaxDisconnect()
smaxReconnect()

References redisxIsConnected().

◆ smaxIsPipelined()

boolean smaxIsPipelined ( )

Check if SMA-X is configured with pipeline mode enabled.

Returns
TRUE (1) if the pipeline is enabled, or else FALSE (0)
See also
smaxSetPipelined()

◆ smaxIsVerbose()

boolean smaxIsVerbose ( )

Checks id verbose reporting is enabled.

Returns
TRUE if verbose reporting is enabled, otherwise FALSE.
See also
smaxSetVerbose()

References redisxIsVerbose().

◆ smaxKeyCount()

int smaxKeyCount ( const char *  table)

Retrieve the current number of variables stored on host (or owner ID).

Parameters
tableHash table name.
Returns
The number of keys (fields) in the specified table (>= 0), or an error code (<0), such as: X_NO_INIT if the SMA-X sharing was not initialized, e.g. via smaConnect(). X_GROUP_INVALID if the table name is invalid. or one of the errors (<0) returned by redisxRequest().
See also
smaxGetKeys()

References RESP::n, redisxCheckRESP(), redisxDestroyRESP(), redisxRequest(), RESP_INT, smaxError(), smaxGetRedis(), x_error(), X_GROUP_INVALID, X_NO_INIT, x_trace(), and xvprintf.

◆ smaxPull()

int smaxPull ( const char *  table,
const char *  key,
XType  type,
int  count,
void *  value,
XMeta meta 
)

Pull data from the specified hash table. This calls data via the interactive client to Redis.

Parameters
[in]tableHash table name.
[in]keyVariable name under which the data is stored.
[in]typeSMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
[in]countNumber of points to retrieve into the buffer.
[out]valuePointer to the buffer to which the data is to be retrieved.
[out]metaPointer to metadata or NULL if no metadata is needed.
Returns
X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the 'table' argument is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_NULL if an essential argument is NULL or contains NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.
See also
smaxLazyPull()
smaxQueue()

References REDISX_INTERACTIVE_CHANNEL, smaxPullField(), x_error(), X_FIELD, X_NULL, X_STRUCT, X_SUCCESS, x_trace(), xGetAggregateID(), and xStringCopyOf().

◆ smaxReconnect()

int smaxReconnect ( )

Reconnects to the SMA-X server. It will try connecting repeatedly at regular intervals until the connection is made. If resilient mode is enabled, then locally accumulated shares will be sent to the Redis server upon reconnection. However, subscriptions are not automatically re-established. The caller is responsible for reinstate any necessary subscriptions after the reconnection or via an approproate connection hook.

Returns
X_SUCCESS (0) if successful X_NO_INIT if SMA-X was never initialized.

or the error returned by redisxReconnect().

See also
smaxConnect()
smaxConnectTo()
smaxDisconnect()
smaxIsConnected()
smaxSetResilient()
smaxAddConnectHook()

References redisxReconnect(), SMAX_RECONNECT_RETRY_SECONDS, x_error(), X_NO_INIT, X_SUCCESS, and xvprintf.

◆ smaxRemoveConnectHook()

int smaxRemoveConnectHook ( void(*)(void)  setupCall)

Remove a post-connection callback function. It's a wrapper to redisxRemoveConnectHook().

Parameters
setupCallCallback function
Returns
X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().
See also
smaxAddConnectHook()
smaxConnect()
smaxConnectTo()

References redisxRemoveConnectHook(), smaxError(), smaxGetRedis(), X_NO_INIT, and X_SUCCESS.

◆ smaxRemoveDisconnectHook()

int smaxRemoveDisconnectHook ( void(*)(void)  cleanupCall)

Remove a post-cdisconnect callback function. It's a wrapper to redisxRemiveDisconnectHook().

Parameters
cleanupCallCallback function
Returns
X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().
See also
smaxAddDisconnectHook()
smaxDisconnect()

References redisxRemoveDisconnectHook(), smaxError(), smaxGetRedis(), X_NO_INIT, and X_SUCCESS.

◆ smaxReset()

int smaxReset ( )

Resets the Redis server for SMA-X. SMA-X must be disconnected when this function is called, or else it will return an error. Resetting SMA-X allows to change configuration settings before the next connection.

Returns
X_SUCCESS (0) if successful or else X_ALREADY_OPEN if we are currently connected to SMA-X.
See also
smaxConnect()

References redisxDestroy(), smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

◆ smaxSetAuth()

int smaxSetAuth ( const char *  username,
const char *  password 
)

Sets the SMA-X database authentication parameters (if any) before connecting to the SMA-X server.

Parameters
usernameRedis ACL user name (if any), or NULL for no user-based authentication
passwordRedis database password (if any), or NULL if the database is not password protected
Returns
X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.
See also
smaxSetServer()
smaxConnect()

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), X_SUCCESS, and xStringCopyOf().

◆ smaxSetDB()

int smaxSetDB ( int  idx)

Sets a non-default Redis database index to use for SMA-X before connecting to the SMA-X server.

Parameters
idxThe Redis database index to use (if not the default one)
Returns
X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.
See also
smaxSetServer()
smaxConnect()

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

◆ smaxSetHostName()

void smaxSetHostName ( const char *  name)

Changes the host name to the user-specified value instead of the default (leading component of the value returned by gethostname()). Subsequent calls to smaxGetHostName() will return the newly set value. An argument of NULL resets to the default.

Parameters
namethe host name to use, or NULL to revert to the default (leading component of gethostname()).
See also
smaxGetHostName()

References xStringCopyOf().

◆ smaxSetPipelineConsumer()

int smaxSetPipelineConsumer ( void(*)(RESP *)  f)

Change the pipeline response consumer function (from it's default or other previous consumer). It is a wrapper for redisxSetPipelineConsumer().

Parameters
fThe function to process ALL pipeline responses from Redis.
Returns
X_SUCCESS (0) if successful, or else an error by redisxSetPipelineConsumer()
See also
smaxSetPipelined()
smaxIsPipelined()

References redisxSetPipelineConsumer(), smaxError(), smaxGetRedis(), X_NO_INIT, and X_SUCCESS.

◆ smaxSetPipelined()

int smaxSetPipelined ( boolean  isEnabled)

Enable or disable pipelined write operations (enabled by default). When pipelining, share calls will return as soon as the request is sent to the Redis server, without waiting for a response. Instead, responses are consumed asynchronously by a dedicated thread, which will report errors to stderr. Pipelined writes can have a significant performance advantage over handshaking at the cost of one extra socket connection to Redis (dedicated to pipelining) and the extra thread consuming responses.

The default state of pipelined writes might vary by platform (e.g. enabled on Linux, disabled on LynxOS).

IMPORTANT: calls to smaxSetPipelined() must precede the call to smaxConnect().

Parameters
isEnabledTRUE to enable pipelined writes, FALSE to disable (default is enabled).
Returns
X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.
See also
smaxIsPipelined()
smaxSetPipelineConsumer()

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

◆ smaxSetSentinel()

int smaxSetSentinel ( const RedisServer servers,
int  nServers 
)

Configure SMA-X to use a high availability Redis Sentinel configuration

Parameters
serversAn array of known Sentinel servers
nServersThe number of servers in the array
Returns
X_SUCCESS (0) if successful or else an error code <0.
See also
smaxConnect()

References redisxValidateSentinel(), SMAX_SENTINEL_SERVICENAME, x_error(), X_FAILURE, and X_SUCCESS.

◆ smaxSetServer()

int smaxSetServer ( const char *  host,
int  port 
)

Configures the SMA-X server before connecting.

Parameters
hostThe SMA-X REdis server host name or IP address.
portThe Redis port number on the SMA-X server, or &lt=0 to use the default
Returns
X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.
See also
smaxSetAuth()
smaxSetDB()
smaxConnect()

References REDISX_TCP_PORT, smaxIsConnected(), X_ALREADY_OPEN, x_error(), X_SUCCESS, and xStringCopyOf().

◆ smaxSetTcpBuf()

int smaxSetTcpBuf ( int  size)

Set the size of the TCP/IP buffers (send and receive) for future client connections.

Parameters
size(bytes) requested buffer size, or <= 0 to use default value
See also
smaxConnect;

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

◆ smaxSetVerbose()

void smaxSetVerbose ( boolean  value)

Enable or disable verbose reporting of all SMA-X operations (and possibly some details of them). Reporting is done on the standard output (stdout). It may be useful when debugging programs that use the SMA-X interface. Verbose reporting is DISABLED by default.

Parameters
valueTRUE to enable verbose reporting, or FALSE to disable.
See also
smaxIsVerbose()

References redisxSetVerbose().

◆ smaxShare()

int smaxShare ( const char *  table,
const char *  key,
const void *  value,
XType  type,
int  count 
)

Share the data into a Redis hash table over the interactive Redis client. It's a fire-and-forget type implementation, which sends the data to Redis, without waiting for confirmation of its arrival. The choice improves the efficiency and throughput, and minimizes execution time, of the call, but it also means that a pipelined pull request in quick succession, e.g. via smaxQueue(), may return a value on the pipeline client before this call is fully executed on the interactive Redis client.

(It is generally unlikely that you will follow this share call with a pipelined pull of the same variable. It would not only create superflous network traffic for no good reason, but it also would have unpredictable results. So, don't.)

Parameters
tableHash table name in which to share entry.
keyVariable name under which the data is stored.
valuePointer to the buffer whose data is to be shared.
typeSMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
countNumber of 1D elements.
Returns
X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_SIZE_INVALID if count < 1 or count > X_MAX_ELEMENTS X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.
See also
smaxShareArray()
smaxShareField()
smaxShareStruct()

References smaxShareArray(), and X_SUCCESS.

◆ smaxShareArray()

int smaxShareArray ( const char *  table,
const char *  key,
const void *  ptr,
XType  type,
int  ndim,
const int *  sizes 
)

Share a multidimensional array, such as an int[][][], or float[][], in a single atomic transaction.

Parameters
tableHash table in which to write entry.
keyVariable name under which the data is stored.
ptrPointer to the data buffer, such as an int[][][] or float[][].
typeSMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
ndimDimensionality of the data (0 <= ndim <= X_MAX_DIMS).
sizesAn array of ints containing the sizes along each dimension.
Returns
X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_SIZE_INVALID if ndim or sizes are invalid. X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.
See also
smaxShare()

References XField::isSerialized, XField::name, XField::ndim, REDISX_CMDBUF_SIZE, XField::sizes, smaxShareField(), smaxValuesToString(), TRUE, XField::type, XField::value, x_error(), X_FIELD_INIT, X_MAX_ELEMENTS, X_NULL, X_RAW, X_SIZE_INVALID, X_STRUCT, X_SUCCESS, x_trace(), and xGetElementCount().

◆ smaxShareField()

int smaxShareField ( const char *  table,
const XField f 
)

Share a field object, which may contain any SMA-X data type.

Parameters
tableHash table in which to write entry.
fPointer for XField holding the data to share.
Returns
X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_SIZE_INVALID if ndim or sizes are invalid. X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.
See also
smaxShare()
smaxShareField()
smaxShareStruct()
xSetField()
xGetField()

References XField::name, smaxShareStruct(), XField::type, XField::value, X_NO_SERVICE, X_STRUCT, X_SUCCESS, x_trace(), and xGetAggregateID().

◆ smaxShareStruct()

int smaxShareStruct ( const char *  id,
const XStructure s 
)

Share a structure, and all its data including recursive sub-structures, in a single atromic transaction.

Parameters
idStructure's ID, i.e. its own aggregated hash table name.
sPointer to the structure data.
Returns
X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.
See also
smaxShare()
smaxShareField()
xCreateStruct()

References smaxCreateField(), X_NO_SERVICE, X_STRUCT, and X_SUCCESS.