Message queue

message queues (messages of variable size) More...

Macros
#define	OS_MSG_BUFFER(buf, limit, size)
	define message queue data buffer
#define	OS_MSG(msg, limit, size)
	define and initialize a message queue object
#define	static_MSG(msg, limit, size)
	static alias of OS_MSG()
#define	MSG_INIT(limit, size)
	create and initialize a message queue object
#define	MSG_CREATE(limit, size)
	create and initialize a message queue object
#define	MSG_NEW   MSG_CREATE
	alias of MSG_CREATE()

Typedefs
typedef struct __msh	msh_t
	message header

Functions
void	msg_init (msg_t *msg, size_t size, void *data, size_t bufsize)
	initialize a message queue object
void	msg_reset (msg_t *msg)
	reset the message queue object and wake up all waiting tasks with 'E_STOPPED' event value
void	msg_kill (msg_t *msg)
	alias of msg_reset()
int	msg_take (msg_t *msg, void *data, size_t size, size_t *read)
	try to transfer data from the message queue object, don't wait if the message queue object is empty
int	msg_tryWait (msg_t *msg, void *data, size_t size, size_t *read)
	alias of msg_take()
int	msg_takeAsync (msg_t *msg, void *data, size_t size, size_t *read)
	Async alias of msg_take().
int	msg_waitFor (msg_t *msg, void *data, size_t size, size_t *read, cnt_t delay)
	try to transfer data from the message queue object, wait for given duration of time while the message queue object is empty
int	msg_waitUntil (msg_t *msg, void *data, size_t size, size_t *read, cnt_t time)
	try to transfer data from the message queue object, wait until given timepoint while the message queue object is empty
int	msg_wait (msg_t *msg, void *data, size_t size, size_t *read)
	try to transfer data from the message queue object, wait indefinitely while the message queue object is empty
int	msg_waitAsync (msg_t *msg, void *data, size_t size, size_t *read)
	Async alias of msg_wait().
int	msg_give (msg_t *msg, const void *data, size_t size)
	try to transfer data to the message queue object, don't wait if the message queue object is full
int	msg_giveAsync (msg_t *msg, const void *data, size_t size)
	Async alias of msg_give().
int	msg_sendFor (msg_t *msg, const void *data, size_t size, cnt_t delay)
	try to transfer data to the message queue object, wait for given duration of time while the message queue object is full
int	msg_sendUntil (msg_t *msg, const void *data, size_t size, cnt_t time)
	try to transfer data to the message queue object, wait until given timepoint while the message queue object is full
int	msg_send (msg_t *msg, const void *data, size_t size)
	try to transfer data to the message queue object, wait indefinitely while the message queue object is full
int	msg_sendAsync (msg_t *msg, const void *data, size_t size)
	Async alias of msg_send().
int	msg_push (msg_t *msg, const void *data, size_t size)
	try to transfer data to the message queue object, remove the oldest data if the message queue object is full
size_t	msg_count (msg_t *msg)
	return the amount of data contained in the message queue
size_t	msg_space (msg_t *msg)
	return the amount of free space in the message queue
size_t	msg_limit (msg_t *msg)
	return the size of the message queue
size_t	msg_size (msg_t *msg)
	return max size of a message in the message queue

Variables
char	data []
	message data

Detailed Description

message queues (messages of variable size)

Macro Definition Documentation

OS_MSG_BUFFER

#define OS_MSG_BUFFER	(		buf,
			limit,
			size )

Value:

char buf[limit * MSG_SIZE(size)]

define message queue data buffer

Parameters

buf	name of the buffer (passed to the init function)
limit	size of a queue (max number of stored messages)
size	max size of a single message (in bytes)

OS_MSG

#define OS_MSG	(		msg,
			limit,
			size )

Value:

