Files
file	mbx.c
	Mailbox functions.

Functions
RTAI_SYSCALL_MODE int	_rt_mbx_evdrp (MBX mbx, void msg, int msg_size, int space)
	Receives bytes as many as possible leaving the message available for another receive. More...

RTAI_SYSCALL_MODE int	rt_typed_mbx_init (MBX *mbx, int size, int type)
	Initializes a fully typed mailbox queueing tasks according to the specified type. More...

int	rt_mbx_init (MBX *mbx, int size)
	Initializes a mailbox. More...

RTAI_SYSCALL_MODE int	rt_mbx_delete (MBX *mbx)
	Deletes a mailbox. More...

RTAI_SYSCALL_MODE int	_rt_mbx_send (MBX mbx, void msg, int msg_size, int space)
	Sends a message unconditionally. More...

RTAI_SYSCALL_MODE int	_rt_mbx_send_wp (MBX mbx, void msg, int msg_size, int space)
	Sends as many bytes as possible without blocking the calling task. More...

RTAI_SYSCALL_MODE int	_rt_mbx_send_if (MBX mbx, void msg, int msg_size, int space)
	Sends a message, only if the whole message can be passed without blocking the calling task. More...

RTAI_SYSCALL_MODE int	_rt_mbx_send_until (MBX mbx, void msg, int msg_size, RTIME time, int space)
	Sends a message with absolute timeout. More...

RTAI_SYSCALL_MODE int	_rt_mbx_send_timed (MBX mbx, void msg, int msg_size, RTIME delay, int space)
	Sends a message with relative timeout. More...

RTAI_SYSCALL_MODE int	_rt_mbx_receive (MBX mbx, void msg, int msg_size, int space)
	Receives a message unconditionally. More...

RTAI_SYSCALL_MODE int	_rt_mbx_receive_wp (MBX mbx, void msg, int msg_size, int space)
	Receives bytes as many as possible, without blocking the calling task. More...

RTAI_SYSCALL_MODE int	_rt_mbx_receive_if (MBX mbx, void msg, int msg_size, int space)
	Receives a message only if the whole message can be passed without blocking the calling task. More...

RTAI_SYSCALL_MODE int	_rt_mbx_receive_until (MBX mbx, void msg, int msg_size, RTIME time, int space)
	Receives a message with absolute timeout. More...

RTAI_SYSCALL_MODE int	_rt_mbx_receive_timed (MBX mbx, void msg, int msg_size, RTIME delay, int space)
	Receives a message with relative timeout. More...

RTAI_SYSCALL_MODE int	_rt_mbx_ovrwr_send (MBX mbx, void msg, int msg_size, int space)
	Sends a message overwriting what already in the buffer if there is no place for the message. More...

RTAI_SYSCALL_MODE MBX *	_rt_typed_named_mbx_init (unsigned long mbx_name, int size, int qtype)
	Initializes a specifically typed (fifo queued, priority queued or resource queued) mailbox identified by a name. More...

RTAI_SYSCALL_MODE int	rt_named_mbx_delete (MBX *mbx)
	Deletes a named mailbox. More...

Detailed Description

Function Documentation

◆ _rt_mbx_evdrp()

RTAI_SYSCALL_MODE int _rt_mbx_evdrp	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Receives bytes as many as possible leaving the message available for another receive.

rt_mbx_evdrp receives at most msg_size of bytes of message from the mailbox mbx and then returns immediately. Does what rt_mbx_receive_wp does while keeping the message in the mailbox buffer. Useful if one needs to just preview the mailbox content, without actually receiving it.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	points to a buffer provided by the caller.
msg_size	corresponds to the size of the message to be received.

Returns: The number of bytes not received is returned.

◆ _rt_mbx_ovrwr_send()

RTAI_SYSCALL_MODE int _rt_mbx_ovrwr_send	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Sends a message overwriting what already in the buffer if there is no place for the message.

