Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

gm_provide_receive_buffer.c File Reference

#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)

Detailed Description

This file contains the GM API function gm_provide_receive_buffer_with_tag().


Function Documentation

GM_ENTRY_POINT void gm_provide_receive_buffer_with_tag gm_port_t *    p,
void *    ptr,
unsigned    size,
unsigned    priority,
unsigned int    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.

Parameters:
p  (IN) The GM port.
ptr  (IN) The address of the message communicated.
size  (IN) The size of the message.
priority  (IN) The priority of the message.
tag  (OUT) The tag for a receive event queue.
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)


Generated on Mon Nov 3 15:39:26 2003 for GM by doxygen1.2.15