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.
Last updated 02/16/06