Functions
int	smaxAddSubscriber (const char *idStem, RedisSubscriberCall f)

int	smaxReleaseWaits ()

int	smaxRemoveSubscribers (RedisSubscriberCall f)

int	smaxSubscribe (const char table, const char key)

int	smaxUnsubscribe (const char table, const char key)

int	smaxWaitOnAnySubscribed (char changedTable, char changedKey, int timeout, sem_t *gating)

int	smaxWaitOnSubscribed (const char table, const char key, int timeout, sem_t *gating)

int	smaxWaitOnSubscribedGroup (const char matchTable, char changedKey, int timeout, sem_t gating)

int	smaxWaitOnSubscribedVar (const char matchKey, char changedTable, int timeout, sem_t gating)

Detailed Description

Date: Created on Jun 11, 2025

Author: Attila Kovacs

Function Documentation

◆ smaxAddSubscriber()

int smaxAddSubscriber	(	const char *	idStem,
		RedisSubscriberCall	f
	)

Add a subcriber (callback) function to process incoming PUB/SUB messages for a given SMA-X table (or id). The function should itself check that the channel receiving notification is indeed what it expectes before acting on it, as the callback routine will be invoked for any update inside the specified table, unless the table argument refers to a specific aggregate ID of a single variable. This call only registers the callback routine for SMA-X update notifications for variables that begin with the specified stem. You will still have to subscrive to any relevant variables with smaxSubscribe() to enable delivering update notifications for the variables of your choice.

Parameters

idStem	Table name or ID stem for which the supplied callback function will be invoked as long as the beginning of the PUB/SUB update channel matches the given stem. Alternatively, it can be a fully qualified SMA-X ID (of the form table:key) of a single variable, or NULL to call with all updates
f	The function to call when there is an incoming PUB/SUB update to a channel starting with stem.

Returns: X_SUCCESS if successful, or else an approriate error code by redisxAddSubscriber()

See also: smaxSubscribe()

References redisxAddSubscriber(), SMAX_UPDATES_ROOT, smaxError(), smaxGetRedis(), X_NO_INIT, X_SUCCESS, and xGetAggregateID().

◆ smaxReleaseWaits()

int smaxReleaseWaits ( )

Unblocks all smax_wait*() calls, which will return X_REL_PREMATURE, as a result.

Returns: X_SUCCESS (0)

See also: smaxWaitOnAnySubscribed()

References RELEASEID, X_SUCCESS, and xvprintf.

◆ smaxRemoveSubscribers()

int smaxRemoveSubscribers ( RedisSubscriberCall f )

Remove all instances of a subscriber callback function from the current list of functions processing PUB/SUB messages. This call only deactivates the callback routine, but does not stop the delivery of update notifications from the Redis server. You should therefore also call smaxUnsubscribe() as appropriate to stop notifications for variables that no longer have associated callbacks.

Parameters

f	Function to remove

Returns: X_SUCCESS (0) if successful, or else an error (<0) returned by redisxRemoveSubscriber().

See also: smaxUnsubscribe()

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

◆ smaxSubscribe()

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

Subscribes to a specific key(s) in specific group(s). Both the group and key names may contain Redis subscription patterns, e.g. '*' or '?', or bound characters in square-brackets, e.g. '[ab]'. The subscription only enables receiving update notifications from Redis for the specified variable or variables. After subscribing, you can either wait on the subscribed variables to change, or add callback functions to process subscribed variables changes, via smaxAddSubscriber().

Parameters

table	Variable group pattern, i.e. hash-table names. (NULL is the same as '*').
key	Variable name pattern. (if NULL then subscribes only to the table stem).

Returns: X_SUCCESS if successfully subscribed to the Redis distribution channel. X_NO_SERVICE if there is no active connection to the Redis server. X_NULL if the channel argument is NULL X_NO_INIT if the SMA-X library was not initialized.

See also: smaxUnsubscribe(); smaxWaitOnSubscribed(); smaxWaitOnSubscribedGroup(); smaxWaitOnSubscribedVar(); smaxWaitOnAnySubscribed(); smaxAddSubscriber()

