Echelon Neuron C - Manual (Page 156)

144 How Devices Communicate Using Application Messages
task. However, you might want to free an application input buffer explicitly if
you are finished with it in a task, but you have more work to do before exiting the
task.
Normally, you allocate an application output buffer by assigning a value to one of
the fields of the msg_out object. In the event that an application buffer is not
available, application processing is suspended (preemption mode) until one is
available. If you want to avoid possibly suspending processing, use the
msg_alloc( ) function. If no application output buffer is available, a FALSE value
is returned, and processing continues. This allows the application to do
something else if there are no outgoing application buffers available, rather than
stopping to wait for an application buffer.
An application input buffer is normally freed at the end of the critical section in
which the msg_receive( ) call is made. The application can choose to free the
application buffer directly by calling msg_free( ). After this call, the msg_in
object no longer contains the received message, but the network processor is able
to use the freed application input buffer for another incoming message. The
msg_alloc( ) and msg_free( ) functions are unlike standard memory allocation
functions. An application output buffer allocated by the msg_alloc( ) function is
not freed by a matching call to the msg_free( ) function. Instead, a msg_send( ) or
msg_cancel( ) call automatically frees an output buffer allocated by msg_alloc( ),
and a msg_free( ) call automatically frees an input buffer allocated by
msg_receive( ).
The analogous functions for allocating and freeing responses are:
boolean resp_alloc (void);
void resp_free (void);
The following example shows a task that creates two messages. Before creating
and sending each message, the code checks buffer availability with msg_alloc( ).
msg_tag motor1;
msg_tag motor2;
#define MOTOR_ON 0
when (x == 2)
{
if(msg_alloc() == FALSE)
return;
msg_out.tag = motor1;
msg_out.code = MOTOR_ON;
msg_send();
if(msg_alloc() == FALSE)
return;
msg_out.tag = motor2;
msg_out.code = MOTOR_ON;
msg_send();
}