#include "gm_debug.h"
#include "gm_debug_recv_tokens.h"
#include "gm_internal.h"
#include "gm_send_queue.h"
Functions | |
GM_ENTRY_POINT void | gm_provide_receive_buffer_with_tag (gm_port_t *p, void *ptr, unsigned size, unsigned priority, unsigned int tag) |
This file contains the GM API function gm_provide_receive_buffer_with_tag().
|
gm_provide_receive_buffer_with_tag() provides GM with a buffer into which it can receive messages with matching size and priority fields. It is the client software's responsibility to provide buffers of each size and priority that might be received; not doing so can cause program deadlock, which will eventually result in a port being closed after a timeout. This timeout is a function of the number of packets sent. The client software may provide up to gm_num_receive_tokens() different receive buffers into which messages may be received. Each buffer provided by the client software to GM via this function will be used only once to receive a message. In other words, calling gm_provide_receive_buffer_with_tag(port,buffer,size,priority,tag) provides GM a token to receive a single message of size size and priority priority into the receive buffer buffer. When a message is eventually received into this buffer, gm_receive(port) stores the buffer pointer buffer and tag in the returned event, returning control of the buffer (token) to the client software. If the client software wishes for the buffer to be reused for a similar receive, it must call gm_provide_receive_buffer_with_tag() again with the same or similar parameters. Once a buffer has been provided to GM, its content should not be changed until control of the buffer has been returned to the client software via gm_receive(). The tag parameter must be in the range [0,255], and is returned in the receive event describing a receive into a buffer. It may be used in any way the client desires, and need not be unique.
|