---

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 non-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/BlockingIO &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), or a DiskIO task (java 1.4.2 doesn't support non-blocking disk IO) that will cause problems if done on the SelectorThread. For these tasks, you can use the Processor. This is simply a different thread (or pool of threads) that will be context switched automatically by the system. Typically, you will access this by using the Node.process(), Endpoint.process(), or environment.getProcessor().processBlockingIO() function calls. The task provided to these calls will be executed on another thread so they don't interfere with the network IO thread. 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(). One benefit of this virtualization is that it allows a virtual clock in FreePastry's discreet event simulator. Another benefit is that this approach allows you to run a FreePastry node on a clock that is offset from the physical computer's 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.

Pastry applications access the Environment from the PastryNode or the commonapi Node (PastryNode implements Node). Generally you can use the same Environment for everything inside your JVM. The two Objects that you will likely construct with an Environment are the PastryNodeFactory and the IdFactory.

How should I get an environment?

• In your main method simply call new Environment(). Or if you are using the simulator, we recommend using Environment.directEnvironment(). Note that this can only be done before you create the PastryNodeFactory, don't do this elsewhere or you will be working with a different environment!
• In your application, call node.getEnvironment(), or endpoint.getEnvironment().

The default constructor for an environment looks in the classpath for a params file called freepastry.params. If you compiled the jar with the included ant task, or used the jar from the web, this should work automagically. If you are compiling FreePastry from an IDE (such as eclipse) or from the command line (javac) then you will need to make sure to put the freepastry.params file located in jars/freepastry in your classpath, or use a different contstructor for the Environment.

By default, the Environment also looks for a file in the local directory called user.params. With this file you can alter FreePastry's parameters without re-compiling or rebuilding the jar.

See also: Adjusting FreePastry's parameters.

My JVM won't exit, or How should I get rid of an environment?

The SelectorManager and Processor both have non-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 the Advanced Environment tutorial.

---