Permalink
Browse files

Add/update Doxygen class comments for several classes

  • Loading branch information...
1 parent d3e44c5 commit 2749c19dd87fa0909af4125a8eb9a0eb3c026f68 @agardiner agardiner committed Jan 10, 2011
View
@@ -16,18 +16,19 @@ using namespace rubinius;
static void check_directory(std::string root);
-/* The main function here handles the CL arguments passed to it.
- * It then boots the VM, runs the appropriate file (`loader`),
- * and returns 0. If there is an Assertion raised or an Exception,
- * it prints the backtrace supplied. This function is the wrapper for
- * the entire VM, as it deals with anything that could possibly happen
- * to the VM. It's like the person playing whack-a-mole, in that if
- * something tries to come out of the VM that's evil (such as a failed
- * assertion or exception), it catches it and skins it and shows it to
- * the user.
+/**
+ * Main rbx entry point.
*
- * Note: Although Rubinius is gathering support for multiple VMs, this
- * function does not deal with that subject.
+ * The main function here handles the environment settings and command-line
+ * arguments passed to it. It then boots the VM, runs the appropriate file
+ * (`loader`), and returns 0 if no errors occur along the way.
+ *
+ * If there is an Assertion raised or an Exception, it prints the backtrace
+ * supplied. This function is the wrapper for the entire VM, as it deals with
+ * anything that could possibly happen to the VM. It's like the person
+ * playing whack-a-mole, in that if something tries to come out of the VM
+ * that's evil (such as a failed assertion or exception), it catches it and
+ * skins it and shows it to the user.
*/
int main(int argc, char** argv) {
Environment env(argc, argv);
View
@@ -1,5 +1,3 @@
-/* An Environment is the toplevel class for Rubinius. It manages multiple
- * VMs, as well as imports C data from the process into Rubyland. */
#include "config.h"
#include "prelude.hpp"
#include "environment.hpp"
@@ -495,6 +493,9 @@ namespace rubinius {
state->shared.stop_the_world(state);
}
+ /**
+ * Returns the exit code to use when exiting the rbx process.
+ */
int Environment::exit_code() {
#ifdef ENABLE_LLVM
@@ -528,29 +529,29 @@ namespace rubinius {
agent->run();
}
- /* Loads the runtime kernel files. They're stored in /kernel.
- * These files consist of classes needed to bootstrap the kernel
- * and just get things started in general.
+ /**
+ * Loads the runtime kernel files stored in /runtime.
+ * These files consist of the compiled Ruby /kernel code in .rbc files, which
+ * are needed to bootstrap the Ruby kernel.
+ * This method is called after the VM has completed bootstrapping, and is
+ * ready to load Ruby code.
*
- * @param root [String] The file root for /kernel. This expects to find
- * alpha.rbc (will compile if not there).
- * @param env [Environment&] The environment for Rubinius. It is the uber
- * manager for multiple VMs and process-Ruby interaction.
+ * @param root The path to the /runtime directory. All kernel loading is
+ * relative to this path.
*/
void Environment::load_kernel(std::string root) {
+ // Check that the index file exists; this tells us which sub-directories to
+ // load, and the order in which to load them
std::string index = root + "/index";
std::ifstream stream(index.c_str());
if(!stream) {
std::cerr << "It appears that " << index << " is missing.\n";
exit(1);
}
- // Load the ruby file to prepare for bootstrapping Ruby!
- // The bootstrapping for the VM is already done by the time we're here.
-
- // First, pull in the signature file. This helps control when .rbc files need
- // to be discarded.
-
+ // Pull in the signature file; this helps control when .rbc files need to
+ // be discarded and recompiled due to changes to the compiler since the
+ // .rbc files were created.
std::string sig_path = root + "/signature";
std::ifstream sig_stream(sig_path.c_str());
if(sig_stream) {
@@ -587,6 +588,13 @@ namespace rubinius {
}
}
+ /**
+ * Runs rbx from the filesystem, loading the Ruby kernel files relative to
+ * the supplied root directory.
+ *
+ * @param root The path to the Rubinius /runtime directory, which contains
+ * the loader.rbc and kernel files.
+ */
void Environment::run_from_filesystem(std::string root) {
int i = 0;
state->set_stack_start(&i);
View
@@ -13,18 +13,32 @@ namespace rubinius {
class ConfigParser;
class QueryAgent;
- // throw when there is a bad signature on a kernel .rbc file.
+ /**
+ * Thrown when there is a bad signature on a kernel .rbc file.
+ */
class BadKernelFile : public std::runtime_error {
public:
BadKernelFile(const std::string& str)
: std::runtime_error(str)
{}
};
+
+ /**
+ * The environment context under which Rubinius virtual machines are executed.
+ *
+ * Environment and configuration data is processed and stored in an Environment
+ * instance, which uses this information to bootstrap the VM. It also stores
+ * all runtime shared state.
+ */
+
class Environment {
int argc_;
char** argv_;
+ /// Signature to be used to verify the validity of .rbc files.
+ /// If the signature in a .rbc file does not match this value, the file
+ /// needs to be recompiled.
uint64_t signature_;
public:
View
@@ -19,6 +19,16 @@
#include "capi/tag.hpp"
namespace rubinius {
+
+ /**
+ * Creates a BakerGC of the specified size.
+ *
+ * The requested size is allocated as a contiguous heap, which is then split
+ * into three spaces:
+ * - Eden, which gets half of the heap
+ * - Heap A and Heap B, which get one quarter of the heap each. Heaps A and B
+ * alternate between being the Current and Next space on each collection.
+ */
BakerGC::BakerGC(ObjectMemory *om, size_t bytes)
: GarbageCollector(om)
, full(bytes * 2)
@@ -38,6 +48,15 @@ namespace rubinius {
BakerGC::~BakerGC() { }
+ /**
+ * Called for each object in the young generation that is seen during garbage
+ * collection. An object is seen by scanning from the root objects to all
+ * reachable objects. Therefore, only reachable objects will be seen, and
+ * reachable objects may be seen more than once.
+ *
+ * Returns the new address for the object, so that the source reference can
+ * be updated when the object has been moved.
+ */
Object* BakerGC::saw_object(Object* obj) {
Object* copy;
@@ -76,6 +95,10 @@ namespace rubinius {
return copy;
}
+
+ /**
+ * Scans the remaining unscanned portion of the Next heap.
+ */
void BakerGC::copy_unscanned() {
Object* iobj = next->next_unscanned(object_memory_->state());
@@ -86,7 +109,14 @@ namespace rubinius {
}
}
+
+ /**
+ * Returns true if the young generation has been fully scanned in the
+ * current collection.
+ */
bool BakerGC::fully_scanned_p() {
+ // Note: The spaces are swapped at the start of collection, which is why we
+ // check the Next heap
return next->fully_scanned_p();
}
@@ -98,7 +128,9 @@ namespace rubinius {
const static int cUnderFullTimes = -3;
const static size_t cMaximumLifetime = 6;
- /* Perform garbage collection on the young objects. */
+ /**
+ * Perform garbage collection on the young objects.
+ */
void BakerGC::collect(GCData& data, YoungCollectStats* stats) {
#ifdef RBX_GC_STATS
stats::GCStats::get()->bytes_copied.start();
@@ -115,6 +147,7 @@ namespace rubinius {
copy_spills_ = 0;
reset_promoted();
+ // Start by copying objects in the remember set
for(ObjectArray::iterator oi = current_rs->begin();
oi != current_rs->end();
++oi) {
@@ -227,11 +260,10 @@ namespace rubinius {
assert(fully_scanned_p());
// We're now done seeing the entire object graph of normal, live references.
// Now we get to handle the unusual references, like finalizers and such.
- //
- /* Update finalizers. Doing so can cause objects that would have just died
- * to continue life until we can get around to running the finalizer. That
- * more promoted objects, etc. */
+ // Update finalizers. Doing so can cause objects that would have just died
+ // to continue life until we can get around to running the finalizer. That
+ // means more promoted objects, etc.
check_finalize();
// Run promotions again, because checking finalizers can keep more objects
@@ -246,10 +278,10 @@ namespace rubinius {
// find_lost_souls();
#endif
- /* Check any weakrefs and replace dead objects with nil*/
+ // Check any weakrefs and replace dead objects with nil
clean_weakrefs(true);
- /* Swap the 2 halves */
+ // Swap the 2 halves
Heap *x = next;
next = current;
current = x;
@@ -265,6 +297,7 @@ namespace rubinius {
stats->excess_objects = copy_spills_;
}
+ // Tune the age at which promotion occurs
if(autotune_) {
double used = current->percentage_used();
if(used > cOverFullThreshold) {
Oops, something went wrong. Retry.

0 comments on commit 2749c19

Please sign in to comment.