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.vmmagic.pragma.Uninterruptible;
016import org.vmmagic.unboxed.*;
017
018@Uninterruptible
019public abstract class ObjectModel {
020
021  /**
022   * Copy an object using a plan's allocCopy to get space and install
023   * the forwarding pointer.  On entry, <code>from</code> must have
024   * been reserved for copying by the caller.  This method calls the
025   * plan's <code>getStatusForCopy()</code> method to establish a new
026   * status word for the copied object and <code>postCopy()</code> to
027   * allow the plan to perform any post copy actions.
028   *
029   * @param from the address of the object to be copied
030   * @param allocator The allocator to use.
031   * @return the address of the new object
032   */
033  public abstract ObjectReference copy(ObjectReference from, int allocator);
034
035  /**
036   * Copy an object to be pointer to by the to address. This is required
037   * for delayed-copy collectors such as compacting collectors. During the
038   * collection, MMTk reserves a region in the heap for an object as per
039   * requirements found from ObjectModel and then asks ObjectModel to
040   * determine what the object's reference will be post-copy.
041   *
042   * @param from the address of the object to be copied
043   * @param to The target location.
044   * @param region The start of the region that was reserved for this object
045   * @return Address The address past the end of the copied object
046   */
047  public abstract Address copyTo(ObjectReference from, ObjectReference to, Address region);
048
049  /**
050   * Return the reference that an object will be referred to after it is copied
051   * to the specified region. Used in delayed-copy collectors such as compacting
052   * collectors.
053   *
054   * @param from The object to be copied.
055   * @param to The region to be copied to.
056   * @return The resulting reference.
057   */
058  public abstract ObjectReference getReferenceWhenCopiedTo(ObjectReference from, Address to);
059
060
061  /**
062   * Return the size required to copy an object
063   *
064   * @param object The object whose size is to be queried
065   * @return The size required to copy <code>obj</code>
066   */
067  public abstract int getSizeWhenCopied(ObjectReference object);
068
069  /**
070   * Return the alignment requirement for a copy of this object
071   *
072   * @param object The object whose size is to be queried
073   * @return The alignment required for a copy of <code>obj</code>
074   */
075  public abstract int getAlignWhenCopied(ObjectReference object);
076
077  /**
078   * Return the alignment offset requirements for a copy of this object
079   *
080   * @param object The object whose size is to be queried
081   * @return The alignment offset required for a copy of <code>obj</code>
082   */
083  public abstract int getAlignOffsetWhenCopied(ObjectReference object);
084
085
086  /**
087   * Return the size used by an object
088   *
089   * @param object The object whose size is to be queried
090   * @return The size of <code>obj</code>
091   */
092  public abstract int getCurrentSize(ObjectReference object);
093
094  /**
095   * @param object the current object
096   * @return the object reference for the next object in the heap under
097   *  contiguous allocation
098   */
099  public abstract ObjectReference getNextObject(ObjectReference object);
100
101  /**
102   * @param start the start address of the object
103   * @return an object reference from knowledge of the low order word
104   */
105  public abstract ObjectReference getObjectFromStartAddress(Address start);
106  /**
107   * Gets a pointer to the address just past the end of the object.
108   *
109   * @param object The object
110   * @return the address of the first word after the the object
111   */
112  public abstract Address getObjectEndAddress(ObjectReference object);
113
114
115  /**
116   * Get the type descriptor for an object.
117   *
118   * @param ref address of the object
119   * @return byte array with the type descriptor
120   */
121  public abstract byte[] getTypeDescriptor(ObjectReference ref);
122
123  /**
124   * @param object address of the object
125   * @return whether the passed object is an array
126   */
127  public abstract boolean isArray(ObjectReference object);
128
129  /**
130   * @param object address of the object
131   * @return whether the passed object is a primitive array
132   */
133  public abstract boolean isPrimitiveArray(ObjectReference object);
134
135  /**
136   * Get the length of an array object.
137   *
138   * @param object address of the object
139   * @return The array length, in elements
140   */
141  public abstract int getArrayLength(ObjectReference object);
142
143  /**
144   * Attempts to set the bits available for memory manager use in an
145   * object.  The attempt will only be successful if the current value
146   * of the bits matches <code>oldVal</code>.  The comparison with the
147   * current value and setting are atomic with respect to other
148   * allocators.
149   *
150   * @param object the address of the object
151   * @param oldVal the required current value of the bits
152   * @param newVal the desired new value of the bits
153   * @return <code>true</code> if the bits were set,
154   * <code>false</code> otherwise
155   */
156  public abstract boolean attemptAvailableBits(ObjectReference object,
157      Word oldVal, Word newVal);
158
159  /**
160   * Gets the value of bits available for memory manager use in an
161   * object, in preparation for setting those bits.
162   *
163   * @param object the address of the object
164   * @return the value of the bits
165   */
166  public abstract Word prepareAvailableBits(ObjectReference object);
167
168  /**
169   * Sets the byte available for memory manager use in an object.
170   *
171   * @param object the address of the object
172   * @param val the new value of the byte
173   */
174  public abstract void writeAvailableByte(ObjectReference object, byte val);
175  /**
176   * Read the byte available for memory manager use in an object.
177   *
178   * @param object the address of the object
179   * @return the value of the byte
180   */
181  public abstract byte readAvailableByte(ObjectReference object);
182
183  /**
184   * Sets the bits available for memory manager use in an object.
185   *
186   * @param object the address of the object
187   * @param val the new value of the bits
188   */
189  public abstract void writeAvailableBitsWord(ObjectReference object, Word val);
190  /**
191   * Read the bits available for memory manager use in an object.
192   *
193   * @param object the address of the object
194   * @return the value of the bits
195   */
196  public abstract Word readAvailableBitsWord(ObjectReference object);
197
198  /**
199   * Gets the offset of the memory management header from the object
200   * reference address.  XXX The object model / memory manager
201   * interface should be improved so that the memory manager does not
202   * need to know this.
203   *
204   * @return the offset, relative the object reference address
205   */
206  public abstract Offset GC_HEADER_OFFSET();
207
208  /**
209   * Returns the lowest address of the storage associated with an object.
210   *
211   * @param object the reference address of the object
212   * @return the lowest address of the object
213   */
214  public abstract Address objectStartRef(ObjectReference object);
215
216  /**
217   * Returns an address guaranteed to be inside the storage assocatied
218   * with and object.
219   *
220   * @param object the reference address of the object
221   * @return an address inside the object
222   */
223  public abstract Address refToAddress(ObjectReference object);
224
225  /**
226   * Checks if a reference of the given type in another object is
227   * inherently acyclic.  The type is given as a TIB.
228   *
229   * @param typeRef the type of the reference (as a TIB)
230   * @return <code>true</code> if a reference of the type is
231   * inherently acyclic
232   */
233  public abstract boolean isAcyclic(ObjectReference typeRef);
234
235  /**
236   * Dump debugging information for an object.
237   *
238   * @param object The object whose information is to be dumped
239   */
240  public abstract void dumpObject(ObjectReference object);
241
242  /*
243   * NOTE: The following methods must be implemented by subclasses of this
244   * class, but are internal to the VM<->MM interface glue, so are never
245   * called by MMTk users.
246   */
247  /** @return The offset from array reference to element zero */
248  protected abstract Offset getArrayBaseOffset();
249
250  /*
251   * NOTE: These methods should not be called by anything other than the
252   * reflective mechanisms in org.mmtk.vm.VM, and are not implemented by
253   * subclasses.
254   *
255   * This hack exists only to allow us to declare the respective
256   * methods as protected.
257   */
258  static Offset arrayBaseOffsetTrapdoor(ObjectModel o) {
259    return o.getArrayBaseOffset();
260  }
261}