References redisxSubscribe(), smaxAddDisconnectHook(), smaxError(), smaxGetRedis(), XField::value, X_NO_INIT, X_SUCCESS, xAllocLookup(), xCreateIntField(), xLookupField(), xLookupPut(), and xSplitID().

◆ smaxUnsubscribe()

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

Unsubscribes from a specific key(s) in specific group(s). Both the group and key names may contain Redis subscription patterns, e.g. '*' or '?', or bound characters in square-brackets, e.g. '[ab]'. Unsubscribing will only stops the delivery of update notifications for the affected varuiables, but does not deactivate the associated callbacks for these added via smaxAddSubscriber(). Therefore you should also call smaxRemovesubscribers() as appropriate to deactivate actions that can no longer get triggered by updates.

Parameters

table	Variable group pattern, i.e. structure or hash-table name(s) (NULL is the same as '*').
key	Variable name pattern. (if NULL then unsubscribes only from the table stem).

Returns: X_SUCCESS if successfully unsubscribed to the Redis distribution channel. X_NO_SERVICE if there is no active connection to the Redis server. X_NULL if the channel argument is NULL X_NO_INIT if the SMA-X library was not initialized.

See also: smaxSubscribe(); smaxRemoveSubscribers()

References redisxUnsubscribe(), smaxError(), smaxGetRedis(), XField::value, X_NO_INIT, X_SUCCESS, xDestroyField(), xLookupField(), and xLookupRemove().

◆ smaxWaitOnAnySubscribed()

int smaxWaitOnAnySubscribed	(	char **	changedTable,
		char **	changedKey,
		int	timeout,
		sem_t *	gating
	)

Waits until any variable was pushed on any host, returning both the host and variable name for the updated value. The variable must be already subscribed to with smaxSubscribe(), or else the wait will not receive update notifications.

Parameters

[out]	changedTable	Pointer to the variable that points to the string buffer for the returned table name or NULL. The lease of the buffer is for the call only.
[out]	changedKey	Pointer to the variable that points to the string buffer for the returned variable name or NULL. The lease of the buffer is for the call only.
[in]	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.
[in,out]	gating	Optional semaphore to post after thuis wait call gains exclusive access to the notification mutex. Another thread may wait on that semaphore before it too tries to get exclusive access to SMA-X notifications via some other library call, to ensure that the wait is entered (or else fails) in a timely manner, without unwittingly being blocked by the other thread. Typically, you can set it to NULL if such cross-thread gating is not required.

Returns: X_SUCCESS (0) if a variable was pushed on a host. X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_NO_SERVICE if the connection was broken X_GROUP_INVALID if the buffer for the returned table name is NULL. X_NAME_INVALID if the buffer for the returned variable name is NULL. X_INTERRUPTED if smaxReleaseWaits() was called. X_INCOMPLETE if the wait timed out.

See also: smaxSubscribe(); smaxWaitOnSubscribed(); smaxWaitOnSubscribedGroup(); smaxReleaseWaits()

References RELEASEID, smaxError(), smaxGetRedis(), smaxIsConnected(), x_error(), X_GROUP_INVALID, X_INCOMPLETE, X_INTERRUPTED, X_NAME_INVALID, X_NO_INIT, X_NO_SERVICE, X_SEP_LENGTH, X_SUCCESS, X_TIMEDOUT, x_warn(), xLastSeparator(), xStringCopyOf(), and xvprintf.

◆ smaxWaitOnSubscribed()

int smaxWaitOnSubscribed	(	const char *	table,
		const char *	key,
		int	timeout,
		sem_t *	gating
	)

Waits for a specific pushed entry. There must be an active subscription that includes the specified group & variable, or else the call will block indefinitely.

Parameters

	table	Hash table name
	key	Variable name to wait on.
	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.
[in,out]	gating	Optional semaphore to post after thuis wait call gains exclusive access to the notification mutex. Another thread may wait on that semaphore before it too tries to get exclusive access to SMA-X notifications via some other library call, to ensure that the wait is entered (or else fails) in a timely manner, without unwittingly being blocked by the other thread. Typically, you can set it to NULL if such cross-thread gating is not required.

