appCORE - coreMsgDispatch()

NAME

coreMsgDispatch() -- dispatch, or send, a message to a thread.

SYNOPSIS

include "appcore.h"

int coreMsgDispatch( corehTHR_t h, coreMsg_t* m )

DESCRIPTION

The coreMsgDispatch() function sends, or dispatches, a standard appCORE message to the designated thread. The message must have been created via a call to either coreMsgCreate() or coreMsgDup(). Thread input messages can not be dispatched, they can only be forwarded via the function coreMsgForward().

After the function returns, the message must not be accessed as it is now owned by the destination thread. It is good practice to null the message pointer when this function returns.

If the function fails for any reason, the caller should free the input msg via a call to coreMsgFree() to avoid a resource leak.

PARAMETERS

h	
    Target thread handle.
m
    Pointer to a message.

RETURN VALUE

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

errno Value	Condition
EINVAL	Thread handle is invalid or input message is null.
ECANCELED	Trying to dispatch an input message.
EIDRM	Stale thread handle - destination thread not found.
ENOMEM	Insufficient memory for operation.

MULTI-THREAD SAFETY LEVEL

MT-safe.