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 */
013package org.mmtk.vm;
014
015import org.mmtk.plan.CollectorContext;
016import org.mmtk.plan.MutatorContext;
017
018import 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   * Spawns a thread to execute the supplied collector context.
072   *
073   * @param context the context to execute
074   */
075  @Interruptible
076  public abstract void spawnCollectorContext(CollectorContext context);
077
078  /**
079   * @return The default number of collector threads to use.
080   */
081  public abstract int getDefaultThreads();
082
083  /**
084   * @return The number of active threads.
085   *
086   */
087  public abstract int getActiveThreads();
088
089  /**
090   * Block for the garbage collector.
091   */
092  @Unpreemptible
093  public abstract void blockForGC();
094
095  /**
096   * Prepare a mutator for collection.
097   *
098   * @param m the mutator to prepare
099   */
100  public abstract void prepareMutator(MutatorContext m);
101
102  /**
103   * Request each mutator flush remembered sets. This method
104   * will trigger the flush and then yield until all processors have
105   * flushed.
106   */
107  public abstract void requestMutatorFlush();
108
109  /**
110   * Stop all mutator threads. This is current intended to be run by a single thread.
111   * <p>
112   * Fixpoint until there are no threads that we haven't blocked. Fixpoint is needed to
113   * catch the (unlikely) case that a thread spawns another thread while we are waiting.
114   */
115  @Unpreemptible
116  public abstract void stopAllMutators();
117
118  /**
119   * Resume all mutators blocked for GC.
120   */
121  @Unpreemptible
122  public abstract void resumeAllMutators();
123
124  /**
125   * Fail with an out of memory error.
126   */
127  public abstract void outOfMemory();
128}