smax-messages.c File Reference

Simple API for sending and receiving program broadcast messages through SMA-X. More...

Macros
#define	_BSD_SOURCE
	vsnprinf() feature macro for glibc <= 2.19
#define	MESSAGES_ID   "messages"
	Redis PUB_SUB channel head used for program messages.
#define	MESSAGES_PREFIX   MESSAGES_ID X_SEP
	Prefix for Redis PUB/SUB channel for program messages (e.g. "messages:")

Functions
int	smaxAddDefaultMessageProcessor (const char *host, const char *prog, const char *type)
int	smaxAddMessageProcessor (const char *host, const char *prog, const char *type, void(*f)(XMessage *))
int	smaxRemoveMessageProcessor (int id)
int	smaxSendDebug (const char *msg,...)
int	smaxSendDetail (const char *msg,...)
int	smaxSendError (const char *msg,...)
int	smaxSendInfo (const char *msg,...)
int	smaxSendProgress (double fraction, const char *msg,...)
int	smaxSendStatus (const char *msg,...)
int	smaxSendWarning (const char *msg,...)
void	smaxSetMessageSenderID (const char *id)

Detailed Description

Simple API for sending and receiving program broadcast messages through SMA-X.

Author

Attila Kovacs

Date

Created on 12 December 2020

Function Documentation

smaxAddDefaultMessageProcessor()

int smaxAddDefaultMessageProcessor	(	const char *	host,
		const char *	prog,
		const char *	type
	)

Report messages to stdout/stderr in default formats.

Parameters

host	Host name where messages originate from, or "*" or NULL if any.
prog	Program name of message originator, or "*" or NULL if any.
type	Message type, or "*" or NULL if any.

Returns

Serial ID number (> 0) of the message processor, or X_NULL.

References smaxAddMessageProcessor().

smaxAddMessageProcessor()

int smaxAddMessageProcessor	(	const char *	host,
		const char *	prog,
		const char *	type,
		void(*)(XMessage *)	f
	)

Adds a message processor function for a specific host (or all hosts), a specific program (or all programs), and a specific message type (or all message types).

Parameters

host	Host name where messages originate from, or "*" or NULL if any.
prog	Program name of message originator, or "*" or NULL if any.
type	Message type, or "*" or NULL if any.
f	Callback function

Returns

Serial ID number (> 0) of the message processor, or X_NULL if callback function is null, or X_FAILURE if malloc failed.

See also

smaxRemoveMessageProcessor()

References MESSAGES_PREFIX, redisxAddSubscriber(), redisxSubscribe(), smaxGetRedis(), smaxRemoveMessageProcessor(), x_error(), X_NULL, X_SEP, X_SEP_LENGTH, X_SUCCESS, x_trace(), and xStringCopyOf().

smaxRemoveMessageProcessor()

int smaxRemoveMessageProcessor

(

int

id

)

Stops a running message processor.

Parameters

id	Message processor ID, as returned by smaxAddMessageProcessor()

Returns

X_SUCCESS (0) if successful, or X_NULL if no message processor is running by that ID.

See also

smaxAddMessageProcessor()

References redisxRemoveSubscribers(), redisxUnsubscribe(), smaxGetRedis(), X_NULL, and X_SUCCESS.

smaxSendDebug()

int smaxSendDebug	(	const char *	msg,
			...
	)

Broadcast a debugging message via SMA-X (e.g. program traces). Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

References SMAX_MSG_DEBUG, and X_SUCCESS.

smaxSendDetail()

int smaxSendDetail	(	const char *	msg,
			...
	)

Broadcast non-essential verbose informational detail via SMA-X. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

References SMAX_MSG_DETAIL, and X_SUCCESS.

smaxSendError()

int smaxSendError	(	const char *	msg,
			...
	)

Broadcast an error message via SMA-X. Errors should be used for an issues that impair program functionality. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

smaxSendWarning();

smaxSendDebug();

References SMAX_MSG_ERROR, and X_SUCCESS.

smaxSendInfo()

int smaxSendInfo	(	const char *	msg,
			...
	)

Broadcast an informational message via SMA-X. These should be confirmations or essential information reported back to users. Non-essential information should be sent with sendDetail() instead. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

sendDetail()

sendStatus()

References SMAX_MSG_INFO, and X_SUCCESS.

smaxSendProgress()

int smaxSendProgress	(	double	fraction,
		const char *	msg,
			...
	)

Broadcast a progress update over SMA-X. Apart from the progress fraction argument, it works just like printf().

Parameters

fraction	(0.0:1.0) Completion fraction.
msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

References SMAX_MSG_DETAIL, x_error(), X_NULL, and X_SUCCESS.

smaxSendStatus()

int smaxSendStatus	(	const char *	msg,
			...
	)

Broadcast a program status update via SMA-X. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

sendInfo()

References SMAX_MSG_STATUS, and X_SUCCESS.

smaxSendWarning()

int smaxSendWarning	(	const char *	msg,
			...
	)

Broadcast a warning message via SMA-X. Warnings should be used for any potentially problematic issues that nonetheless do not impair program functionality. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

smaxSendError();

smaxSendDebug();

References SMAX_MSG_WARNING, and X_SUCCESS.

smaxSetMessageSenderID()

void smaxSetMessageSenderID

(

const char *

id

)

Sets the sender ID for outgoing program messages. By default the sender ID is <host>:<program> for the program that calls this function, but it can be modified to use some other SMA-X style hierarchical ID also.

Parameters

id	The new sender ID for outgoing program messages, or NULL to reinstate the default <host>:<program> style ID. The argument is not referenced and can be deallocated as desired after the call without affecting the newly defined message ID.

References xStringCopyOf().