These are frequently asked questions and answers for
Guarana 1.2: Brazilian Slavery Abolition Day edition

Introduction
------------

Q1. What is guarana?

A1. Guarana is the name of an Amazonian bush tree, as well as its
    fruit, that contains lots of caffeine.  There's a very tasty
    soft-drink made from this fruit; if you ever come to Brazil, ask
    for a bottle of Guarana, you'll love it.  Richard Stallman did!
    Really!

    Guarana powder is commonly used as an ingredient to hot drinks
    that people have in order to stay awake for the whole Carnival
    holiday.  In Brazil, that's serious business: it's four days long!

    This all is to say that Guarana is a good replacement for Java :-)

Q2. No, I mean, what is Guarana, with capital `G'?  This piece of
    software I've just downloaded!

A2. Guarana is the name of a reflexive architecture we have created,
    that allows multiple meta-objects to be combined to define the
    meta-level behavior for an object, which improves code reuse.

    Some of its unique characteristics are the hierarchical
    organization of meta-objects and the preoccupation with security
    of both base-level and meta-level objects.

    Please read the technical report that describes Guarana for more
    details (it's available from my home page), and fell free to
    send e-mail to the Guarana mailing-list if you have any doubts.

Q3. Who are `we' and `I'?

A3. When I write `we', I refer to the people who have created Guarana,
    namely:

	- Alexandre Oliva <oliva@dcc.unicamp.br> (that's me! :-)
	    Computer Science MSc student.  I work on computational
	    reflection, and I'm particularly interested in
	    fault-tolerant distributed systems.

	- Islene Calciolari Garcia <islene@dcc.unicamp.br>
	    Computer Science MSc student.  She works with distributed
	    systems, in particular, global snapshots algorithms.
	    In her spare time, she's my fiancee.  :-)

	- Luiz Eduardo Buzato <buzato@dcc.unicamp.br>
	    He's our advisor, which means he's the one to be blamed. :-)
	    He's a full-time professor at the Institute of Computing
	    of the State University of Campinas, SP, Brazil.  He's got
	    his PhD at Newcastle, UK.

Q4. So why would I want to use Guarana?

A4. Because we worked a lot to make it good for you! :-)

    Seriously, computational reflection is a powerful technique that
    allows one to implement management requirements, such as
    persistence, distribution, replication, fault-tolerance and
    concurrency control, just to mention a few, in a transparent way,
    that is, one doesn't have to modify the application code in order
    to add these features.

    Guarana was made so that the implementation of these features can
    be reused across several applications, *even if you don't have
    their source code*.  Furthermore, in Guarana, you can dynamically
    enable or disable these features, for selected objects.

Q5. Is Guarana 100% Java?

A5. No.  Although we haven't modified the Java Programming Language at
    all, we have modified a Java interpreter to provide for
    interception of operations such as method and constructor
    invocation, field and array element access, synchronization
    operations and object creation.

    It might have been possible to implement Guarana in 100% Java, but
    it would involve pre-processing class files with a custom
    ClassLoader.  Even standard Java classes would have to be
    preprocessed, which is unportable anyway.  In the beginning, we
    have actually tried to do that, but we haven't tried hard enough.
    Modifying the interpreter was much easier.

Q6. Why did you choose to modify Kaffe?

A6. Because it is Free Software!

    Furthermore, I didn't have access to the sources of any other
    implementation of the Java Virtual Machine when I started (now
    there's Japhar, the GNU JVM).  In particular, I'm not a source
    code licensee of Sun's JDK, and I really don't want to, since I
    like and support the Free Software concept, and working on JDK
    would forbid me from working on Kaffe or other Free JVMs.

    Anyway, if you do have access to JDK sources, and you'd like to
    implement Guarana on it, I'd be glad to lend you a hand.

Q7. Can I use Guarana with other programming languages?

A7. Certainly.  There's nothing in the reflexive architecture of
    Guarana that ties it to Java.  It was designed to be a
    language-independent reflexive architecture.  Java was chosen for
    the first implementation because of its simplicity and
    portability.

    I should note, however, that we don't currently have plans to
    implement Guarana for other programming languages.  If you decide
    to do so, please tell me.

Q8. Can I use concepts of Guarana on other reflexive platforms?

A8. Of course!  I couldn't prevent you from doing that, anyway!

    In fact, Guarana was originally intended to be an extension to
    existing reflexive architectures.  It has grown to a complete
    reflexive architecture, but you can easily borrow some of its
    concepts, such as meta-object composition and meta-configuration
    propagation to other reflexive architectures.

Q9. Do I have to modify my application source code to use Guarana?

A9. Not at all.  Your application code doesn't have to be modified,
    and you don't even need the source code of your application in
    order to make it reflexive.  In fact, we support the idea that you
    *shouldn't* modify the base-level code because of reflection,
    otherwise the separation of concerns between the functional (base)
    level and the management (meta) level is broken.


Installing and Running Guarana
------------------------------

Q1. How do I install Guarana?

A1. First, you should have downloaded the distribution file of
    Guarana.  It contains a file named README.  You don't have to read
    it, actually, it just says Guarana is Free Software and such.
    Instead, you should read the FAQ, which is this file you're
    reading already.

    Decompress the Guarana tarball into a temporary directory.
    Then, download kaffe 0.10.0 package into the guarana directory.
    This tar file used to be available from
    ftp://ftp.kaffe.org/pub/kaffe.  If it ever disappears from there,
    there will be a copy of it available from my home page.

    From inside directory guarana-1.2, run `make'.  This will
    decompress the kaffe package and apply two patch files: first, the 
    patch that updates kaffe 0.10.0 to the latest tested development
    snapshot available at the time of this release, then the patch
    file that modifies kaffe so that it supports Guarana.  You may
    need GNU patch, if your system lacks a patch utility, or if it
    can't handle the patch file.

    Ok, now you're ready to build: enter the kaffe-0.10.0 directory,
    configure, make and make install, as you used to do with kaffe.

    You may try to use this release of Guarana with newer releases of
    Kaffe, just `touch update-stmp' and set KAFFE_VERSION as
    appropriate for you.

Q2. What if it doesn't build?

A2. You have probably found out kaffe hasn't probably been ported to
    your platform yet.  Note that there was a major change in the
    platform-specific interface of kaffe from release 0.9 to 0.10, so
    some formerly-supported platforms may have become unsupported
    again.

    I have tested it myself on Sparc Solaris 2.5 and 2.6 and RedHat
    Linux/GNU 4.0/x86 and 5.0/x86, with both engines (jit and intrp).

    I have unsuccessfully tried it on IRIX 5.2 and 6.3: kaffe would
    refuse to configure, and README says these are not currently
    supported platforms anyway.  On RedHat Linux/GNU 5.0/alpha, there
    was no such configure-time error, but compile-time ones instead.
    Perhaps we just need someone to port kaffe to these platforms
    again...  On SunOS 4.1.3, it would compile, link and install
    successfully, but it wouldn't run, and gdb would crash when
    loading the `kaffe' program; too bad :-(

