FreePastry is a modular, open source implementation of the Pastry p2p routing
and location substrate.
- "Wire" uses an event-based implementation based on sockets, and uses the non-blocking NIO support in Java 1.4. It uses UDP as transport by default, switching dynamically to TCP for large messages or in the event that a stream of traffic is sent to a given node. The wire protocol is till in beta testing, in part because the implementations of the Java NIO do not yet work properly and efficiently in several Java VMs on some platforms (for instance, Sun's JDK 1.4.1 RC1 and earlier on Windows platforms).
Support for simulated killing of nodes is for testing purposes only. There is a potential to lose any messages that are queued to be sent when you simulate killing a node. Any such dropped messages will print the error:
Potentially lost the message: [message.toString()]
There is a known issue in the BSD (FreeBSD, OS X) implementations of Java NIO that bubbles up the error: "IOException: Bad file descriptor", whenever a node simulates being killed. We catch the error and print the message to the command line. Simulated killing of nodes causes instability in some JVMs prior to JRE 1.4.2.
On Unix systems, Java's socket implementation uses File Descriptors. In this implementation, the File Descriptors can be used up if too many nodes are running in a single process. If you require running more than one node inside a single process, consider increasing the number of File Descriptors per process (bash: ulimit -n), or lowering the available sockets per node (rice.pastry.wire.SocketManager.MAX_OPEN_SOCKETS).
Future transport protocols will also be based on an open standard to ensure interoperability among different implementations.
(Background: To start a Pastry node, the IP address (and port number, unless the default port is used) of a "bootstrap" or "contact" node must be provided. If no such node is provided, and no other Pastry node runs on the local machine, then FreePastry creates a new overlay network with itself as the only node. Any node that is already part of the Pastry node can serve as the bootstrap node.)
To compile the source distribution, you will need to have GNU make installed (available from ftp://ftp.gnu.org/pub/gnu/make , or as part of cygwin ) on your system. Expand the archive (FreePastry-1.3.tgz or FreePastry-1.3.zip) into a directory. Set the environment variables mentioned in setpath.csh to values appropriate for your system. Execute "make" in the top level directory (you may have to run "make" twice the first time), then change to the "classes" directory to run FreePastry.
You may have to provide a Java security policy file with sufficient permissions to allow FreePastry to contact other nodes. The simplest way to do this is to install a ".java.policy" file with the following content into your home directory:
grant {
permission java.security.AllPermission;
};
java [-cp pastry.jar] rice.pastry.testing.DistHelloWorld
[-msgs m] [-nodes n] [-port p] [-bootstrap bshost[:bsport]] [-protocol [wire,rmi]]
[-verbose|-silent|-verbosity v] [-help]
Without -bootstrap bshost[:bsport], only localhost:p is used for bootstrap.
Default verbosity is 5, -verbose is 10, and -silent is -1 (error msgs only).
(replace "pastry.jar" by "FreePastry-<version>.jar", of course)
a. java rice.pastry.testing.DistHelloWorld
Starts a standalone Pastry network, and sends two messages
essentially to itself. Waits for anyone to connect to it,
so terminate with ^C.
b. java rice.pastry.testing.DistHelloWorld -nodes 2
One node starts a Pastry network, and sends two messages to
random destination addresses. At some point another node
joins in, synchronizes their leaf sets and route sets, and
sends two messages to random destinations. These may be
delivered to either node with equal probability. Note how
the sender node gets an "enroute" upcall from Pastry before
forwarding the message.
c. java rice.pastry.testing.DistHelloWorld -nodes 2 -verbose
Also prints some interesting transport-level messages.
d. pokey$ java rice.pastry.testing.DistHelloWorld
gamma$ java rice.pastry.testing.DistHelloWorld -bootstrap pokey
Two machines coordinate to form a Pastry network.
e. pokey$ java rice.pastry.testing.DistHelloWorld
gamma$ java rice.pastry.testing.DistHelloWorld -bootstrap pokey
wait a few seconds, and interrupt with <ctrl-C>
gamma$ java rice.pastry.testing.DistHelloWorld -bootstrap pokey
The second client restarts with a new NodeID, and joins the
Pastry network. One of them sends messages to the now-dead
node, finds it down, and may or may not remove it
from the leaf sets. (repeat a few times to observe both
possibilities, i.e., leaf sets of size 3 or 5). If the
latter, then leaf set maintenance kicks in within a minute
on one of the nodes, and removes the stale entries.
f. pokey$ java rice.pastry.testing.DistHelloWorld
gamma$ java rice.pastry.testing.DistHelloWorld -bootstrap pokey -nodes 2
The client on gamma instantiates two virtual nodes, which
are independent in identity and functionality. Note how the
second virtual node bootstraps from the first (rather than
from pokey). Try starting say 10 or 30 virtual nodes, killing
with a <ctrl-C>, starting another bunch, etc.
java [-cp pastry.jar] rice.pastry.testing.HelloWorld [-msgs m] [-nodes n] [-verbose|-silent|-verbosity v] [-simultaneous_joins] [-simultaneous_msgs] [-help]
a. java rice.pastry.testing.HelloWorld
Creates three nodes, and sends total three messages from
randomly chosen nodes to random destinations addresses
(which are delivered to the node with the numerically
closest address).
b. java rice.pastry.testing.HelloWorld -simultaneous_joins -simultaneous_msgs
Join all three nodes at once, then issue three messages,
then go about delivering them.
java [-cp pastry.jar] rice.pastry.testing.DirectPastryRegrTest
java [-cp pastry.jar] rice.pastry.testing.DirectPastryPingTest
java [-cp pastry.jar] rice.p2p.scribe.testing.ScribeRegrTest [-nodes n] [-port p] [-bootstrap bshost[:bsport]] [-protocol (direct|wire|rmi)] [-help]
Ports p and bsport refer to contact port numbers (default = 5009).
Without -bootstrap bshost[:bsport], only localhost:p is used for bootstrap.
(replace "pastry.jar" by "FreePastry-<version>.jar", of course)
java [-cp pastry.jar] rice.p2p.past.testing.PastRegrTest [-nodes n] [-protocol (direct|wire|rmi)]
This creates a network of n nodes (10 by default), and then
runs the Past regression test over these nodes.
SplitStream.java class provides an interface that can be used by applications to create SplitStream instances. Each SplitStream forest is represented by a channel object (Channel.java), where a channel object encapsulates multiple stripe trees. Each stripe tree for a SplitStream forest is represented by a class (Stripe.java), which handles the data reception and subscription failures.
Applications can configure the maximum capacity each channel can accomodate in terms of number of children it is willing to accept. Applications can control total outgoing capacity they are willing to provide by changing the value in ScribeSplitStreamPolicy.java.
1. To run a simple distributed test:
java [-cp pastry.jar] rice.p2p.splitstream.testing.SplitStreamRegrTest [-nodes n] [-protocol (direct|wire|rmi)]
This creates a network of n nodes (10 by default), and then
runs the SplitStream regression test over these nodes.