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.vmmagic.pragma.Uninterruptible;
016    import org.vmmagic.unboxed.*;
017    
018    @Uninterruptible
019    public 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       * Return the next object in the heap under contiguous allocation
096       */
097      public abstract ObjectReference getNextObject(ObjectReference object);
098    
099      /**
100       * Return an object reference from knowledge of the low order word
101       */
102      public abstract ObjectReference getObjectFromStartAddress(Address start);
103      /**
104       * Gets a pointer to the address just past the end of the object.
105       *
106       * @param object The objecty.
107       */
108      public abstract Address getObjectEndAddress(ObjectReference object);
109    
110    
111      /**
112       * Get the type descriptor for an object.
113       *
114       * @param ref address of the object
115       * @return byte array with the type descriptor
116       */
117      public abstract byte[] getTypeDescriptor(ObjectReference ref);
118    
119      /**
120       * Is the passed object an array?
121       *
122       * @param object address of the object
123       */
124      public abstract boolean isArray(ObjectReference object);
125    
126      /**
127       * Is the passed object a primitive array?
128       *
129       * @param object address of the object
130       */
131      public abstract boolean isPrimitiveArray(ObjectReference object);
132    
133      /**
134       * Get the length of an array object.
135       *
136       * @param object address of the object
137       * @return The array length, in elements
138       */
139      public abstract int getArrayLength(ObjectReference object);
140    
141      /**
142       * Attempts to set the bits available for memory manager use in an
143       * object.  The attempt will only be successful if the current value
144       * of the bits matches <code>oldVal</code>.  The comparison with the
145       * current value and setting are atomic with respect to other
146       * allocators.
147       *
148       * @param object the address of the object
149       * @param oldVal the required current value of the bits
150       * @param newVal the desired new value of the bits
151       * @return <code>true</code> if the bits were set,
152       * <code>false</code> otherwise
153       */
154      public abstract boolean attemptAvailableBits(ObjectReference object,
155          Word oldVal, Word newVal);
156    
157      /**
158       * Gets the value of bits available for memory manager use in an
159       * object, in preparation for setting those bits.
160       *
161       * @param object the address of the object
162       * @return the value of the bits
163       */
164      public abstract Word prepareAvailableBits(ObjectReference object);
165    
166      /**
167       * Sets the byte available for memory manager use in an object.
168       *
169       * @param object the address of the object
170       * @param val the new value of the byte
171       */
172      public abstract void writeAvailableByte(ObjectReference object, byte val);
173      /**
174       * Read the byte available for memory manager use in an object.
175       *
176       * @param object the address of the object
177       * @return the value of the byte
178       */
179      public abstract byte readAvailableByte(ObjectReference object);
180    
181      /**
182       * Sets the bits available for memory manager use in an object.
183       *
184       * @param object the address of the object
185       * @param val the new value of the bits
186       */
187      public abstract void writeAvailableBitsWord(ObjectReference object, Word val);
188      /**
189       * Read the bits available for memory manager use in an object.
190       *
191       * @param object the address of the object
192       * @return the value of the bits
193       */
194      public abstract Word readAvailableBitsWord(ObjectReference object);
195    
196      /**
197       * Gets the offset of the memory management header from the object
198       * reference address.  XXX The object model / memory manager
199       * interface should be improved so that the memory manager does not
200       * need to know this.
201       *
202       * @return the offset, relative the object reference address
203       */
204      public abstract Offset GC_HEADER_OFFSET();
205    
206      /**
207       * Returns the lowest address of the storage associated with an object.
208       *
209       * @param object the reference address of the object
210       * @return the lowest address of the object
211       */
212      public abstract Address objectStartRef(ObjectReference object);
213    
214      /**
215       * Returns an address guaranteed to be inside the storage assocatied
216       * with and object.
217       *
218       * @param object the reference address of the object
219       * @return an address inside the object
220       */
221      public abstract Address refToAddress(ObjectReference object);
222    
223      /**
224       * Checks if a reference of the given type in another object is
225       * inherently acyclic.  The type is given as a TIB.
226       *
227       * @return <code>true</code> if a reference of the type is
228       * inherently acyclic
229       */
230      public abstract boolean isAcyclic(ObjectReference typeRef);
231    
232      /**
233       * Dump debugging information for an object.
234       *
235       * @param object The object whose information is to be dumped
236       */
237      public abstract void dumpObject(ObjectReference object);
238    
239      /*
240       * NOTE: The following methods must be implemented by subclasses of this
241       * class, but are internal to the VM<->MM interface glue, so are never
242       * called by MMTk users.
243       */
244      /** @return The offset from array reference to element zero */
245      protected abstract Offset getArrayBaseOffset();
246    
247      /*
248       * NOTE: These methods should not be called by anything other than the
249       * reflective mechanisms in org.mmtk.vm.VM, and are not implemented by
250       * subclasses.
251       *
252       * This hack exists only to allow us to declare the respective
253       * methods as protected.
254       */
255      static Offset arrayBaseOffsetTrapdoor(ObjectModel o) {
256        return o.getArrayBaseOffset();
257      }
258    }