A set of functions to support the efficient retrieval of lazy variables, that is variables that change infrequently, from the SMA-X database. Rather than querying the database on every call, the first lazy pull of a variable initiates monitoring for updates. The pull requests will return the current state of the variable at all times, but it generates minimal network traffic only when the underlying value in the database is changed. More...

Functions
int	smaxGetLazyCached (const char table, const char key, XType type, int count, void value, XMeta meta)

int	smaxGetLazyUpdateCount (const char table, const char key)

int	smaxLazyCache (const char table, const char key, XType type)

int	smaxLazyEnd (const char table, const char key)

int	smaxLazyFlush ()

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

int	smaxLazyPullChars (const char table, const char key, char *buf, int n)

double	smaxLazyPullDouble (const char table, const char key)

double	smaxLazyPullDoubleDefault (const char table, const char key, double defaultValue)

long long	smaxLazyPullLong (const char table, const char key, long long defaultValue)

char *	smaxLazyPullString (const char table, const char key)

int	smaxLazyPullStruct (const char id, XStructure s)

Detailed Description

A set of functions to support the efficient retrieval of lazy variables, that is variables that change infrequently, from the SMA-X database. Rather than querying the database on every call, the first lazy pull of a variable initiates monitoring for updates. The pull requests will return the current state of the variable at all times, but it generates minimal network traffic only when the underlying value in the database is changed.

Date: Jun 24, 2019

Author: Attila Kovacs

Function Documentation

◆ smaxGetLazyCached()

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

Retrieve a variable from the local cache (if available), or else pull from the SMA-X database. If local caching was not previously eanbled, it will be enabled with this call, so that subsequent calls will always return data from the locally updated cache with minimal overhead and effectively no latency.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
type	The SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
count	The number of elements to retrieve
value	Pointer to the native data buffer in which to restore values
meta	Optional metadata pointer, or NULL if metadata is not required.

Returns: X_SUCCESS (0), or X_NO_SERVICE is SMA-X is not accessible, or another error (<0) from smax.h or xchange.h.

See also: sa smaxLazyCache(); sa smaxLaxyPull()

References TRUE, X_NO_SERVICE, X_SUCCESS, and x_trace().

◆ smaxGetLazyUpdateCount()

int smaxGetLazyUpdateCount	(	const char *	table,
		const char *	key
	)

Returns the actual number of times a variable has been updated from SMA-X. It may be useful information when deciding if lazy pulling is appropriate (it is if the number of pull requests exceeds the actual number of transfers significantly).

Parameters

table	The hash table name.
key	The variable name under which the data is stored.

Returns: The number of times a variable has been updated, or -1 if the variable is not being monitored, or if the arguments are invalid.

◆ smaxLazyCache()

int smaxLazyCache	(	const char *	table,
		const char *	key,
		XType	type
	)

Specify that a specific variable should be cached for minimum overhead lazy access. When a variable is lazy cached its local copy is automatically updated in the background so that accessing it is always nearly instantaneous. Lazy caching is a good choice for variables that change less frequently than they are polled typically. For variables that change frequently (ans used less frequently), lazy caching is not a great choice since it consumes network bandwidth even when the variable is not being accessed.

Once a variable is lazy cached, it can be accessed instantaneously via smaxGetLazyCached() without any blocking network operations.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
type	The SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.

Returns: X_SUCCESS (0) or X_NO_SERVICE.

See also: smaxGetLazyCached()

References FALSE, TRUE, X_NO_SERVICE, X_SUCCESS, and x_trace().

◆ smaxLazyEnd()

int smaxLazyEnd	(	const char *	table,
		const char *	key
	)

Stops processing lazy updates in the background for a given variable.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.

Returns: X_SUCCESS (0)

See also: smaxLazyFlush(); smaxLazyPull()

References X_SUCCESS.

◆ smaxLazyFlush()

int smaxLazyFlush ( )

Discards caches for all lazy variables (i.e. stops all subscriptions to variable updates, at least until the next smaxLazyPull() call). Generally speaking, it's a good idea to call this routine when one is done using a set of lazy variables for the time being, but want to avoid the tedium of calling smaxLazyEnd() individually for each of them. Note however, that after flushing the lazy caches, the fist lazy call following for each variable will inevitably result in a real SMA-X pull. So use it carefully!

Returns: Number of monitor points flushed.