Q3. How hard is it to port Guarana to other platforms?

A3. Since Guarana is not platform-specific at all, it is as portable
    as Kaffe itself.

Q4. How do I run Guarana?

A4. Just like you invoked kaffe.  There isn't a separate executable
    program; it is just the virtual machine that was modified.

    Well, actually, you need to modify the CLASSPATH so that the
    guarana jar file is searched for classes, and you have to make
    sure the guarana shared library can be found in LD_LIBRARY_PATH.

    The easies way to accomplish this is to make sure your environment
    contains all the definitions listed in file ENVIRONMENT, which
    is created when you run `configure'.

    I myself prefer to use shell-scripts that will set up my
    environment and invoke kaffe for me.  I don't understand why kaffe
    doesn't do it itself...  Perhaps we can work it out for the next
    release...

    Just save the script below in same directory in your PATH, fix the
    definition of variable `prefix', name the script `kaffe' and make it
    executable.  You may also create hard-links or copies of this file
    with names such as jar, javac, kaffeh, etc.

#!/bin/sh
prefix=<insert the kaffe installation prefix here>
# follow soft links
file=$0
while [ -h $file ]; do
  newfile=`ls -l $file | sed s/'.* -> '//`
  case "$newfile" in
  /*) file="$newfile";;
  *) file="`dirname "$file"`/$newfile";;
  esac
done
name=`echo $file | sed 's%.*/%%g'`
CLASSPATH=${CLASSPATH-.}:$prefix/share/kaffe/klasses.zip:$prefix/share/kaffe/classes.zip:$prefix/share/kaffe/guarana.jar
export CLASSPATH
LD_LIBRARY_PATH=$prefix/lib${LD_LIBRARY_PATH+:$LD_LIBRARY_PATH}
export LD_LIBRARY_PATH
PATH=$prefix/bin${PATH+:$PATH}
export PATH
exec $name ${1+"$@"}