rt_mbx_ovrwr_send sends the message msg of msg_size bytes to the mailbox mbx overwriting what already in the mailbox buffer if there is no place for the message. Useful for logging purposes. It returns immediately and the caller is never blocked.

Returns

On success, 0 is returned. On failure a negative value is returned as described below:

EINVAL: mbx points to an invalid mailbox.

◆ _rt_mbx_receive()

RTAI_SYSCALL_MODE int _rt_mbx_receive	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Receives a message unconditionally.

rt_mbx_receive receives a message of msg_size bytes from the mailbox mbx. The caller will be blocked until all bytes of the message arrive or an error occurs.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	points to a buffer provided by the caller.
msg_size	corresponds to the size of the message to be received.

Returns

On success, 0 is returned. On failure a value is returned as described below:

the number of bytes not received: an error is occured in the queueing of all receiving tasks.
EINVAL: mbx points to an invalid mailbox.

◆ _rt_mbx_receive_if()

RTAI_SYSCALL_MODE int _rt_mbx_receive_if	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Receives a message only if the whole message can be passed without blocking the calling task.

rt_mbx_receive_if receives a message from the mailbox mbx if the whole message of msg_size bytes is available immediately.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	points to a buffer provided by the caller.
msg_size	corresponds to the size of the message to be received.

Returns

On success, the number of bytes not received (0 or msg_size) is returned. On failure a negative value is returned as described below:

EINVAL: mbx points to an invalid mailbox.

◆ _rt_mbx_receive_timed()

RTAI_SYSCALL_MODE int _rt_mbx_receive_timed	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		RTIME	delay,
		int	space
	)

Receives a message with relative timeout.

rt_mbx_receive_timed receives a message of msg_size bytes from the mailbox mbx. The caller will be blocked until all bytes of the message arrive, timeout expires or an error occurs.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	points to a buffer provided by the caller.
msg_size	corresponds to the size of the message received.
delay	is the timeout value relative to the current time.

Returns

On success, 0 is returned. On failure a value is returned as described below:

the number of bytes not received: an error is occured in the queueing of all receiving tasks or the timeout has expired.
EINVAL: mbx points to an invalid mailbox.

See also: notes under rt_mbx_received_until().

References _rt_mbx_receive_until().

◆ _rt_mbx_receive_until()

RTAI_SYSCALL_MODE int _rt_mbx_receive_until	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		RTIME	time,
		int	space
	)

Receives a message with absolute timeout.

rt_mbx_receive_until receives a message of msg_size bytes from the mailbox mbx. The caller will be blocked until all bytes of the message arrive, timeout expires or an error occurs.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	points to a buffer provided by the caller.
msg_size	corresponds to the size of the message received.
time	is an absolute value of the timeout.

Returns

On success, 0 is returned. On failure a value is returned as described below:

the number of bytes not received: an error is occured in the queueing of all receiving tasks or the timeout has expired.
EINVAL: mbx points to an invalid mailbox.

See also: notes under rt_mbx_received_timed().

Referenced by _rt_mbx_receive_timed().

◆ _rt_mbx_receive_wp()

RTAI_SYSCALL_MODE int _rt_mbx_receive_wp	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Receives bytes as many as possible, without blocking the calling task.

rt_mbx_receive_wp receives at most msg_size of bytes of message from the mailbox mbx then returns immediately.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	points to a buffer provided by the caller.
msg_size	corresponds to the size of the message to be received.

Returns

On success, the number of bytes not received is returned. On failure a negative value is returned as described below:

EINVAL: mbx points to not a valid mailbox.

◆ _rt_mbx_send()

RTAI_SYSCALL_MODE int _rt_mbx_send	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Sends a message unconditionally.

rt_mbx_send sends a message msg of msg_size bytes to the mailbox mbx. The caller will be blocked until the whole message is copied into the mailbox or an error occurs. Even if the message can be sent in a single shot, the sending task can be blocked if there is a task of higher priority waiting to receive from the mailbox.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	corresponds to the message to be sent.
msg_size	is the size of the message.

Returns

On success, 0 is returned. On failure a value is returned as described below:

