UserGuid

Chimera User's Guide

How to write an application using Chimera ?
Before writing an application on Chimera make sure that you read Chimera API section in Chimera Architecture & API document first. In Chimera API we explain basic interface for interacting with Chimera. In the same document we also provide a brief overview of Chimera architecture that helps to get a general overview of the system. We also provide a very basic chat application called test.c in test folder, as a simple example of how to utilize Chimera API.
The only header file that you need to include in your application is "chimera.h". After that the very first step in writing an application for Chimera is initializing the Chimera system by calling chimera_init(int port).The second main step is writing the three up-call functions for forward, deliver, and update Chimera events. As explained in section 2.2 of the Chimera API document, the provided functions will be called every time the associated events occurs in the Chimera system. A simple example for an update function could be:
void test_update(Key *k, ChimeraHost *h, int joined) {
if(joined) {
fprintf(stderr,"Node %s:%s:%d joined neighbor set\n", k->keystr, h->name, h->port);
}
else {
fprintf(stderr,"Node %s:%s:%d leaving neighbor set\n", k->keystr, h->name, h->port);
}
}
In this example every time a node joins or leaves the leaf set a message will be printed to the screen informing the user as event happens.
These up-calls then should be associated to their appropriate events by passing them to the associated message up-calls. e.g: chimera_update(test_update)
An application can utilize Chimera messaging subsystem by defining an integer message type and registering it with chimera_register(int type) function. Be aware that types 1 to 10 are reserved for internal chimera message types. This step is necessary for messaging subsystem to recognize message type, unrecognized message types will be dropped. However this version of Chimera does not provide mechanism for associating a message type with a function in messaging subsystem, users can mimic this functionality in their up-call functions. In another words, users can decide what to do with message by examining the message type in provided up-call functions. To demonstrate this take a look at the following deliver function :
#define TEST_CHAT 15
void chat_deliver(Key *k, Message *m) {
if(m->type == TEST_CHAT) {
fprintf(stderr,"** %s **\n", m->payload);
}
}
In this example every time a message is delivered to the local node, the message type is examined and if the type is TEST_CHAT then the message payload is printed to the screen.
After registering different message types and providing their functionality in up-calls, you can use chimera_join( ChimeraHost *bootstrap) to join the network that host bootstrap belongs to. If bootstrap is NULL then the caller starts the system. At this point you can use chimera_send function to route through routing subsystem.
Other than the test.c that is a very simple application to show how to develop application on top of chimera overlay, we also included one of our test beds. The test main file is "bigtest.c" that can be found under <chimera_folder>/test/. The bigtest uses "bighost.c" which is very similar to test.c chat application. To run bigtest.c first create a set of random keys from "sha1_keygen #num_keys hostname" and save them to a file called hosts. then run bigtest. bigtest calls bighost and create the network and pick a random source from hosts and random destination from key space and route message from source to destination. It also output the logs than can be parsed to create the graph to see the average hop count.
Rama Alebouyeh
Last updated 02/16/06