Q5. Is there any sample code available?

A5. Yes.  After you apply the guarana patch, you should find a rather
    complete example in directory sample.  It shows most of the
    single-meta-object functionality of Guarana, using a sample
    MetaObject called MetaLogger.  Composing meta-objects is left as
    an exercise for the reader.

    Note that you can use this MetaLogger to start any Java
    application in logging mode: run `kaffe MetaLogger' for usage.

Q6. What if I have any doubts about Guarana?

A6. Subscribe to the Guarana mailing-list (send e-mail to
    guarana-subscribe@makelist.com), then post your question to
    guarana@makelist.com.  There is a mailing-list archive at
    <URL:http://www.findmail.com/listsaver/guarana>, if you'd rather
    check for common questions before posting.

Q7. What if I Guarana doesn't work as I expected?

A7. Maybe your expectations were incorrect.  :-)

    Sometimes, Guarana does more than we'd expect it to do, because we 
    don't know enough about the internals of the class/object we're
    reflecting upon, or we just couldn't foresee its behavior.

    On the other hand, you may have found a bug.  Please post a
    detailed bug report.  Code snippets and stack traces are welcome.

Q8. Is there anything else I should know?

A8. Yes.  You should read the paper that describes the Reflexive
    Architecture of Guarana (it is available from my home page).
    Additionally, the API of Guarana is worth having on-line; you may
    rebuild it from the sources: just run `make docs' in directory
    src.  If you, for any reason, modify the Java part of the source
    code of Guarana, run `make depend' in the `src' directory once.
    After that, running `make' should be enough.  After rebuilding the
    sources, you may wish to `make jar' and `make stubs' in directory
    kaffe-<version>/kaffe/kaffevm/guarana.

Q9. Why is it slower than kaffe?

A9. Why do you think it is?  Did you really measure its performance
    with real-world applications?

    My performance tests, with real-world applications such as
    compiling and running `HelloWorldApp' have indicated that the
    interception code inserted for Guarana support produces a
    *negligible* impact on performance on the interpreter engine.

    The JIT engine apparently suffers much more, but most affected
    part is the JIT compiler itself, because some bytecodes now
    produce machine-code that is much more complex.  So, what seems an 
    unacceptable performance impact for short-running test programs,
    turns out to be negligible for long-running ones.

    Of course, all this assumes no use of reflection at all.  When you 
    introduce meta-objects, even do-nothing ones, performance drops
    down a lot, because interception of operations has to take
    place. But then, isn't intercepting operations what reflection is
    all about?

    Anyway, I've still got plans on how to make the negligible
    performance impact yet more negligible, but I've got a MSc Thesis
    to finish first! :-)

    Here's a list of points that might improve the performance
    of Guarana:

    - instead of checking, for each operation, whether the target
      object or class is associated with a meta-object or not, a
      modified dispatch table could be set up, so that non-reflexive
      operations do not incur into any additional cost.  This would
      also reduce register spilling and reloading on all interceptable
      operations except monitor enter and exit.  However, it is hard
      to foretell whether this will achieve any performance gain in
      the case of field and array operations.  For method invocations, 
      it certainly will.

    - reification of method invocations have to parse the method
      signature several times.  A good way to improve this situation
      would be to modify the argument list reification and method
      dispatching mechanisms.  With the JIT engine, we could generate
      an additional code block that reify invocations of a particular
      method, and another that dispatches such an invocation.

* Java is a trademark of Sun Microsystems, Inc.
