![]() |
smax-clib v1.0
A C/C++ client library for SMA-X
|
Functions | |
char * | smaxControl (const char *table, const char *key, const void *value, XType type, int count, const char *replyTable, const char *replyKey, int timeout) |
boolean | smaxControlBoolean (const char *table, const char *key, boolean value, const char *replyTable, const char *replyKey, boolean defaultReply, int timeout) |
double | smaxControlDouble (const char *table, const char *key, double value, const char *replyTable, const char *replyKey, int timeout) |
int | smaxControlInt (const char *table, const char *key, int value, const char *replyTable, const char *replyKey, int defaultReply, int timeout) |
char * | smaxControlString (const char *table, const char *key, const char *value, const char *replyTable, const char *replyKey, int timeout) |
int | smaxSetControlFunction (const char *table, const char *key, SMAXControlFunction func, void *parg) |
Send and process control 'commands' via SMA-X by setting or monitored designated control variables Clients will set these and wait for a response in another variable, while servers will monitor the control variables and execute designated control functions when these variables are updated. The controlled application is expected to act on the request passed in the control variable, and post the result (such as the actual value) after the request was processed in the designated 'reply' variable.
For example, we set system:subsystem:control_voltage
to 0.123456 to request that the given subsystem outputs the desired voltage. The program that controls the subsystem, monitors the control_voltage
for requests ('commands'), and then sets the output voltage to the nearest possible value, then posts the actual value that was applied in system:subsystem:voltage
. Suppose, it's DAC has a resolution of 0.01 V. In that case, it might 'reply' with voltage
set to 0.12.
It is important that for every request received, the control program should post exactly one reply in the designated response variable.
The control calls of this module will simply wait for an update of the reply variable, and return the value set by the control program after the request is sent.
char * smaxControl | ( | const char * | table, |
const char * | key, | ||
const void * | value, | ||
XType | type, | ||
int | count, | ||
const char * | replyTable, | ||
const char * | replyKey, | ||
int | timeout | ||
) |
Sets an SMA-X control variable, and returns the response to the monitored reply value.
table | SMA-X table name |
key | The command keyword |
value | Pointer to the value to set |
type | The type of the value |
count | Number of elements in value |
replyTable | SMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set. |
replyKey | The keyword to monitor for responses. |
timeout | [s] Maximum time to wait for a response before returning NULL. |
References FALSE, smaxError(), smaxErrorDescription(), smaxShare(), smaxSubscribe(), smaxUnsubscribe(), x_error(), X_NAME_INVALID, X_SUCCESS, x_trace_null(), and x_warn().
boolean smaxControlBoolean | ( | const char * | table, |
const char * | key, | ||
boolean | value, | ||
const char * | replyTable, | ||
const char * | replyKey, | ||
boolean | defaultReply, | ||
int | timeout | ||
) |
Sets a boolean type SMA-X control variable, and returns the boolean response to the monitored reply, or the specified default value in case of an error.
table | SMA-X table name |
key | The command keyword |
value | Pointer to the value to set |
replyTable | SMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set. |
replyKey | The keyword to monitor for responses. |
defaultReply | The value to return in case of an error |
timeout | [s] Maximum time to wait for a response before returning NULL. |
References smaxControl(), X_BOOLEAN, x_trace(), and xParseBoolean().
double smaxControlDouble | ( | const char * | table, |
const char * | key, | ||
double | value, | ||
const char * | replyTable, | ||
const char * | replyKey, | ||
int | timeout | ||
) |
Sets a atring type SMA-X control variable, and returns the string response to the monitored reply, or NULL in case of an error.
table | SMA-X table name |
key | The command keyword |
value | Pointer to the value to set |
replyTable | SMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set. |
replyKey | The keyword to monitor for responses. |
timeout | [s] Maximum time to wait for a response before returning NAN. |
References NAN, smaxControl(), X_DOUBLE, and x_trace_null().
int smaxControlInt | ( | const char * | table, |
const char * | key, | ||
int | value, | ||
const char * | replyTable, | ||
const char * | replyKey, | ||
int | defaultReply, | ||
int | timeout | ||
) |
Sets an integer-type SMA-X control variable, and returns the integer response to the monitored reply, or the specified default value in case of an error.
table | SMA-X table name |
key | The command keyword |
value | Pointer to the value to set |
replyTable | SMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set. |
replyKey | The keyword to monitor for responses. |
defaultReply | The value to return in case of an error |
timeout | [s] Maximum time to wait for a response before returning NULL. |
References smaxControl(), X_INT, and x_trace().
char * smaxControlString | ( | const char * | table, |
const char * | key, | ||
const char * | value, | ||
const char * | replyTable, | ||
const char * | replyKey, | ||
int | timeout | ||
) |
Sets a atring type SMA-X control variable, and returns the string response to the monitored reply, or NULL in case of an error.
table | SMA-X table name |
key | The command keyword |
value | Pointer to the value to set |
replyTable | SMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set. |
replyKey | The keyword to monitor for responses. |
timeout | [s] Maximum time to wait for a response before returning NULL. |
References smaxControl(), X_STRING, and x_trace_null().
int smaxSetControlFunction | ( | const char * | table, |
const char * | key, | ||
SMAXControlFunction | func, | ||
void * | parg | ||
) |
Configures an SMA-X control function. The designated function will be called every time the monitored control variable is updated in the database, so it may act on the update as appropriate. If another control functions was already defined for the variable, it will be replaced with the new function. The same control function may be used with multiple control variables, given that the triggering control variable is passed to it as arguments.
When the control variables are updated, the associated control functions will be called asynchronously, such that previous control calls may be executing still while new ones are called. The design allows for control functions to take their sweet time executing, without holding up other time-sensitive SMA-X processing. If simultaneous execution of control functions is undesired, the control function(s) should implement mutexing as necessary to avoid conflicts / clobbering.
As a result of the asynchronous execution, there is also no guarantee of maintaining call order with respect to the order in which the control variables are updated. If two updates arrive in quick succession, it is possible that the asynchronous thread of the second one will make its call to its control function before the first one gets a chance. Thus, if order is important, you might want to process updates with a custom lower-level RedisxSubscriberCall
wrapper instead (see smaxAddSubscriber()
).
table | The hash table in which the control variable resides. |
key | the control variable to monitor. It may not contain a sepatator. |
func | The new function to call if the monitored control variable receives an update, or NULL to clear a previously configured function for the given variable. |
parg | Optional pointer argument to pass along to the command procesing function, or NULL if the control function does not need extra data. |
References SMAX_UPDATES, smaxAddSubscriber(), smaxSubscribe(), smaxUnsubscribe(), XField::value, x_error(), X_GROUP_INVALID, X_NAME_INVALID, X_SEP, X_SEP_LENGTH, X_SUCCESS, x_trace(), X_UNKNOWN, xAllocLookup(), xCreateField(), xDestroyField(), xGetAggregateID(), xLookupPut(), and xLookupRemove().