cnet Frequently Asked Questions
This page contains a number of Frequently Asked/Answered Questions (FAQs)
about the cnet network protocol simulator.
The questions here have been collated from students' actual questions
over recent years.
Please read this page first to ensure that you fully understand
what is happening and then be able to anticipate any errors that
you may confront.
Please email
[email protected]
if you find any errors here,
or think that some additional material should be added.
Getting started
Identity
Developing protocols
Managing time and periodic activity
Hidden meanings
Getting some real protocol simulation done
How can I get started with cnet?
There are many on-line WWW pages to help you to get
started with cnet. Allow about two hours to read each of these
links and this FAQ:
Firstly, read the cnet specific header file
(typically installed at /usr/local/lib/cnet/cnet.h).
All cnet programs must include the line
#include <cnet.h>
to include the contents of this file.
In particular,
it is important that you understand the CnetNodeinfo
and CnetLinkinfo structures,
the CnetEvent and CnetError enumerated types
and the protoypes of commonly used functions.
These are all described in much greater detail in another set of web-pages:
Where can I get cnet for Windows?
cnet does not currently run under Windows,
and there are no current plans to port cnet to Windows.
All of cnet's source code is released
under licence - creativecommons.org/licenses/by-nc-sa/4.0/
Good luck.
How can I compile my cnet protocol source files?
You do not need to compile your protocol files yourself.
Simply executing
shell> cnet TOPOLOGY
will cause cnet to locate and compile your
C source files and produce a shared object file in your working directory
(e.g. protocol.cnet).
This shared object is then dynamically linked with
the cnet simulator at run-time.
The system's standard C compiler,
typically clang or gcc, is used.
All C error messages are reported by the compiler (not cnet).
All fatal and warning messages should be eliminated before your protocol
code can be considered syntactically correct.
You will probably receive many more error
messages than you've experienced before - the reason being that
the compiler is invoked with extra compilation switches to be very
pedantic (this is good for your soul and in fact is how you should
always compile C code).
If you are concerned about any "black magic" destroying your code,
observe what happens by invoking cnet as:
shell> cnet -d TOPOLOGY
How can my protocols access external functions?
Protocols written in cnet may access external functions,
such as functions in the Mathematics library.
For example, to access the old UNIX sqrt function,
we first need to add function prototypes to our protocols -
this is usually involves including a header file in our C code:
#include <math.h>
and then indicating in our topology file
that we need to link against an external library, with (for example):
compile = "protocol.c -lm"
The embedded switches -l and -L,
and any filenames ending in .o or .a,
are recognized as (assumed to be) arguments for the linker.
All other switches are assumed to be C-preprocessor and C-compiler switches.
NOTE: By default, cnet's header file
includes the header file <math.h>,
and links against the standard C mathematics library by appending -lm.
Why does cnet terminate after 5 minutes?
Errors in your protocols which prevent an event handler from returning
when expected, prevent the cnet scheduler from performing correctly.
In particular,
the scheduler cannot service events from the windowing
system - for example your requests to kill cnet itself when you detect
a problem.
To overcome this major problem, cnet itself times-out after
5 minutes just in case you have written incorrect protocols which have
become 'stuck'.
Once you are confident that your protocols are working
as expected you can easily extend this 5 minute period with, for example,
cnet -m 10 TOPOLOGY
where the command line option requests execution for
the required number of minutes.
How can I develop my cnet protocols in multiple files?
As cnet projects become larger,
it's naturally wise to develop protocols in a number of different source files.
A natural method to partition the files is based on their responsibilities.
C (and of course many other programming languages) allow you to place
relatively independent sections of source code in separate files,
compile each source file individually, and to then link the resulting
object files to form a single executable file.
cnet also allows you to do this, but simplifies the activity. In your
topology file, replace a line such as
compile = "protocol.c"
with
compile = "dll.c nl.c routing.c queueing.c fragments.c"
(or whatever) and cnet will quietly compile and link all of the pieces.
Only one of the C source files needs to have a reboot_node() function.
cnet handles the compilation and linking quite happily,
unless it is interrupted.
If individual files appear to be not being compiled,
just remove all object files with
rm *.o and re-run cnet.
If you're interested in what's going on, invoke cnet with its
-v
switch to see the executed compilation and linking commands.
How many nodes are there in my simulation?
By default, cnet does not reveal the total
number of nodes in the simulation.
This encourages the development of protocols which
make no assumptions about the size of the network.
By setting the
-N command line option,
the number of nodes in the simulation is available in the
global integer variable NNODES.
Without -N, the value of NNODES is zero.
How many links does my node have?
The number of physical links connecting a node
(i.e. those of type LT_WAN, LT_LAN, or LT_WLAN),
is always available in the
global integer variable nodeinfo.nlinks.
Links are numbered within each node
from 0 to nodeinfo.nlinks.
Link number 0 is always the node's LOOPBACK link,
which simply delivers anything transmitted to it straight back to the same node.
The first physical link is number 1,
and every node will have a link number 1.
Each node's link attributes may be accessed, at runtime,
via elements of the C structure variables
linkinfo[0],
linkinfo[1],
linkinfo[2], and so on.
When allocating an array of structures,
and then iterating across all physical links indexed by their link number,
you'll require code similar to:
linkthings = calloc(nodeinfo.nlinks+1, sizeof(LINKTHING));
....
for(link=1 ; link<=nodeinfo.nlinks ; ++link)
linkthings[link].field = ....
What is the difference between a node's number and its node address?
Nodes have both a number and an address -
node numbers (available in nodeinfo.nodenumber)
range from 0,1,2,.....NNODES-1,
whereas each node's address (available in nodeinfo.address)
can be any unique non-negative value.
By default
node numbers and node addresses are the same (0,1,2,....).
Setting a node address attribute in the topology file,
as with
host Perth {
address = 351
....
}
should reveal a problem if your protocols are assuming that
node numbers and node addresses are always the same.
In particular,
the destination node addresses provided by
CNET_read_application
and expected by
CNET_write_direct
are node addresses and not node numbers.
What is link zero ever used for?
Links are numbered within each node
from 0 to nodeinfo.nlinks.
Link number 0 is always the node's LOOPBACK link,
which simply delivers anything transmitted to it straight back to the same node.
The LOOPBACK link may be used when developing and debugging
protocols. A node may construct, "transmit", and instrument data to itself,
to debug and test code receiving erroneous data,
without sending that data across the physical layer.
What if an event occurs while I'm currently handling an event?
cnet does not employ pre-emptive scheduling - once an event
handling function is being executed,
it will not be interrupted by the arrival of another event.
Event-handling functions must execute to their completion in a timely
manner - they must perform their actions and then simply return.
Only then, will other pending events be delivered to their event handlers.
This style of event-driven programming makes protocol development much
easier. Your code does not need to manage interrupts or semaphores,
or employ critical regions.
Why does my simulation, and the whole GUI, appear to hang?
If one of your event handlers becomes stuck in an unbounded loop,
or does not return,
the whole simulation and its GUI will appear to hang.
The flow of execution must return to cnet's scheduler,
in a timely manner,
so that any interaction with the GUI is received and further cnet
events are raised.
Your process is probably still executing,
but one of your protocol's event handlers is performing all activity.
You will need to terminate cnet from the command-line
(probably with Control-C).
Then, re-run the simulation with cnet's
trace window displayed.
This will provide an annotation of each node's event handlers
and the cnet API's invoked while your event handlers are executing.
How can I debug my cnet programs?
Because many things appear to be happening simultaneously in cnet,
debugging cnet protocols can be difficult.
However, it is far easier than debugging protocols on different computers
in different geographic locations!
Although cnet permits protocols to be written in C and
executed natively in a single operating system process,
it does not provide traditional debugging support.
Moreover (unfortunately) because of the way cnet manipulates the
single process's data segments to transparently schedule nodes,
standard debuggers, such as gdb,
can't "keep up" with what is happening and begin reporting incorrect
information.
Most importantly, most cnet functions return an integer indicating
their success or failure (0 for success, -1 for failure).
IT IS ESSENTIAL
that you examine the function's return value to ensure that
it performed as expected. If you ignore this return value your
protocols may fail at a much later stage in their execution and it will
be extremely difficult to track down your error. If a function detects
an error (and returns -1) it will also set the node-specific variable
cnet_errno
to reflect what went wrong.
The most recent error detected
by cnet may then be printed from each node (to stderr)
with the function
CNET_perror
or you may construct your own error messages
using the error descriptions in
*cnet_errname[] or
*cnet_errstr[].
It is also helpful to trace your protocols to see the exact ordering
and arguments of cnet function calls.
Tracing may be selected with the
-t command line option,
setting the trace node attribute to true for
all or individual nodes in the topology file or by selecting the trace
checkbox on either the default or specific node panels under
the windowing system.
Tracing will appear on the trace stream of cnet
(either the separate trace window or the shell's tty)
and shows each node's event handling
functions being invoked (and returned from) and, within each handler,
all function calls, their arguments and the function return values.
Any function arguments that are modified by the functions (arguments passed
by reference) are also shown after the function return values.
If any errors are detected by the functions themselves, these will be
reported within the trace.
See Tracing cnet's execution.
Where did my code's output go?
All output implicitly sent to C's standard output stream
with calls to printf() or puts(),
appears on each node's output window.
Clicking a node's icon on the simulation map will reveal this window,
and you can scroll back through a limited number of previous lines.
Each node's output printed via printf() or puts()
can also be copied to an individual file using the
-o option to cnet.
For example, if running a two node network with
shell> cnet -o debug TOPOLOGY
all output will be copied (typically) to the files debug.node0
and debug.node1.
All output explicitly sent to the stdout or stderr streams,
requested with calls to fprintf() or fputs(),
appears on the invoking terminal/shell window (tty or pty).
Such output (merged output from all nodes)
can be captured using traditional output redirection in your shell.
Are there any simple tricks that can help my understanding?
Many people get confused with cnet's apparent ability to manage
multiple nodes simultaneously within a single process
(which is, in fact, one of its unique features).
In addition,
it can be initially confusing to understand how a single protocol can
act as both a sender and receiver simultaneously.
A simple trick to ease this confusion is
to only allow one node to transmit and the other to receive
(in a network of just 2 nodes).
As nodes have nodenumbers of 0, 1, 2, ... adding the lines
if(nodeinfo.nodenumber == 0)
(void)CNET_enable_application(ALLNODES);
to your handler for EV_REBOOT,
typically reboot_node(),
will only permit node #0 to generate messages for delivery.
What is the EVENT_HANDLER function that appears in most examples?
EVENT_HANDLER is actually not a function provided by
cnet (or your operating system) but a C macro
defined in the <cnet.h> header file.
Its full definition is:
#define EVENT_HANDLER(name) \
void name(CnetEvent ev, CnetTimerID timer, CnetData data)
This provides greater readability in protocol code,
which can simply declare its event handling functions with, for example:
EVENT_HANDLER(timeouts)
{
....
}
Use of EVENT_HANDLER does, however, introduce some potential confusion.
As an consequence of being declared with EVENT_HANDLER,
each such function "automatically" has three formal parameters:
ev, timer and data.
While this improves both readability and consistency,
it may introduce confusion as to where the parameters actually "come from".
What is the CHECK function that appears in most examples?
CHECK is actually not a function provided by
cnet (or your operating system) but a C macro
defined in the <cnet.h> header file.
Most of cnet's library (builtin) functions return
0 on success and something else,
typically -1, on failure.
In fact, if any of these
functions fail, it probably indicates a serious error in a protocol
(there are a few exceptions to this generalization, such as cancelling a
timer that has already expired).
Moreover, all functions will set the global error variable
cnet_errno
on failure and this may be used as an index into the globally accessible
array of error strings,
cnet_errstr.
This is similar to the use of
errno and sys_errlist in C.
By enveloping most calls to cnet's
library routines with CHECK,
we can get an accurate and immediate report on the location
(source file, function name, line number, and nodename) and type of each error.
These values are passed to cnet's function CNET_exit
which, if able, pops up a window highlighting the exact location of
the runtime error.
Looking at the definition of CHECK in <cnet.h>
may expose the "black magic":
#define CHECK(call) do{ if(call) != 0) \
CNET_exit(__FILE__, __func__, __LINE__);} while(false)
CHECK may not strictly belong in cnet's header file,
but it's such a useful macro, it saves everyone from re-inventing the wheel.
How can I determine the current time?
Do not attempt to use your operating system's
time() or gettimeofday() functions.
In cnet each node's "system-time" is provided in
the global integer variable nodeinfo.time_in_usec,
which measures the time, in microseconds, since the node was last rebooted.
This value will (usually) have increased between calls to event
handlers, but its value will not change during the execution of an
event handler.
The current time of day, i.e. the "wall clock time" of each node,
is available via the structure nodeinfo.time_of_day, i.e. in
nodeinfo.time_of_day.sec and nodeinfo.time_of_day.usec.
The integer value in nodeinfo.time_of_day.sec
represents the number of seconds elapsed since 00:00:00 on January 1, 1970,
and can thus be used as an argument to standard operating system
functions such as ctime().
Unless cnet is invoked with the
-c option,
the wall clock time of all nodes is initially different on each node.
If -c is specified,
the clocks in all nodes will initially be synchronized.
Protocols may be developed, which call
CNET_set_time_of_day
to synchronize the clocks.
cnet provides no support for timezones or daylight saving.
How can I print a CnetTime value?
All times in cnet are measured in microseconds,
and the datatype CnetTime is a 64-bit integer - long enough to
hold about 580,000 years of simulation.
To print a value of CnetTime, we have two choices:
include the header file <inttypes.h>
and format with:
printf("time taken %" PRIi64 "usecs\n", taken);
What are timers and CnetTimerIDs?
The event-driven nature of cnet means that your protocols cannot simply
'wait' for something to happen. The cnet scheduler will inform your
protocols when important things need doing (messages to deliver, frames
to receive, etc).
In particular, your protocols cannot simply wait a
nominated period of time and then do something appropriate after that
time.
YOUR PROTOCOLS SHOULD NOT CALL sleep()
or any similar functions.
Instead, cnet provides timers so that the scheduler may inform your
protocol when a nominated period of time has elapsed.
You may have an almost unlimited number timers quietly "ticking away" -
they are each uniquely identified by a CnetTimerID.
When you create a new timer you must indicate one of 10 timer events
EV_TIMER0..EV_TIMER9
and a period of time (in microseconds) in the future.
The function
CNET_start_timer
will return to you a CnetTimerID
so that you may keep track of which timer has expired
when your timer event handler is invoked.
For example:
CnetTimerID saved_timer;
saved_timer = CNET_start_timer(EV_TIMER1, (CnetTime)1000000, 0);
will cause the event handler for EV_TIMER1 to be called in 1 second.
The value of saved_timer will be passed as the second parameter to the
handler so that you can see which timer expired. You can have as many
outstanding timers on the EV_TIMER1 queue as you want.
PLEASE NOTE: there are not only 10 timers available -
however, each timer must be tagged with one of the 10 available timer events.
If you decide that you no longer want to be informed when a timer
expires, you should call
CNET_stop_timer
with the CnetTimerID in which you are no longer interested.
For example,
(void)CNET_stop_timer(saved_timer);
If the cnet scheduler invokes your timer handler,
then you do not need to cancel the corresponding timer
(it will be done for you).
However, if you wish a timer event to be raised periodically,
then you'll need to start a new timer in the handler of an
expiring timer,
i.e. timers only expire once, not repeatedly.
Why does cnet only provide 10 timers?
cnet provide 10 distinct timer queues -
not just 10 timers.
Each timer queue may have an unlimited number of timers "ticking-away" on it
and,
when each expires,
the event handler for the associated queue will be invoked.
When writing protocols in multiple layers,
it's a nice separation of concerns to employ different timers in each layer.
For example, in a Data Link Layer protocol,
we could use EV_TIMER1 for a frame retransmission timer,
and EV_TIMER2 for a piggyback timer.
At the same time, the Network layer may use EV_TIMER3 to flush any
queued packets if it uses a leaky bucket for congestion control,
and EV_TIMER4 to periodically exchange routing table
information with neighbours.
Employing a distinct timer queue for each activity allows us to use
a separate handler to manage the requirements of each activity,
and to "hide" the handler in the protocol layer or source file of concern.
What is the third parameter to CNET_start_timer ever used for?
Any value passed as
the third parameter to CNET_start_timer is remembered,
internally, along with the timer.
When the timer expires, this saved value is passed as the third parameter
to the handler for the timer's event.
This parameter is of type CnetData (a long integer in C)
which allows it to store integral values or a pointer to a variable or
dynamically allocated data structure.
Typical uses for this parameter are to pass a sequence number used in a
protocol,
or perhaps a pointer to a list or tree structure,
to the timer event's handler.
If the parameter is used to store a pointer,
care must be taken to ensure that the pointer is still valid at the time
the timer's event handler is called.
In particular,
the parameter should never be used to store the address of any variable or
structure on C's runtime stack.
It is reasonable to pass a pointer to dynamically allocated storage
to CNET_start_timer (i.e. allocated with malloc),
and then have the timer's event handler deallocate this storage
(i.e. deallocated with free).
If you need to call CNET_stop_timer before a timer expires,
take care to first deallocate any dynamic storage associated with the timer
as a CnetData value.
You can "recover" the CnetData value
by calling the function CNET_timer_data.
Can I add my own CnetEvent events?
No, not unless you wish to change and recompile the source code of cnet
itself.
However, there are a few "spare" standard EV_TIMER events that
could be re-used or "renamed" to suit your purpose.
For example,
if you'd like a new event for the Data Link Layer to signal the Network
Layer, you could (ab)use the C-preprocessor and say:
#define EV_DLL_2_NL EV_TIMER8
#define raise_dll_2_nl_event(data) CNET_start_timer(EV_DLL_2_NL, 1, data)
and then simply call raise_dll_2_nl_event()
with an instance of CnetData when you want to raise the pseudo-event.
What is the meaning of "spelling mistake on line 83 of protocol.c"?
There is a spelling mistake on line 83 of protocol.c
What is the meaning of "caught signal number XX while (last) handling Perth.EV_APPLICATIONREADY"?
Old tricks for young players.
Fatal error messages of this form generally indicate a major problem
with your protocols.
The number (typically 2, 10 or 11) refers to an
operating system signal number intercepted by cnet
(see /usr/include/signal.h).
For example,
signal number 2 will be caught and reported by cnet if you
interrupt cnet from the shell level
(signal 2 = SIGINT).
The other common signals,
10 and 11, reveal significant flaws in the implementation of your protocols.
Signal 10 (SIGBUS, a bus error)
occurs when the CPU attempts to execute
an instruction not on an instruction boundary
(on many architectures,
you've requested to execute an instruction whose address is not a
multiple of 4).
This error will generally occur when your programming
corrupts your program's stack and,
in particular, you corrupt the
return address of the currently executing function.
When the current
function attempts to return (to a now incorrect address) and then fetches
an instruction whose address is invalid, signal 10 will result.
Signal 11 (SIGSEGV, segmentation violation)
occurs when your program
attempts to address memory that has not been mapped into your address
space. Typically, by accessing a pointer that has not been correctly
initialized or has been modified/overwritten incorrectly, that pointer
will point to memory that you do not "own",
it being owned by either
the operating system or another (person's) process.
When attempting to
access outside of your memory segment, you will get a segmentation
violation.
Operating systems that do not provide memory protection
(segmentation), for example DOS, will not report this error as the
(single) process on those operating systems "own" all of the address
space. Your program there will still (maybe!) exhibit errors but these
may not be reported to you.
The operating system is in fact doing you a favour.
Signals 10 and 11 spell disaster for your programs - there is obviously
something seriously wrong with your program if they happen. Both forms
of error most frequently occur when you are incorrectly managing
pointers and/or dynamic memory.
Such problems are very difficult to diagnose - your first action should
be to check your programming logic. By their nature, errors which
often *cause* signals 10 and 11 to be reported, do not necessarily
raise the signal immediately. You may do the wrong thing many
instructions or even seconds before the signal is reported. For this
reason, the best cnet can do is state which event handler it was
executing (or it was most recently executing) when the signal occurs.
This does not necessarily indicate that your programming error is in
that event handler though experience shows that this is likely.
What is the meaning of "warning: no more events are scheduled"?
This message means that cnet has nothing more to do (for your
simulation) -
all Application Layers are disabled and so no new messages will be generated,
all frames have been delivered (or have been lost) via the Physical Layer, and
all timers have expired or been cancelled.
cnet has nothing further to do until
you click a debug button,
provide some keyboard input to one of the nodes, or
terminate cnet.
What is the meaning of the statistic "Efficiency (bytes AL) / (bytes PL)"?
Here, AL stands for Application Layer, and PL for Physical Layer.
This statistic divides the total number of bytes generated by all
Application Layers, by the total number of bytes traversing the Physical Layer.
Our protocols will require headers for their frames and packets,
re-transmit data frames,
and generate acknowledgments and other control packets,
and so this ratio is expected to be less than 100%
(the price we pay for reliable message delivery).
The statistic is not updated until the first message is successfully
written "up" to a node's Application Layer.
Under some circumstances this statistic appears to be inaccurate,
and may not correspond exactly with your own calculations.
This occurs when some bytes still "remain" in the Physical Layer
and have yet to be delivered.
Also, if your protocols perform compression of their payloads,
then it is possible for this statistic to exceed 100%.
Keep in mind that this ratio is not the only desirable measure of
protocol efficiency (but retains this name for historical reasons).
Protocols may also strive to minimize average delivery time,
or the total (monetary) cost of delivering frames.
What is the meaning of the error
"ER_NOTREADY - Function called when service not available"?
This error arises in two common circumstances,
usually when using functions to communicate with the Application or
Physical layers:
-
When a node is rebooting
(its EV_REBOOT event handler is executing)
data frames may not be written to the Physical Layer -
it too needs to be rebooted before it can accept data.
To overcome this limitation, set a timer for a very short interval,
say just 1usec,
and write to the Physical Layer in the timer's handler.
-
cnet employs an event-driven paradigm to inform your protocol
code that the Application and Physical layers require your attention.
You may not poll either layer to see if new messages or data frames
are available.
-
Attempts to call CNET_read_application when not executing
an EV_APPLICATIONREADY handler, or
attempts to call CNET_read_physical when not executing
an EV_PHYSICALREADY handler,
will result in the functions failing and setting cnet_errno to
ER_NOTREADY.
What is the meaning of the error
"ER_TOOBUSY - Function is too busy/congested to handle request"?
The function CNET_write_physical() will 'trap' the situation
when a large number of frames have been written to the Physical Layer,
and when the receiving node has not read any of them off.
This trap is currently set at the large value of 1000,
which surely indicates an error in a protocol.
Your protocol may have some unbounded loop,
or a very short timeout-and-retransmission sequence,
resulting in many calls to CNET_write_physical() at the sender,
before any EV_PHYSICALREADY events are handled at the receiver.
How can I speed up my simulations?
Firstly, it's important to keep some perspective.
cnet runs within a single process on a single processor.
If you dramatically increase the number of simulated nodes,
expect a corresponding decrease in simulation speed.
Even though the nodes appear to execute at the same time,
their execution shares the single processor.
However, all is not lost:
- Don't print out volumes of debug information to each node's output
window. The printing of large amounts of text and the scrolling of these
windows obviously slows down cnet.
Just print out bad news, not lots of good news.
- Disable all printing, altogether -
invoke cnet with the
-q option
to keep the windows quiet.
- cnet simulates multiple, independent, nodes by swapping their
data segments (their variables) in and out of memory
before each node's event handler is called.
You can speed up your simulation (considerably) by reducing the space
(number of bytes) required for each node's variables.
Instead of declaring, say, a large buffer of 64KB as a global variable,
declare a global pointer to such a buffer (probably requiring only
4 bytes) and in your
reboot_node() handler,
allocate the 64KB with a call to malloc().
Now, each time the node is scheduled, only the 4 byte pointer variable
will be swapped in and out (and data allocated in the heap is not swapped).
-
If your protocol works "for a few minutes" before crashing,
change a few attributes to speed up the cnet simulation.
For example:
messagerate = 3ms
propagationdelay = 100usec
should enable your protocol to work "for a few seconds" before it crashes.
Hmmmm, much better.
- If you'd rather not wait a full second for cnet
to complete one second of network activity, run with the
-T option
to force events to be scheduled
immediately (nodeinfo.time_in_usec is updated as you'd hope).
-
You don't always need to work with cnet's graphical display;
it'll run "within" an ASCII terminal window without its display if you
invoke cnet with its
-W option.
You can also use the
-o option
or explicitly send output to stdout,
stderr or to a file rather than
having it all appear in each node's stdout window.
After a while, the gimmick of the "network map" should wear off
and you should only be debugging bad news,
by examining cnet_errno and CNET_perror().
How can I collate cnet statistics for plotting?
cnet centrally collates statistics on behalf of all
nodes, and displays these on the 'Statistics' popup window or at the
end of a simulation run if cnet is invoked with the
-s option
(or the
-z option
to also get zero-valued statistics).
We can also print statistics more frequently (periodically) with the correct
choice of
command line options.
These are:
| -W |
no need for the windowing interface |
| -T |
run the simulation as fast as possible |
| -e 5m |
execute for 5 minutes of simulation time |
| -s |
yes, we want statistics |
| -f 10s |
print statistics with a frequency (period) of 10 seconds |
This will produce volumes of output to cnet's
standard output stream,
so we need to both capture this and probably filter only what we need.
So, to capture the Efficiency measure (bytes AL/PL) every second
(in the hope that it improves), we issue:
#!/bin/bash
#
cnet -W -T -e 5m -s -f 1s TOPOLOGYFILE | \
grep Efficiency | \
cut -d: -f 2 | \
cat -n > effic.statistics
The last line takes its input (a column of 300 efficiencies) and places a
line number at the beginning of each line.
This is fine if we really want statistics every single second, but slowly
adapting protocols may take several minutes to reach their optimum.
We could develop a shellscript which accepts arguments
indicating the topology file and the frequency of collection:
#!/bin/bash
#
TOPFILE=$1
FREQ=$2
#
cnet -W -T -e 5m -s -f $FREQ $TOPFILE | \
grep Efficiency | \
cut -d: -f 2 | \
awk '{ printf("%d %s\n", n+=freq, $0); }' freq=$FREQ > effic.statistics
Of course,
other shellscript arguments could indicate the required
statistic, resultfile, etc.
How can each node collate its own statistics?
Each node can easily collate statistics about its own performance
in its own variables (in its C protocol source code).
Each node can then use a timer event to periodically report its statistics
(either accumulated values, or instantaneous values that are then cleared
by the timer event handling code).
If the statistics are printed in a consistent format,
to C's stdout stream,
then external shellscripts (as described above) may be written to
further collate or plot information.
A node may set a handler for the EV_SHUTDOWN event,
and then print its statistics when the node is politely shutdown,
or when the whole simulation finishes.
Similarly, a node may set a handler for the EV_PERIODIC event,
and then print its statistics whenever its handfler is called.
The frequency with which the EV_PERIODIC event occurs
may be requested with, for example:
shell> cnet -f 10secs TOPOLOGY
How can I collate my own global statistics?
Normally cnet provides the appearance that all nodes have independent
memories (variables)
so that all inter-node communication must be made via the Physical Layer.
However, this feature can make the collation of global statistics difficult
and, on such occasions, having access to a shared block of memory,
say an array of integers indexed via each node's nodenumber,
would be beneficial.
Consider the need to determine the number of re-transmissions required by
each node executing a certain protocol - not a statistic that cnet
can manage because it doesn't understand your code,
and doesn't know what a re-transmission is.
Let's assume that we have at most 100 nodes.
In each node's EV_REBOOT handler, we call
CNET_shmem
to request a shared memory region to store our re-transmission counts:
#include <cnet.h>
int *retransmissions;
void reboot_node(CnetEvent ev, CnetTimerID timer, CnetData data)
{
.....
retransmissions = (int *)CNET_shmem(100 * sizeof(int));
.....
}
Then, when each node makes a re-transmission we can simply increment the
relevent count in this shared array of integers:
// I have just re-transmitted a DATA frame
++retransmissions[ nodeinfo.nodenumber ];
.....
All other nodes can instantly see the number of re-transmissions made by
all other nodes, and any particular node could, say, print out all values when
its EV_SHUTDOWN handler is called.
The provision of CNET_shmem() is not intended to provide a
covert communication channel between nodes.
|