the number of bytes not received: an error is occured in the queueing of all sending tasks.
EINVAL: mbx points to an invalid mailbox.

◆ _rt_mbx_send_if()

RTAI_SYSCALL_MODE int _rt_mbx_send_if	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Sends a message, only if the whole message can be passed without blocking the calling task.

rt_mbx_send_if tries to atomically send the message msg of msg_size bytes to the mailbox mbx. It returns immediately and the caller is never blocked.

Returns

On success, the number of unsent bytes (0 or msg_size) is returned. On failure a negative value is returned as described below:

EINVAL: mbx points to an invalid mailbox.

◆ _rt_mbx_send_timed()

RTAI_SYSCALL_MODE int _rt_mbx_send_timed	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		RTIME	delay,
		int	space
	)

Sends a message with relative timeout.

rt_mbx_send_timed send a message msg of msg_size bytes to the mailbox mbx. The caller will be blocked until all bytes of message is enqueued, timeout expires or an error occurs.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	is the message to be sent.
msg_size	corresponds to the size of the message.
delay	is the timeout value relative to the current time.

Returns

On success, 0 is returned. On failure a value is returned as described below:

the number of bytes not received: an error is occured in the queueing of all sending tasks or the timeout has expired.
EINVAL: mbx points to an invalid mailbox.

See also: notes under _rt_mbx_send_until().

References _rt_mbx_send_until().

◆ _rt_mbx_send_until()

RTAI_SYSCALL_MODE int _rt_mbx_send_until	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		RTIME	time,
		int	space
	)

Sends a message with absolute timeout.

rt_mbx_send_until sends a message msg of msg_size bytes to the mailbox mbx. The caller will be blocked until all bytes of message is enqueued, timeout expires or an error occurs.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	is the message to be sent.
msg_size	corresponds to the size of the message.
time	is an absolute value for the timeout.

Returns

On success, 0 is returned. On failure a value is returned as described below:

the number of bytes not received: an error is occured in the queueing of all sending tasks or the timeout has expired.
EINVAL: mbx points to an invalid mailbox.

See also: notes under _rt_mbx_send_timed().

Referenced by _rt_mbx_send_timed().

◆ _rt_mbx_send_wp()

RTAI_SYSCALL_MODE int _rt_mbx_send_wp	(	MBX *	mbx,
		void *	msg,
		int	msg_size,
		int	space
	)

Sends as many bytes as possible without blocking the calling task.

rt_mbx_send_wp atomically sends as many bytes of message msg as possible to the mailbox mbx then returns immediately.

Parameters

mbx	is a pointer to a user allocated mailbox structure.
msg	corresponds to the message to be sent.
msg_size	is the size of the message.

Returns

On success, the number of unsent bytes is returned. On failure a negative value is returned as described below:

EINVAL: mbx points to an invalid mailbox.

◆ _rt_typed_named_mbx_init()

RTAI_SYSCALL_MODE MBX * _rt_typed_named_mbx_init	(	unsigned long	mbx_name,
		int	size,
		int	qtype
	)

Initializes a specifically typed (fifo queued, priority queued or resource queued) mailbox identified by a name.

_rt_typed_named_mbx_init initializes a mailbox of type qtype and size size identified by name. Named mailboxed are useful for use among different processes, kernel/user space and in distributed applications, see netrpc.

Parameters

mbx_name	is the mailbox name; since it can be a clumsy identifier, services are provided to convert 6 characters identifiers to unsigned long (see nam2num()).
size	corresponds to the size of the mailbox.
qtype	corresponds to the queueing policy: FIFO_Q, PRIO_Q or RES_Q.

Returns: On success the pointer to the allocated mbx is returned. On failure, NULL is returned.

See also: notes under rt_mbx_init() and rt_typed_mbx_init().

References rt_mbx_delete(), rt_register(), and rt_typed_mbx_init().

◆ rt_mbx_delete()

RTAI_SYSCALL_MODE int rt_mbx_delete ( MBX * mbx )

Deletes a mailbox.

