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 ()

Redis *	smaxGetRedis ()

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

setupCall Callback 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

cleanupCall Callback 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

server SMA-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

	table	Host name or owner ID whose variable to count.
[out]	n	Pointer 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

table Hash 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]	table	Hash table name.
[in]	key	Variable name under which the data is stored.
[in]	type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
[in]	count	Number of points to retrieve into the buffer.
[out]	value	Pointer to the buffer to which the data is to be retrieved.
[out]	meta	Pointer 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

setupCall Callback 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

cleanupCall Callback 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

username	Redis ACL user name (if any), or NULL for no user-based authentication
password	Redis 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

idx	The 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

name	the 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

f	The 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

isEnabled TRUE 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

servers	An array of known Sentinel servers
nServers	The 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

host	The SMA-X REdis server host name or IP address.
port	The 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

value TRUE 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

table	Hash table name in which to share entry.
key	Variable name under which the data is stored.
value	Pointer to the buffer whose data is to be shared.
type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
count	Number 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

table	Hash table in which to write entry.
key	Variable name under which the data is stored.
ptr	Pointer to the data buffer, such as an `int[][][]` or `float[][]`.
type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
ndim	Dimensionality of the data (0 <= `ndim` <= X_MAX_DIMS).
sizes	An 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

table	Hash table in which to write entry.
f	Pointer 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

id	Structure's ID, i.e. its own aggregated hash table name.
s	Pointer 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.

Macros

Functions

Variables

Detailed Description

Function Documentation

◆ smaxAddConnectHook()

◆ smaxAddDisconnectHook()

◆ smaxConnect()

◆ smaxConnectTo()

◆ smaxDisconnect()

◆ smaxGetHostName()

◆ smaxGetKeys()

◆ smaxGetProgramID()

◆ smaxGetRedis()

◆ smaxIsConnected()

◆ smaxIsPipelined()

◆ smaxIsVerbose()

◆ smaxKeyCount()

◆ smaxPull()

◆ smaxReconnect()

◆ smaxRemoveConnectHook()

◆ smaxRemoveDisconnectHook()

◆ smaxReset()

◆ smaxSetAuth()

◆ smaxSetDB()

◆ smaxSetHostName()

◆ smaxSetPipelineConsumer()

◆ smaxSetPipelined()

◆ smaxSetSentinel()

◆ smaxSetServer()

◆ smaxSetTcpBuf()

◆ smaxSetVerbose()

◆ smaxShare()

◆ smaxShareArray()

◆ smaxShareField()

◆ smaxShareStruct()