These are frequently asked questions and answers for
Guarana 1.3: Corpus Christi edition

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

Q.  What is guarana?

A.  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 :-)

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

A.  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.

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

A.  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.

Q.  So why would I want to use Guarana?

A.  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.

Q.  Is Guarana 100% Java?

A.  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.

Q.  Why did you choose to modify Kaffe?

A.  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.

Q.  Can I use Guarana with other programming languages?

A.  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.

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

A.  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.

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

A.  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
------------------------------

Q.  How do I install Guarana?

A.  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.1 package into the guarana directory.
    This tar file should be available at
    ftp://ftp.transvirtual.com/pub/kaffe.  If it ever disappears from
    there, you are likely to find a copy of it in the Guarana home
    page.

    From inside directory guarana-1.3, run `make'.  This will
    decompress the kaffe package and apply one 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.1 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 or
    snapshots of Kaffe, just set KAFFE_VERSION as appropriate for you.

Q.  What if it doesn't build?

A.  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).

    On Sparc SunOS 4.1.3, Kaffe would build with both engines, but it
    would not run.  It would always say that it could not locate
    native libraries, in spite of printing the directory that contains
    the shared libraries it is looking for.

    On Mips SGI Irix 5.2 and 6.3, Kaffe would build with intrp only,
    but it would not run.  When started, it would claim
    systemCallMethod was referenced in libkaffevm.so.0.100, but not
    defined anywhere.  The definition in config/mips/common.h
    certainly does not apply to a mips processor, and is certainly
    provided just as an example for candidate porters.

    On RedHat Linux/GNU 5.0/alpha, Kaffe would not even build.  From
    the compiler errors, it seems to believe it is on a x86 host.

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

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

Q.  How do I run Guarana?

A.  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+"$@"}

Q.  Is there any sample code available?

A.  Yes, there is a directory called `sample' that contains plenty of
    examples.  The ones in the root directory are just simple examples
    for testing Guarana; in `tutorial-src', you should find all the
    sources for the Guarana Tutorial, a paper to be published soon; a
    preview version of this document should be available at the time
    of this release.  In directory `performance', you'll find a
    program that times several operations, that was used to collect
    data for the paper The Implementation of Guarana, to be published
    soon as well.

    Most examples are based on class MetaLogger, contained in the
    `tutorial-src', so you'd better add this directory to the
    CLASSPATH.  In order to compile all sample sources, just type
    `make' in the source directory, after setting up your ENVIRONMENT.

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

Q.  What if I have any doubts about Guarana?

A.  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.

    Note that the list will only accept posts from subscribers, in
    order to avoid spamming.

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

A.  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.

Q.  Is there anything else I should know?

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

Q.  Why is it slower than kaffe?

A.  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.
    (Actual figures can be found in ``The Implementation of Guarana'',
    available from the home-page of Guarana)

    The JIT engine, particularly the JIT compiler itself, exhibits a
    sensitive performance drop, because some bytecodes now
    produce much more complex machine-code.  However, what seems an
    unacceptable performance impact for short-running test programs,
    turns out to be negligible for long-running ones, because after
    the translation phase, performance is not affected very much.

    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.
