001    /*
002     *  This file is part of the Jikes RVM project (http://jikesrvm.org).
003     *
004     *  This file is licensed to You under the Eclipse Public License (EPL);
005     *  You may not use this file except in compliance with the License. You
006     *  may obtain a copy of the License at
007     *
008     *      http://www.opensource.org/licenses/eclipse-1.0.php
009     *
010     *  See the COPYRIGHT.txt file distributed with this work for information
011     *  regarding copyright ownership.
012     */
013    package org.mmtk.vm;
014    
015    import org.mmtk.plan.CollectorContext;
016    import org.mmtk.plan.MutatorContext;
017    
018    import org.vmmagic.pragma.*;
019    
020    @Uninterruptible public abstract class Collection {
021    
022      /****************************************************************************
023       *
024       * Class variables
025       */
026    
027      /**
028       * An unknown GC trigger reason. Signals a logic bug.
029       */
030      public static final int UNKNOWN_GC_TRIGGER = 0;
031    
032      /**
033       * Concurrent collection phase trigger.
034       */
035      public static final int INTERNAL_PHASE_GC_TRIGGER = 1;
036    
037      /**
038       * Externally triggered garbage collection (eg call to System.gc())
039       */
040      public static final int EXTERNAL_GC_TRIGGER = 2;
041    
042      /**
043       * Resource triggered garbage collection.  For example, an
044       * allocation request would take the number of pages in use beyond
045       * the number available.
046       */
047      public static final int RESOURCE_GC_TRIGGER = 3;
048    
049      /**
050       * Internally triggered garbage collection.  For example, the memory
051       * manager attempting another collection after the first failed to
052       * free space.
053       */
054      public static final int INTERNAL_GC_TRIGGER = 4;
055    
056      /**
057       * The number of garbage collection trigger reasons.
058       */
059      public static final int TRIGGER_REASONS = 5;
060    
061      /** Short descriptions of the garbage collection trigger reasons. */
062      protected static final String[] triggerReasons = {
063        "unknown",
064        "concurrent phase",
065        "external request",
066        "resource exhaustion",
067        "internal request"
068      };
069    
070      /**
071       * Spawn a thread to execute the supplied collector context.
072       */
073      @Interruptible
074      public abstract void spawnCollectorContext(CollectorContext context);
075    
076      /**
077       * @return The default number of collector threads to use.
078       */
079      public abstract int getDefaultThreads();
080    
081      /**
082       * @return The number of active threads.
083       *
084       */
085      public abstract int getActiveThreads();
086    
087      /**
088       * Block for the garbage collector.
089       */
090      @Unpreemptible
091      public abstract void blockForGC();
092    
093      /**
094       * Prepare a mutator for collection.
095       *
096       * @param m the mutator to prepare
097       */
098      public abstract void prepareMutator(MutatorContext m);
099    
100      /**
101       * Request each mutator flush remembered sets. This method
102       * will trigger the flush and then yield until all processors have
103       * flushed.
104       */
105      public abstract void requestMutatorFlush();
106    
107      /**
108       * Stop all mutator threads. This is current intended to be run by a single thread.
109       * <p>
110       * Fixpoint until there are no threads that we haven't blocked. Fixpoint is needed to
111       * catch the (unlikely) case that a thread spawns another thread while we are waiting.
112       */
113      @Unpreemptible
114      public abstract void stopAllMutators();
115    
116      /**
117       * Resume all mutators blocked for GC.
118       */
119      @Unpreemptible
120      public abstract void resumeAllMutators();
121    
122      /**
123       * Fail with an out of memory error.
124       */
125      public abstract void outOfMemory();
126    }