appCORE - coreMsgForward()

NAME

coreMsgForward() -- forward a message to a thread.

SYNOPSIS

include "appcore.h"

int coreMsgForward( corehTHR_t h, coreMsg_t* m )

DESCRIPTION

The coreMsgForward() function marks the message to be forwarded to the target thread. The forwarding happens when the user's message handler function unwinds. Normally, appCORE frees the input message when the user's message handler function unwinds. However, if the message is being forwarded, appCORE dispatches the message to the destination thread instead. In this way, it is not possible for two threads to access a message simultaneously. This function can be called from any message handler to forward a message to any thread. The message must be an input message to the current thread. The message is not copied, thus the forward operation is a very efficient operation.

PARAMETERS

h
	Target thread handle.
m
	Pointer to message.

RETURN VALUE

If successful, coreMsgForward() returns 0. On failure it returns a value of -1 and sets errno to one of the following values.

errno Value	Condition
EINVAL	Invalid argument.
EIDRM	Identifier removed - invalid thread handle.
ENOMEM	Insufficient memory for operation.

MULTI-THREAD SAFETY LEVEL

MT-safe.