These are questions that would be frequently asked about Guarana if
they were not answered here already.  Enjoy!

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 reflective 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@lsd.ic.unicamp.br> (that's me! :-) Computer
Science PhD student.  I work on computational reflection, and I'm
particularly interested in fault-tolerant distributed systems.

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

    - Luiz Eduardo Buzato <buzato@ic.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,
we have had to modify the 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 is impossible to implement Guarana in 100% Java.  We have tried
really hard, but we ended up proving it was impossible.  A paper
describing the problems we have encountered is planned.

Q.  Why did you choose to modify Kaffe?

A.  Because it is Free Software, and it is the most portable existing
Java Virtual Machine!  What could have been a better choice?

    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 reflective architecture of
Guarana that ties it to Java.  It was designed to be a
language-independent reflective 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 let us know.

Q.  Can I use concepts of Guarana on other reflective 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 reflective architectures.  It has grown to a complete
reflective architecture, but you can easily borrow some of its
concepts, such as meta-object composition and meta-configuration
propagation to other reflective 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 reflective.  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 really have to
read, it just says Guarana is Free Software and such.  Instead, you
should read the FAQ, that is this file you're reading already.

    Decompress the Guarana tarball into a temporary directory.  Then,
run `configure; make; make install', as you'd usually do with Kaffe.
Read INSTALL for detailed instructions.

Q.  What if it doesn't build?

A.  Make sure you don't have CLASSPATH, LD_LIBRARY_PATH or
KAFFELIBRARYPATH set in your environment while you build Guarana, as
they may cause the compilation of the Guarana examples or the
generation of the docs to crash.

    You have probably found out Kaffe hasn't probably been ported to
your platform yet.  Read the PLATFORMS file for a list of tested
platforms, and kaffe/README for a list of platforms on which Kaffe is
supposed to run.  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;
kaffe/README hasn't been much updated since then, but PLATFORMS is
updated before each release of Guarana.

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 OpenVM itself.  However, if you find trouble with Guarana on
a platform in which Kaffe OpenVM works, please report this to the
mailing-list.

Q.  How do I run Guarana?

A.  Just like you used to start the Kaffe OpenVM, i.e., run `guarana'
in order to start any Java program, `guaranac' to start the Java
compiler, etc.  `guarana' and `guaranac' are copies of, respectively,
`kaffe' and `javac', for your convenience, but that's all.

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.  In directory `performance', you'll find a
program that times several operations, that was used to collect data
for the paper The Design and Implementation of Guarana, published in
the Proceedings of USENIX COOTS'99, and the more-detailed technical
report The Implementation of Guarana.  All these papers are available
in the Guarana Home Page.

    Most examples are based on class MetaLogger, that has become part
of the Guarana API as of release 1.6.  If you prefer, there's still a
packageless copy of this class in `tutorial-src'.

    Note that you can use this MetaLogger to start any Java
application in logging mode: check the API documentation for usage.

Q.  What if I have any doubts about Guarana?

A.  Subscribe to the Guarana mailing-list (send e-mail to
guarana-subscribe@egroups.com), then post your question to
guarana@egroups.com.  There is a mailing-list archive at
http://www.egroups.com/listsaver/guarana.

    Note that the list is moderated for postings from non-subscribers,
to avoid spamming, but subscribers are allowed to post at will.
Nevertheless, the traffic is quite low, as you may notice from the
archives.  Even if you don't subscribe, I'd appreciate a personal
message with your opinions/plans about Guarana.

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 probably read the paper that describes the
Reflective Architecture of Guarana, or the paper Composition of
Meta-Objects in Guarana, both available from the Guarana Home Page.
You may also find the Guarana Tutorial useful.  Additionally, the API
of Guarana is worth having on-line; you may download it from the Home
Page too.  If you, for any reason, modify the Java part of the source
code of Guarana, run `make build-classes' in the directory
`kaffe/libraries/extensions/guarana/javalib' to rebuild guarana.jar.

Q.  Why is Guarana 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 to support the MOP of Guarana produces a
*negligible* impact on performance on the interpreter engine.  Actual
figures can be found in ``The Design and Implementation of Guarana''.
More detailed information about the implementation can be obtained in
``The Implementation of Guarana'', a technical report, that I hope to
update with figures for the platforms Kaffe has been re-ported to.

    The JIT engine, particularly the JIT compiler itself, exhibits a
larger performance impact, 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
about 15%-20%, on average, 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, lots of
objects have to be created and garbage collected, etc.  But then,
isn't intercepting operations what reflection is all about?

    Anyway, we've still got plans on how to make the small performance
impact yet smaller; the papers mentioned in this section describe some
future optimizations.

    We have plans to modify GCJ, the GNU Compiler for Java(TM), so as
to support the Guarana meta-object protocol.  This will allow
pre-compilation of Java(TM)/Guarana code with all optimizations
offered by GCC.  Since Kaffe can use classes pre-compiled by GCJ, the
plan is to introduce Guarana in GCJ so that Guarana/Kaffe can use
classes pre-compiled by GCJ/Guarana.

Q.  Why aren't all monitor_exit operations intercepted?

A.  Because, with the new locking mechanism of Kaffe, they aren't even
executed.  This is the case when leaving a synchronized JIT-compiled
method, or when exiting a method by propagating an exception out of a
method that holds monitors.  The new locking mechanism is based on
using stack slots as markers of locks, so that, when leaving a stack
frame, locks are implicitly released.  We still haven't decided
whether we're going to force these monitorexit operations to be
executed, so that they can be intercepted, or if we can just leave it
up to MetaObjects to take such monitorexits as implied.  Furthermore,
it's not clear whether generating monitorenter and monitorexit
operations from the meta-level has any useful effects.  This is
hopefully going to be resolved in a future release.


* Java is a trademark of Sun Microsystems, Inc.
