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.TraceLocal;
016import org.mmtk.plan.TransitiveClosure;
017
018import org.vmmagic.pragma.Uninterruptible;
019import org.vmmagic.unboxed.*;
020
021@Uninterruptible public abstract class Scanning {
022  /**
023   * Delegated scanning of a object, processing each pointer field
024   * encountered.
025   *
026   * @param trace the trace to use for scanning
027   * @param object The object to be scanned.
028   */
029  public abstract void scanObject(TransitiveClosure trace, ObjectReference object);
030
031  /**
032   * Invoke a specialized scan method. Note that these methods must have been allocated
033   * explicitly through Plan and PlanConstraints.
034   *
035   * @param id The specialized method id
036   * @param trace The trace the method has been specialized for
037   * @param object The object to be scanned
038   */
039  public abstract void specializedScanObject(int id, TransitiveClosure trace, ObjectReference object);
040
041  /**
042   * Prepares for using the <code>computeAllRoots</code> method.  The
043   * thread counter allows multiple GC threads to co-operatively
044   * iterate through the thread data structure (if load balancing
045   * parallel GC threads were not important, the thread counter could
046   * simply be replaced by a for loop).
047   */
048  public abstract void resetThreadCounter();
049
050  /**
051   * Called the first time during a collection that thread's stacks
052   * have been scanned. This can be used (for example) to clean up
053   * obsolete compiled methods that are no longer being executed.
054   *
055   * @param partialScan whether the scan was partial or full-heap
056   */
057  public abstract void notifyInitialThreadScanComplete(boolean partialScan);
058
059  /**
060   * Computes static roots.  This method establishes all such roots for
061   * collection and places them in the root locations queue.  This method
062   * should not have side effects (such as copying or forwarding of
063   * objects).  There are a number of important preconditions:
064   *
065   * <ul>
066   * <li> All objects used in the course of GC (such as the GC thread
067   * objects) need to be "pre-copied" prior to calling this method.
068   * <li> The <code>threadCounter</code> must be reset so that load
069   * balancing parallel GC can share the work of scanning threads.
070   * </ul>
071   *
072   * @param trace The trace to use for computing roots.
073   */
074  public abstract void computeStaticRoots(TraceLocal trace);
075
076  /**
077   * Computes global roots.  This method establishes all such roots for
078   * collection and places them in the root locations queue.  This method
079   * should not have side effects (such as copying or forwarding of
080   * objects).  There are a number of important preconditions:
081   *
082   * <ul>
083   * <li> All objects used in the course of GC (such as the GC thread
084   * objects) need to be "pre-copied" prior to calling this method.
085   * <li> The <code>threadCounter</code> must be reset so that load
086   * balancing parallel GC can share the work of scanning threads.
087   * </ul>
088   *
089   * @param trace The trace to use for computing roots.
090   */
091  public abstract void computeGlobalRoots(TraceLocal trace);
092
093  /**
094   * Computes roots pointed to by threads, their associated registers
095   * and stacks.<p>
096   *
097   * This method places these roots in the root values,
098   * root locations and interior root locations queues.  This method
099   * should not have side effects (such as copying or forwarding of
100   * objects).  There are a number of important preconditions:
101   *
102   * <ul>
103   * <li> All objects used in the course of GC (such as the GC thread
104   * objects) need to be "pre-copied" prior to calling this method.
105   * <li> The <code>threadCounter</code> must be reset so that load
106   * balancing parallel GC can share the work of scanning threads.
107   * </ul>
108   *
109   * @param trace The trace to use for computing roots.
110   */
111  public abstract void computeThreadRoots(TraceLocal trace);
112
113  /**
114   * Computes new roots pointed to by threads, their associated registers
115   * and stacks.   This method is only required to return roots that are
116   * new since the last stack scan (if possible, the implementation will
117   * optimize the scanning to only scan new portions of the stacks).<p>
118   *
119   * This method places these roots in the root values,
120   * root locations and interior root locations queues.  This method
121   * should not have side effects (such as copying or forwarding of
122   * objects).  There are a number of important preconditions:
123   *
124   * <ul>
125   * <li> All objects used in the course of GC (such as the GC thread
126   * objects) need to be "pre-copied" prior to calling this method.
127   * <li> The <code>threadCounter</code> must be reset so that load
128   * balancing parallel GC can share the work of scanning threads.
129   * </ul>
130   *
131   * @param trace The trace to use for computing roots.
132   */
133  public abstract void computeNewThreadRoots(TraceLocal trace);
134
135  /**
136   * Compute all roots out of the VM's boot image (if any).  This method is a no-op
137   * in the case where the VM does not maintain an MMTk-visible Java space.   However,
138   * when the VM does maintain a space (such as a boot image) which is visible to MMTk,
139   * that space could either be scanned by MMTk as part of its transitive closure over
140   * the whole heap, or as a (considerable) performance optimization, MMTk could avoid
141   * scanning the space if it is aware of all pointers out of that space.  This method
142   * is used to establish the root set out of the scannable space in the case where
143   * such a space exists.
144   *
145   * @param trace The trace object to use to report root locations.
146   */
147  public abstract void computeBootImageRoots(TraceLocal trace);
148
149  /**
150   * @return true if the runtime supports a return barrier
151   */
152  public abstract boolean supportsReturnBarrier();
153}