Returns: X_SUCCESS (0) if the variable was updated on some host (or owner). X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_GROUP_INVALID if the 'group' argument is NULL; X_NAME_INVALID if the 'key' argument is NULL. X_REL_PREMATURE if smaxReleaseWaits() was called.

See also: smaxSubscribe(); smaxWaitOnSubscribed(); smaxWaitOnSubscribedGroup(); smaxWaitOnSubscribedVar(); smaxWaitOnAnySubscribed(); smaxReleaseWaits()

References x_error(), X_GROUP_INVALID, X_NAME_INVALID, and X_SUCCESS.

◆ smaxWaitOnSubscribedGroup()

int smaxWaitOnSubscribedGroup	(	const char *	matchTable,
		char **	changedKey,
		int	timeout,
		sem_t *	gating
	)

Waits for changes on a specific group. The must be an active subscription including that group, or else the call will block indefinitely.

Parameters

[in]	matchTable	Hash table name (e.g. owner ID) to wait on.
[out]	changedKey	Pointer to the string that holds the name of the variable which unblocked the wait or which is set to NULL. The lease of the buffer is for the call only. The caller should copy its content if persistent storage is required.
[in]	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.
[in,out]	gating	Optional semaphore to post after thuis wait call gains exclusive access to the notification mutex. Another thread may wait on that semaphore before it too tries to get exclusive access to SMA-X notifications via some other library call, to ensure that the wait is entered (or else fails) in a timely manner, without unwittingly being blocked by the other thread. Typically, you can set it to NULL if such cross-thread gating is not required.

Returns: X_SUCCESS (0) if a variable was updated on the host. X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_GROUP_INVALID if the table name to match is invalid. X_REL_PREMATURE if smaxReleaseWaits() was called.

See also: smaxSubscribe(); smaxWaitOnSubscribedVar(); smaxWaitOnSubscribed(); smaxWaitOnAnySubscribed(); smaxReleaseWaits()

References x_error(), X_GROUP_INVALID, and X_SUCCESS.

◆ smaxWaitOnSubscribedVar()

int smaxWaitOnSubscribedVar	(	const char *	matchKey,
		char **	changedTable,
		int	timeout,
		sem_t *	gating
	)

Waits for a specific pushed variable from any group/table. There must be an active subscription that includes the specified variable in one or more groups/tables, or else the call will block indefinitely.

Parameters

[in]	matchKey	Variable name to wait on.
[out]	changedTable	Pointer to the string that holds the name of the table which unblocked the wait or which is set to NULL. The lease of the buffer is for the call only. The caller should copy its content if persistent storage is required.
[in]	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.
[in,out]	gating	Optional semaphore to post after thuis wait call gains exclusive access to the notification mutex. Another thread may wait on that semaphore before it too tries to get exclusive access to SMA-X notifications via some other library call, to ensure that the wait is entered (or else fails) in a timely manner, without unwittingly being blocked by the other thread. Typically, you can set it to NULL if such cross-thread gating is not required.

Returns: X_SUCCESS (0) if the variable was updated on some host (or owner). X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_NAME_INVALID if the 'key' argument is NULL. X_REL_PREMATURE if smaxReleaseWaits() was called.

See also: smaxSubscribe(); smaxWaitOnSubscribedGroup(); smaxWaitOnSubscribed(); smaxWaitOnAnySubscribed(); smaxReleaseWaits()

References x_error(), X_NAME_INVALID, and X_SUCCESS.

Functions

Detailed Description

Function Documentation

◆ smaxAddSubscriber()

◆ smaxReleaseWaits()

◆ smaxRemoveSubscribers()

◆ smaxSubscribe()

◆ smaxUnsubscribe()

◆ smaxWaitOnAnySubscribed()

◆ smaxWaitOnSubscribed()

◆ smaxWaitOnSubscribedGroup()

◆ smaxWaitOnSubscribedVar()