The FreePastry Tutorial.
This tutorial is designed to get you cooking quickly with the FreePastry
API and software toolkit.
Version @tutorial_version@; @tutorial_date@. For FreePastry version @freepastry_version@. Maintained by @maintainer@.
Contents
- Lesson 0.a: Continuations.
- Lesson 0.b: Environment.
- Lesson 1: Minimal code to create/join a pastry ring.
- Lesson 2: Execute the code to launch your new ring.
- Lesson 3: Write a simple application using the commonAPI. (this will show you how to send and receive messages)
- Lesson 4: Running multiple nodes in the same JVM.
- Lesson 5: Scheduling tasks on the FreePastry timer.
- Lesson 6: Introducing Scribe.
- Lesson 7: Past &mdash FreePastry's DHT.
- Lesson 8: Splitstream.
- Lesson 9: Advanced Scribe: Policies.
- Lesson 10: Advanced Environment.
Getting Started
Lessons
Coming soon:
What You'll Need
Before you begin, you should meet the following requirements.- An intermediate level of knowledge in the Java programming language. The Java Tutorial is a good place to start.
- A copy of a current JDK, 1.4.2_06 or later. Sun's J2SE.
- A basic understanding of Pastry overlay structure. Read the short overview [pdf][ps] of FreePastry.
- Have a working copy of FreePastry-1.4_01 or later. You can simply download the current jar, or download and build the source.
Lesson 0.b
Environment
The environment allows us to more easily virtualize pastry inside the same Virtual machine. This is the main new feature of FreePastry 1.4.2. The environment serves FreePastry in 6 key ways:- Logging &mdash We have standardized on a logging system throughout FreePastry. This is a simpler logging framework than the one that ships with java. However it is compatible. (In other words, you can implement our LogManager and Logger with the Java one.) This logging replaces the previous "-verbose" etc. logging.
- Parameters &mdash Formerly hard-coded (
public static final
) parameters are now able to be specified at startup, or even changed during runtime rather than requiring a recompile. It allows parameters to be changed from code, and to be persistent. In other words, you could have a gui that lets you change the parameters, then store them to disk (By calling Parameters.store()), so next time the code is run, it retains the parameters. - SelectorManager &mdash You can control which nodes use which SelectorManager. The SelectorManager is a single thread that handles all network IO and Timer events. This model usually gives improved performance, and simpler synchronization than several threads. Note that the SelectorManager is a Daemon thread that will cause the JVM to not exit when the main method ends. See below to find out how to destroy the SelectorManager.
- Processor &mdash It is important that tasks done on the SelectorThread don't take long, as this is the network IO thread, and can cause other nodes to suspect you are faulty. However, sometimes you need to do a CPU intensive task (like calculate a manifest for a bloom filter) that will cause problems if done on the SelectorThread. For these tasks, you can use the "Processor. This is simply a different thread that will be context switched automatically by the system. Typically, you will access this by using the Node.process() or Endpoint.process() function call. These calls result in a call to the Processor. Future implementations could use more Threads for computers with several processors, or hyper-threading.
- TimeSource &mdash FreePastry and its apps now call TimeSource.currentTimeMillis() rather than System.currentTimeMillis(). This will (for example) allow you to run a FreePastry node on a clock that is offset from your computers clock. This can be particularly helpful in a situation like Planetlab where some nodes have incorrect system clocks due to misconfigured NTP servers.
- RandomSource &mdash Has the same interface as java.util.Random, but Allows for easier reproducability of some errors. You can seed the RandomSource with the same parameter so you can reproduce conditions.
How should I get an environment?
- In your main method simply call
new Environment()
. - In your application, call
node.getEnvironment(), or endpoint.getEnvironment()
.
My JVM won't exit, or How should I get rid of an environment?
The SelectorManager and Processor both have daemon threads that are used to handle communication and processing for the PastryNode. For the JVM to be able to exit, you will need to properly destroy the environment, by calling environment.destroy(). This will call store on the parameters, and destroy the selector/processor threads. Of course, you can also call System.exit(), but that is generally considered bad form.This should be sufficient information for you to continue with the tutorial. You can learn more in Lesson 10 Advanced Environment.