static char msg##__buf[limit * MSG_SIZE(size)]; \
       msg_t msg[] = { _MSG_INIT( limit, size, msg##__buf ) }

define and initialize a message queue object

Parameters

msg	name of a pointer to message queue object
limit	size of a queue (max number of stored messages)
size	max size of a single message (in bytes)

static_MSG

#define static_MSG	(		msg,
			limit,
			size )

Value:

static char msg##__buf[limit * MSG_SIZE(size)]; \
static msg_t msg[] = { _MSG_INIT( limit, size, msg##__buf ) }

static alias of OS_MSG()

MSG_INIT

#define MSG_INIT	(		limit,
			size )

Value:

_MSG_INIT( limit, size, _MSG_DATA( limit, size ) )

create and initialize a message queue object

Parameters

limit	size of a queue (max number of stored messages)
size	max size of a single message (in bytes)

Returns

message queue object

Note

use only in 'C' code

MSG_CREATE

#define MSG_CREATE	(		limit,
			size )

Value:

{ MSG_INIT  ( limit, size ) }

create and initialize a message queue object

Parameters

limit	size of a queue (max number of stored messages)
size	max size of a single message (in bytes)

Returns

message queue object as array (id)

Note

use only in 'C' code

Function Documentation

msg_init()

void msg_init	(	msg_t *	msg,
		size_t	size,
		void *	data,
		size_t	bufsize )

initialize a message queue object

Parameters

msg	pointer to message queue object
size	max size of a single message (in bytes)
data	message queue data buffer
bufsize	size of the data buffer (in bytes)

msg_reset()

void msg_reset

(

msg_t *

msg

)

reset the message queue object and wake up all waiting tasks with 'E_STOPPED' event value

Parameters

msg	pointer to message queue object

Note

use only in thread mode

msg_take()

int msg_take	(	msg_t *	msg,
		void *	data,
		size_t	size,
		size_t *	read )

try to transfer data from the message queue object, don't wait if the message queue object is empty

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer
read	pointer to the variable getting number of read bytes

Return values

E_SUCCESS	variable 'read' contains the number of bytes read from the message queue
E_FAILURE	not enough space in the buffer
E_TIMEOUT	message queue object is empty, try again

Note

use Async alias for communication with unmasked interrupt handlers

msg_waitFor()

int msg_waitFor	(	msg_t *	msg,
		void *	data,
		size_t	size,
		size_t *	read,
		cnt_t	delay )

try to transfer data from the message queue object, wait for given duration of time while the message queue object is empty

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer
read	pointer to the variable getting number of read bytes
delay	duration of time (maximum number of ticks to wait while the message queue object is empty) IMMEDIATE: don't wait if the message queue object is empty INFINITE: wait indefinitely while the message queue object is empty

Return values

E_SUCCESS	variable 'read' contains the number of bytes read from the message queue
E_FAILURE	not enough space in the buffer
E_STOPPED	message queue object was reseted before the specified timeout expired
E_TIMEOUT	message queue object is empty and was not received data before the specified timeout expired

msg_waitUntil()

int msg_waitUntil	(	msg_t *	msg,
		void *	data,
		size_t	size,
		size_t *	read,
		cnt_t	time )

try to transfer data from the message queue object, wait until given timepoint while the message queue object is empty

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer
read	pointer to the variable getting number of read bytes
time	timepoint value

Return values

E_SUCCESS	variable 'read' contains the number of bytes read from the message queue
E_FAILURE	not enough space in the buffer
E_STOPPED	message queue object was reseted before the specified timeout expired
E_TIMEOUT	message queue object is empty and was not received data before the specified timeout expired

msg_wait()

int msg_wait ( msg_t * msg, void * data, size_t size, size_t * read )

inline

try to transfer data from the message queue object, wait indefinitely while the message queue object is empty

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer
read	pointer to the variable getting number of read bytes

Return values

E_SUCCESS	variable 'read' contains the number of bytes read from the message queue
E_FAILURE	not enough space in the buffer
E_STOPPED	message queue object was reseted

Note

use Async alias for communication with unmasked interrupt handlers

msg_give()

int msg_give	(	msg_t *	msg,
		const void *	data,
		size_t	size )

try to transfer data to the message queue object, don't wait if the message queue object is full

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer

Return values

E_SUCCESS	message data was successfully transferred to the message queue object
E_FAILURE	too much data in the buffer
E_TIMEOUT	message queue object is full, try again

Note

use Async alias for communication with unmasked interrupt handlers

msg_sendFor()

int msg_sendFor	(	msg_t *	msg,
		const void *	data,
		size_t	size,
		cnt_t	delay )

try to transfer data to the message queue object, wait for given duration of time while the message queue object is full

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer
delay	duration of time (maximum number of ticks to wait while the message queue object is full) IMMEDIATE: don't wait if the message queue object is full INFINITE: wait indefinitely while the message queue object is full

Return values

E_SUCCESS	message data was successfully transferred to the message queue object
E_FAILURE	too much data in the buffer
E_STOPPED	message queue object was reseted before the specified timeout expired
E_TIMEOUT	message queue object is full and was not issued data before the specified timeout expired

msg_sendUntil()

int msg_sendUntil	(	msg_t *	msg,
		const void *	data,
		size_t	size,
		cnt_t	time )

try to transfer data to the message queue object, wait until given timepoint while the message queue object is full

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer
time	timepoint value

Return values

E_SUCCESS	message data was successfully transferred to the message queue object
E_FAILURE	too much data in the buffer
E_STOPPED	message queue object was reseted before the specified timeout expired
E_TIMEOUT	message queue object is full and was not issued data before the specified timeout expired

msg_send()

int msg_send ( msg_t * msg, const void * data, size_t size )

inline

try to transfer data to the message queue object, wait indefinitely while the message queue object is full

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer

Return values

E_SUCCESS	message data was successfully transferred to the message queue object
E_FAILURE	too much data in the buffer
E_STOPPED	message queue object was reseted

Note

use Async alias for communication with unmasked interrupt handlers

msg_push()

int msg_push	(	msg_t *	msg,
		const void *	data,
		size_t	size )

try to transfer data to the message queue object, remove the oldest data if the message queue object is full

Parameters

msg	pointer to message queue object
data	pointer to the buffer
size	size of the buffer

Return values

E_SUCCESS	message data was successfully transferred to the message queue object
E_FAILURE	too much data in the buffer

msg_count()

size_t msg_count

(

msg_t *

msg

)

return the amount of data contained in the message queue

Parameters

msg	pointer to message queue object

Returns

amount of data contained in the message queue

msg_space()

size_t msg_space

(

msg_t *

msg

)

return the amount of free space in the message queue

Parameters

msg	pointer to message queue object

Returns

amount of free space in the message queue

msg_limit()

size_t msg_limit

(

msg_t *

msg

)

return the size of the message queue

Parameters

msg	pointer to message queue object

Returns

size of the message queue

msg_size()

size_t msg_size ( msg_t * msg )

inline

return max size of a message in the message queue

Parameters

msg	pointer to message queue object

Returns

max size of a message in the message queue