cnet's Application Layer
The Application Layer
(either the internal default version or one provided with the
-A option)
has the responsibility of generating messages to be delivered to other
Application Layers.
An Application Layer will not generate a message for its own node.
The required destination node is identified by
its network address and not node number.
Each node's address and node number will in fact be the same,
unless the address attribute is specified in the topology file.
When cnet informs your protocols that the Application Layer
has a message for delivery,
your protocols will read the message into a buffer supplied by you.
You must first indicate the maximum message size that you are willing
to receive.
A successful read will then ``fill-in'' the address of the message's
destination node and the actual length of the message.
Your protocols are simply presented with ``a lump of bytes'',
at least 32 bytes long,
which they must deliver to other Application Layers.
The message is to be considered as opaque data,
its contents are immaterial,
though suffice to say that there is sufficient information in the
message for cnet to diagnose most protocol errors for you.
A typical sequence is:
char msgbuffer[ MAX_MESSAGE_SIZE ];
CnetAddr destaddr;
int length;
length = sizeof(msgbuffer);
result = CNET_read_application(&destaddr,msgbuffer,&length);
/* prepare message for transmission ... */
When the message reaches the correct destination node,
it may be written to the Application Layer:
/* ... receive message from another node */
result = CNET_write_application(msgbuffer, &length);
Protocols will typically need to restrict,
or throttle,
the generation of messages for certain destination nodes.
This may be achieved using the functions
CNET_enable_application and
CNET_disable_application which each accept a single parameter
indicating which destination address to throttle.
For example,
if the node whose address is busynode becomes busy or swamped,
we can stop our Application Layer from generating messages for this node with:
result = CNET_disable_application(busynode);
Similarly, we can permit messages to be generated for all nodes (other
than ourselves, of course) with:
result = CNET_enable_application(ALLNODES);
This function would typically be called in each node's
reboot_node() function.
The default Application Layer prefers to generate messages for ``close nodes'',
with a message having twice the chance of being for
an immediate neighbour as for a node two hops away (and so on).
The Application Layer functions
-
int
CNET_read_application(CnetAddr *dest,
char *msg,
int *len);
-
On invocation, len must point to an integer indicating the maximum
number of bytes that may be copied into msg.
On return, len will point to an integer now indicating the number
of bytes copied into msg.
The network address of the required destination node is
copied into destaddr.
-
int
CNET_write_application(char *msg,
int *len);
-
Passes a number of bytes,
pointed to by msg, ``up to'' the Application Layer.
On invocation, len must point to an integer indicating the number
of bytes to be taken from msg.
On return, len will point to an integer now indicating the number
of bytes accepted by the Application Layer.
-
int
CNET_enable_application(CnetAddr destaddr);
-
Permits the Application Layer to generate messages to the node with
the indicated network address.
If the destaddr is the symbolic constant ALLNODES,
message generation to all nodes will be enabled.
Initially,
message generation to all destination nodes is disabled
and must be enabled to begin the generation of messages.
-
int
CNET_disable_application(CnetAddr destaddr);
-
Prevents the Application Layer from generating new messages to the
node with the indicated network address.
If the destaddr is the symbolic constant ALLNODES,
message generation to all nodes will be disabled.
This function should be called when a harried node runs out of
buffer space, or perhaps while routing information is being gathered.
cnet was written and is maintained by Chris McDonald
(chris@cs.uwa.edu.au)