See also: smaxLazyPull(); smaxLazyEnd()

References smaxRemoveSubscribers().

◆ smaxLazyPull()

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

Poll an infrequently changing variable without stressing out the network or the SMA-X database. The first lazy pull for a variable will fetch its value from SMA-X and subscribe to update notifications. Subsequent smaxLazyPull() calls to the same variable will retrieve its value from a local cache (without contacting SMA-X) as long as it is unchanged.

Note, after you are done using a variable that has been lazy pulled, you should call smaxLazyEnd() to signal that it no longer requires to be cached and updated in the background, or call smaxLazyFlush() to flush all lazy caches for all lazy variables (if that is what you want).

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
type	The SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
count	The number of points to retrieve into the buffer.
value	Pointer to the buffer to which the data is to be retrieved.
meta	Pointer to metadata or NULL if no metadata is needed.

Returns: X_SUCCESS (0) on success, or else an error code (<0) of smaxPull().

See also: smaxLazyEnd(); smaxLazyFlush(); smaxPull(); smaxQueue()

References x_error(), X_NO_SERVICE, X_NULL, X_SUCCESS, and x_trace().

◆ smaxLazyPullChars()

int smaxLazyPullChars	(	const char *	table,
		const char *	key,
		char *	buf,
		int	n
	)

Lazy pulls a string value into the specified string buffer.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
buf	Buffer to fill with stored data
n	Number of bytes to fill in buffer. The retrieved data will be truncated as necessary.

Returns: X_SUCCESS (0) if successful, or the error code (<0) returned by smaxLazyPull().

References smaxLazyPull(), X_CHARS, and X_SUCCESS.

◆ smaxLazyPullDouble()

double smaxLazyPullDouble	(	const char *	table,
		const char *	key
	)

Returns a single double-precision value for a given SMA-X variable, or NAN if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.

Returns: The floating-point value stored in SMA-X, or NaN if the value could not be retrieved.

See also: smaxLazyPullDoubleDefault(); smaxPullDouble()

References NAN, and smaxLazyPullDoubleDefault().

◆ smaxLazyPullDoubleDefault()

double smaxLazyPullDoubleDefault	(	const char *	table,
		const char *	key,
		double	defaultValue
	)

Returns a single double-precision value for a given SMA-X variable, or a default value if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns: The floating-point value stored in SMA-X, or the specified default if the value could not be retrieved.

See also: smaxLazyPullDouble(); smaxPullDoubleDefault()

References smaxLazyPull(), and X_DOUBLE.

◆ smaxLazyPullLong()

long long smaxLazyPullLong	(	const char *	table,
		const char *	key,
		long long	defaultValue
	)

Returns a single integer value for a given SMA-X variable, or a default value if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns: The long integer value stored in SMA-X, or the specified default if the value could not be retrieved.

See also: smaxPullLong()

References smaxLazyPull(), and X_LONG.

◆ smaxLazyPullString()

char * smaxLazyPullString	(	const char *	table,
		const char *	key
	)

Returns a single string value for a given SMA-X variable, or a NULL if the value could not be retrieved.

Parameters

table	Hash table name.
key	Variable name under which the data is stored.

Returns: Pointer to the string value stored in SMA-X, or NULL if the value could not be retrieved.

See also: smaxPullString()

References smaxLazyPull(), X_STRING, and x_trace_null().

◆ smaxLazyPullStruct()

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

Lazy pulls data into a structure, discarding any prior data that the structure might contain.

Parameters

[in]	id	Aggregate structure ID.
[out]	s	Destination structure to populate with the retrieved fields

Returns: X_SUCCESS (0) if successful, or the error code (<0) returned by smaxLazyPull().

See also: smaxPullStruct(); xCreateStruct()

References smaxLazyPull(), X_STRUCT, and X_SUCCESS.

Functions

Detailed Description

Function Documentation

◆ smaxGetLazyCached()

◆ smaxGetLazyUpdateCount()

◆ smaxLazyCache()

◆ smaxLazyEnd()

◆ smaxLazyFlush()

◆ smaxLazyPull()

◆ smaxLazyPullChars()

◆ smaxLazyPullDouble()

◆ smaxLazyPullDoubleDefault()

◆ smaxLazyPullLong()

◆ smaxLazyPullString()

◆ smaxLazyPullStruct()