BRAKES v0.3 ---------------------------------------------------------------------- Developed by: Distributed Systems and Computer Networks Group (DistriNet) Katholieke Universiteit Leuven Department of Computer Science Celestijnenlaan 200A 3001 Leuven (Heverlee) Belgium Project Manager and Principal Investigator: Pierre Verbaeten Licensed under the Academic Free License version 1.1 (see COPYRIGHT) ---------------------------------------------------------------------- This file contains information on how to use the BRAKES framework. A website containing more information about BRAKES shall soon be set up. BRAKES started as a subproject of Correlate. For more information about Correlate, please refer to http://www.cs.kuleuven.ac.be/~xenoops/CORRELATE BRAKES uses a modification of version 1.4 of the JavaClass ByteCode Engineering Library. (http://www.inf.fu-berlin.de/~dahm/JavaClass/) Modifications are: - added additional constructor: public InstructionFactory (ConstantPoolGen cp) - some small bugfixes The current version of the JavaClass ByteCode Engineering Library (version 3.3.1) is released under the GNU Library General Public License. Compatability ------------- BRAKES has been tested on Solaris 2.6 and Linux 2.2 using the Sun Java developer's kit (version 1.2). Versions -------- The BRAKES packages consists of three general parts: - A bytecode transformer which instruments the Java class files. - Two versions of a small computation framework: - computation-serial: This version does not allow JVM context-switching between different threads (thus no pre-emptive scheduling). The programmer is responsible for implementing a customized multi-tasking scheme himself using the primitives defined on our thread abstraction. We have implemented a default demo-version of such mulitasking scheme in the context of the CORRELATE project (see also section 6 of the ASA/MA'2000 Conference paper for info about this - link at the end of this README). - computation (aka computation-parallel): This version does allow JVM context-switching and preemptive scheduling between different threads. Currently we haven't tested how this works together with the Java locking mechanism. NOTE: This latter version (parallel) is not as fast/stable as the first (serial), which was the one presented at the ASA/MA'2000 Conference. Usage ----- Using BRAKES takes three steps : 1) First determine which version of the computation framework you wish to use, and adapt the file rewriteinfo.prop accordingly. This file has always to be located at the directory of where you start your BRAKES-enabled application. When using the computation-serial framework, make sure the file contains: COMPUTATIONCLASS = be.ac.kuleuven.cs.ttm.computationserial.Computation CONTEXTCLASS = be.ac.kuleuven.cs.ttm.computationserial.Context When using the computation framework, these lines are: COMPUTATIONCLASS = be.ac.kuleuven.cs.ttm.computation.Computation CONTEXTCLASS = be.ac.kuleuven.cs.ttm.computation.Context 2) Second, all of your classfiles will need to be hauled through the transformer. To do this, call the transformer with the command java be.ac.kuleuven.cs.ttm.transformer.Transformer for each class. Now two files exist: the original classfile and a file .class.rewritten. Swap these two files to make sure the rewritten version will be used. An included script, rewriteswap.pl, automatically performs this step. In the future, this step will be automated by using a specific classloader. 3) The classes to use when creating serializable threads are : be.ac.kuleuven.cs.ttm.ttm.Computation be.ac.kuleuven.cs.ttm.ttm.Scheduler be.ac.kuleuven.cs.ttm.ttm.Factory Each serializable thread must be run in a Computation object. Each Computation object must be started, and finally the Scheduler must be started to effectivly start up the threads. Example ....... Counter is a Runnable class, and we want to startup two Counter objects in two different computations : Counter count1 = new Counter(); Counter count2 = new Counter(); Computation comp1 = Factory.getInstance().createComputation(count1); Computation comp2 = Factory.getInstance().createComputation(count2); comp1.start(); comp2.start(); Scheduler.getInstance().start(); The last instruction (Scheduler.getInstance().start()) never stops. A running computation can stop itself with the command Scheduler.getInstance().currentComputation().yield(true) The originating thread can reschedule the paused computation with comp1.resume() This command throws an 'IllegalStateException' when executed on a computation which is not stopped. In computation-serial, as JVM context switching isn't possible, an application can simulate this. By issuing the command Scheduler.getInstance().currentComputation().yield(false) the running computation causes itself to stop and add itself at the end of the list of waiting computations. Included are two code examples which illustrate the use of the BRAKES system. (src/test1 and src/test2) Common Problems --------------- Sometimes the transformer returns a verify error. This error arises due to a a ClassNotFoundException. This is not a bug. This is a run-time error caused by wrong use of the transformer or a mal-configured environment: 1) improper use of transformer You should start the transformer with java be.ac.kuleuven.cs.ttm.transformer.Transformer thus for example java be.ac.kuleuven.cs.ttm.transformer.Transformer Test.class 2)CLASSPATH variable is not set You should add to your system variable CLASSPATH the directory in which the source code of the examples is rooted !! Please Note !! ----------------- BRAKES is a very young system, based on a 'bleeding edge' technology. As noted above, we provide NO WARRANTY OF ANY KIND. See http://www.cs.kuleuven.ac.be/~tim/MOS/ for more details about the implementation status. Contact information ------------------- This README is maintained by Eddy Truyen