User guide

Neuron C Programmer’s Guide 143
• Two application input buffers
See Chapter
8, Memory Management , on page 173, for a discussion of buffer
allocation. For most efficient response, set the number of application input
buffers to equal the expected number of responses. If a disproportionately large
number of responses (for example, more than 10) are expected for the same
request, some responses might never be received if only a limited number of
application input buffers are available.
Notes:
• Because of limited memory on the Neuron 3120 Chip and the Neuron
3120E1 Chip, if your program is linked for these chips, the linker adjusts
the output buffer defaults to one priority and one nonpriority buffer. The
number of input buffers still defaults to 2.
• The same pool of buffers is used for processing both incoming messages
and responses. If you are processing events directly (that is, bypassing
the services of the scheduler), be sure to check for messages as well as
responses so that messages are processed and application buffers are
freed up regularly.
Allocating Application Buffers
Normally, when an application builds a message, an application output buffer is
allocated automatically by the Neuron firmware, and when the application leaves
the critical section, any outstanding application output buffer is freed by the
firmware automatically.
The following functions allow you to allocate and free application buffers
explicitly:
boolean msg_alloc (void);
boolean msg_alloc_priority (void);
void msg_free (void);
A message travels along one of two paths: the priority path or the nonpriority
path. As its name suggests, the priority path has precedence over the nonpriority
path. Thus, if you allocate an application output buffer out of the priority buffer
pool, the message is more likely to succeed on a congested network.
The msg_alloc( ) and msg_alloc_priority( ) functions return TRUE if a msg_out
object can be allocated. Otherwise, these functions return FALSE. A program
needs to call one of these functions if it does not want to wait for an application
output buffer. If the function returns FALSE, the program can choose to do
something else, then try again later.
The msg_alloc_priority( ) function allocates a priority application output buffer.
The msg_alloc( ) function allocates a nonpriority application output buffer. If you
are using the system default, up to two buffers of each type can be in use at the
same time. You can allocate up to the maximum number of buffers set by the
#pragma app_buf_out_count and #pragma app_buf_out_priority_count directives.
See Chapter
8, Memory Management , on page 173, and also the Neuron C
Reference Guide
for more information on these directives.
The msg_free( ) function frees the msg_in object. You do not normally need to
free an application input buffer, because this is done for you when you exit a