Small additions to documentation, and convenience methods.

Author: aardvark179

src/main/java/org/truffleruby/core/MarkingService.java

@@ -79,6 +79,11 @@ public MarkRunnerService(RubyContext context, ReferenceProcessor referenceProces
 
         @Override
         protected void processReference(ProcessingReference<?> reference) {
+            /*
+             * We need to keep all the objects that might be marked
+             * alive during the marking process itself, so we add the
+             * arrays to a list to achieve this.
+             */
             ArrayList<Object[]> keptObjectLists = new ArrayList<>();
             Object[] list;
             while (true) {
@@ -189,6 +194,10 @@ private boolean isFull() {
          *    We can just copy its contents into our buffer.
          * 4. The other buffer will not fit into our buffer. We need to copy across as much as will
          *    fit, queue the now full buffer, and then copy the rest.
+         *
+         * We do this rather than simply add the threads objects to
+         * the queue because we want to avoid increasing the marking
+         * overhead unnecessarily.
          */
         public void keepObjects(MarkerKeptObjects otherObjects) {
             if (isFull()) {
@@ -275,6 +284,13 @@ public void queueForMarking(Object[] objects) {
         runnerService.add(new MarkRunnerReference(new Object(), referenceProcessor.processingQueue, runnerService));
     }
 
+    /*
+     * Convenience method to schedule marking now. Puts an empty array on the queue.
+     */
+    public void queueMarking() {
+        queueForMarking(new Object[0]);
+    }
+
     public void addMarker(DynamicObject object, MarkerAction action) {
         add(new MarkerReference(object, referenceProcessor.processingQueue, action, this));
     }

src/main/java/org/truffleruby/core/VMPrimitiveNodes.java

@@ -109,7 +109,7 @@ public static abstract class VMGCStartPrimitiveNode extends PrimitiveArrayArgume
         @TruffleBoundary
         @Specialization
         public DynamicObject vmGCStart() {
-            getContext().getMarkingService().queueForMarking(new Object[0]);
+            getContext().getMarkingService().queueMarking();
             System.gc();
             return nil();
         }

src/main/java/org/truffleruby/language/objects/ObjectGraph.java

@@ -40,7 +40,7 @@ public static Set<DynamicObject> newRubyObjectSet() {
 
     @TruffleBoundary
     public static Set<DynamicObject> stopAndGetAllObjects(Node currentNode, final RubyContext context) {
-        context.getMarkingService().queueForMarking(new Object[0]);
+        context.getMarkingService().queueMarking();
         final Set<DynamicObject> visited = newRubyObjectSet();
 
         final Thread initiatingJavaThread = Thread.currentThread();