rt_mbx_delete removes a mailbox previously created with rt_mbx_init().

Parameters

mbx	is the pointer to the structure used in the corresponding call to rt_mbx_init.

Returns

0 is returned on success. On failure, a negative value is returned as described below:

EINVAL: mbx points to an invalid mailbox.
EFAULT: mailbox data were found in an invalid state.

Referenced by _rt_typed_named_mbx_init(), and rt_named_mbx_delete().

◆ rt_mbx_init()

int rt_mbx_init	(	MBX *	mbx,
		int	size
	)

Initializes a mailbox.

rt_mbx_init initializes a mailbox of size size. mbx must point to a user allocated MBX structure. Using mailboxes is a flexible method for inter task communications. Tasks are allowed to send arbitrarily sized messages by using any mailbox buffer size. There is even no need to use a buffer sized at least as the largest message you envisage, even if efficiency is likely to suffer from such a decision. However if you expect a message larger than the average message size very rarely you can use a smaller buffer without much loss of efficiency. In such a way you can set up your own mailbox usage protocol, e.g. using fix sized messages with a buffer that is an integer multiple of such a size guarantees maximum efficiency by having each message sent/received atomically to/from the mailbox. Multiple senders and receivers are allowed and each will get the service it requires in turn, according to its priority. Thus mailboxes provide a flexible mechanism to allow you to freely implement your own policy.

rt_mbx_init is equivalent to rt_typed_mbx_init(mbx, size, PRIO_Q).

Parameters

mbx	is a pointer to a user allocated mailbox structure.
size	corresponds to the size of the mailbox.

Returns

On success 0 is returned. On failure, a special value is returned as indicated below:

ENOMEM: Space could not be allocated for the mailbox buffer.

See also: notes under rt_typed_mbx_init().

References rt_typed_mbx_init().

◆ rt_named_mbx_delete()

RTAI_SYSCALL_MODE int rt_named_mbx_delete ( MBX * mbx )

Deletes a named mailbox.

rt_named_mbx_delete removes a mailbox previously created with _rt_typed_named_mbx_init().

Parameters

mbx	is the pointer to the structure returned by a corresponding call to _rt_typed_named_mbx_init.

As it is done by all the named allocation functions delete calls have just the effect of decrementing a usage count till the last is done, as that is the one that really frees the object.

Returns

On success, an integer >=0 is returned. On failure, a negative value is returned as described below:

EFAULT: deletion of mailbox failed.

◆ rt_typed_mbx_init()

RTAI_SYSCALL_MODE int rt_typed_mbx_init	(	MBX *	mbx,
		int	size,
		int	type
	)

Initializes a fully typed mailbox queueing tasks according to the specified type.

rt_typed_mbx_init initializes a mailbox of size size. mbx must point to a user allocated MBX structure. Tasks are queued in FIFO order (FIFO_Q), priority order (PRIO_Q) or resource order (RES_Q).

Parameters

mbx	is a pointer to a user allocated mailbox structure.
size	corresponds to the size of the mailbox.
type	corresponds to the queueing policy: FIFO_Q, PRIO_Q or RES_Q.

Returns

On success 0 is returned. On failure, a special value is returned as indicated below:

ENOMEM: Space could not be allocated for the mailbox buffer.

Files

Functions

Detailed Description

Function Documentation

◆ _rt_mbx_evdrp()

◆ _rt_mbx_ovrwr_send()

◆ _rt_mbx_receive()

◆ _rt_mbx_receive_if()

◆ _rt_mbx_receive_timed()

◆ _rt_mbx_receive_until()

◆ _rt_mbx_receive_wp()

◆ _rt_mbx_send()

◆ _rt_mbx_send_if()

◆ _rt_mbx_send_timed()

◆ _rt_mbx_send_until()

◆ _rt_mbx_send_wp()

◆ _rt_typed_named_mbx_init()

◆ rt_mbx_delete()

◆ rt_mbx_init()

◆ rt_named_mbx_delete()

◆ rt_typed_mbx_init()