Sample Applications

What are the test programs?

We've implemented a fairly simple set of test programs which demonstrate the use of the Congestion Manager from userland with UDP programs. The programs use a very simple protocol between the client and server:

• The client opens a UDP socket to the server, and begins sending data. All packets have a packet header containing a sequence number, a timestamp, and an indication of the length of data contained therein. The rest of the packet is "application data". (In the case of the test programs, we simply fill it with a character).
• The server (test_receiver) receives the packet and echos back the packet header, but NOT the data. This functions as an acknowledgement of the reception of the data to the client.
• The client examines all incoming ACKs and updates the congestion manager with the number of bytes received and lost, and the round-trip time.

  * Please note that this simple demonstration does NOT account for packet re-ordering.

What is the organization?

The test programs all link against the test_framework.c file; it contains a simple main() function which sets up the sockets the programs need, and then dispatches into a function called test_run. test_run should be defined in a separate file for each test, named "test_". For instance, the ALF sending test is in test_alf.c.

The test_run function implements the program's event loop. Many of the test programs make use of some convenience functions defined in the test_framework.c file, send_pkt and receive_pkt. Please read the comments in the code for these functions if you're considering using them in your own code - they have some important restrictions of which you should be aware.

How do I run the programs?

First, run the receiver program. We'll assume you're running it on the machine "test1"

   ./test_receiver

This program can run on any Linux or BSD system; it does NOT require the congestion manager.

Then, run any of the example programs. For instance, to send 10 packets to the receiver with the buffered UDP API, run:

  ./test_bufudp -n 10 -d test1

But my program has a different <event loop, style, etc>!

The test programs included herein are intended only to give a flavor for how the Congestion Manager may be used. The CM is compatable with a variety of different program architectures, including those based on select loops, timers, or signals. You'll need to determine the best way to integrate the CM into your programs, of course, but we hope we've provided an easy framework for you to accomplish this.

What do each of the test programs do?

test_alf

test_alf implements an "ALF" - Application Level Framing - style sender. This is an application that wants last-minute control over what packets it sends, so it registers with the Congestion Manager for a callback when it is allowed to send a packet out.

test_alf_noconnect

Built from the same file as test_alf, this is designed to test the overhead involved in requiring the application to call cm_notify, instead of letting the kernel do it automatically.

test_bufudp

test_bufudp uses the buffered UDP sender model. It doesn't care about adapting its data to the client - it just wants to get its data transmitted in a network-friendly manner, without the extra trimmings of TCP. Therefore, it opens a socket, and asks the CM to control the flow of data out of that socket.

test_sync

This test program uses the synchronous transmission API provided by the CM (Section 4.1) to send a stream of data clocked by its own timer. It uses repeated cm_query() calls to adjust its input rate, picking from one of a pre-specified set of rates that are #define'd.

The program registers a cmapp_update() function with the CM, and then waits for the CM library to call cmapp_update(). Upon receiving this callback, it picks a suitable transmission rate and clocks its transmissions. It implements its own event loop so it can receive notifications of successfully received and lost packets from the client.