Java Source Code: sun.misc.Unsafe


   1: /* Unsafe.java - Unsafe operations needed for concurrency
   2:    Copyright (C) 2006 Free Software Foundation
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package sun.misc;
  39: 
  40: import java.lang.reflect.Field;
  41: 
  42: /**
  43:  * This class should provide access to low-level operations and its
  44:  * use should be limited to trusted code.  Fields can be accessed using
  45:  * memory addresses, with undefined behaviour occurring if invalid memory
  46:  * addresses are given.
  47:  *
  48:  * @author Tom Tromey (tromey@redhat.com)
  49:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  50:  */
  51: public class Unsafe
  52:	  {
  53:  // Singleton class.
  54:  private static Unsafe unsafe = new Unsafe();
  55:
  56:  /**
  57:   * Private default constructor to prevent creation of an arbitrary
  58:   * number of instances.
  59:   */
  60:  private Unsafe()
  61:	    {
  62:  }
  63:
  64:  /**
  65:   * Retrieve the singleton instance of <code>Unsafe</code>.  The calling
  66:   * method should guard this instance from untrusted code, as it provides
  67:   * access to low-level operations such as direct memory access.
  68:   *
  69:   * @throws SecurityException if a security manager exists and prevents
  70:   *                           access to the system properties.
  71:   */
  72:  public static Unsafe getUnsafe()
  73:	    {
  74:    SecurityManager sm = System.getSecurityManager();
  75:    if (sm != null)
  76:      sm.checkPropertiesAccess();
  77:    return unsafe;
  78:  }
  79:  
  80:  /**
  81:   * Returns the memory address offset of the given static field.
  82:   * The offset is merely used as a means to access a particular field
  83:   * in the other methods of this class.  The value is unique to the given
  84:   * field and the same value should be returned on each subsequent call.
  85:   *
  86:   * @param field the field whose offset should be returned.
  87:   * @return the offset of the given field.
  88:   */
  89:  public native long objectFieldOffset(Field field);
  90:
  91:  /**
  92:   * Compares the value of the integer field at the specified offset
  93:   * in the supplied object with the given expected value, and updates
  94:   * it if they match.  The operation of this method should be atomic,
  95:   * thus providing an uninterruptible way of updating an integer field.
  96:   *
  97:   * @param obj the object containing the field to modify.
  98:   * @param offset the offset of the integer field within <code>obj</code>.
  99:   * @param expect the expected value of the field.
 100:   * @param update the new value of the field if it equals <code>expect</code>.
 101:   * @return true if the field was changed.
 102:   */
 103:  public native boolean compareAndSwapInt(Object obj, long offset,
 104:                                          int expect, int update);
 105:
 106:  /**
 107:   * Compares the value of the long field at the specified offset
 108:   * in the supplied object with the given expected value, and updates
 109:   * it if they match.  The operation of this method should be atomic,
 110:   * thus providing an uninterruptible way of updating a long field.
 111:   *
 112:   * @param obj the object containing the field to modify.
 113:   * @param offset the offset of the long field within <code>obj</code>.
 114:   * @param expect the expected value of the field.
 115:   * @param update the new value of the field if it equals <code>expect</code>.
 116:   * @return true if the field was changed.
 117:   */
 118:  public native boolean compareAndSwapLong(Object obj, long offset,
 119:                                           long expect, long update);
 120:
 121:  /**
 122:   * Compares the value of the object field at the specified offset
 123:   * in the supplied object with the given expected value, and updates
 124:   * it if they match.  The operation of this method should be atomic,
 125:   * thus providing an uninterruptible way of updating an object field.
 126:   *
 127:   * @param obj the object containing the field to modify.
 128:   * @param offset the offset of the object field within <code>obj</code>.
 129:   * @param expect the expected value of the field.
 130:   * @param update the new value of the field if it equals <code>expect</code>.
 131:   * @return true if the field was changed.
 132:   */
 133:  public native boolean compareAndSwapObject(Object obj, long offset,
 134:                                             Object expect, Object update);
 135:
 136:  /**
 137:   * Sets the value of the integer field at the specified offset in the
 138:   * supplied object to the given value.  This is an ordered or lazy
 139:   * version of <code>putIntVolatile(Object,long,int)</code>, which
 140:   * doesn't guarantee the immediate visibility of the change to other
 141:   * threads.  It is only really useful where the integer field is
 142:   * <code>volatile</code>, and is thus expected to change unexpectedly.
 143:   *
 144:   * @param obj the object containing the field to modify.
 145:   * @param offset the offset of the integer field within <code>obj</code>.
 146:   * @param value the new value of the field.
 147:   * @see #putIntVolatile(Object,long,int)
 148:   */
 149:  public native void putOrderedInt(Object obj, long offset, int value);
 150:
 151:  /**
 152:   * Sets the value of the long field at the specified offset in the
 153:   * supplied object to the given value.  This is an ordered or lazy
 154:   * version of <code>putLongVolatile(Object,long,long)</code>, which
 155:   * doesn't guarantee the immediate visibility of the change to other
 156:   * threads.  It is only really useful where the long field is
 157:   * <code>volatile</code>, and is thus expected to change unexpectedly.
 158:   *
 159:   * @param obj the object containing the field to modify.
 160:   * @param offset the offset of the long field within <code>obj</code>.
 161:   * @param value the new value of the field.
 162:   * @see #putLongVolatile(Object,long,long)
 163:   */
 164:  public native void putOrderedLong(Object obj, long offset, long value);
 165:
 166:  /**
 167:   * Sets the value of the object field at the specified offset in the
 168:   * supplied object to the given value.  This is an ordered or lazy
 169:   * version of <code>putObjectVolatile(Object,long,Object)</code>, which
 170:   * doesn't guarantee the immediate visibility of the change to other
 171:   * threads.  It is only really useful where the object field is
 172:   * <code>volatile</code>, and is thus expected to change unexpectedly.
 173:   *
 174:   * @param obj the object containing the field to modify.
 175:   * @param offset the offset of the object field within <code>obj</code>.
 176:   * @param value the new value of the field.
 177:   */
 178:  public native void putOrderedObject(Object obj, long offset, Object value);
 179:
 180:  /**
 181:   * Sets the value of the integer field at the specified offset in the
 182:   * supplied object to the given value, with volatile store semantics.
 183:   *
 184:   * @param obj the object containing the field to modify.
 185:   * @param offset the offset of the integer field within <code>obj</code>.
 186:   * @param value the new value of the field.
 187:   */
 188:  public native void putIntVolatile(Object obj, long offset, int value);
 189:
 190:  /**
 191:   * Retrieves the value of the integer field at the specified offset in the
 192:   * supplied object with volatile load semantics.
 193:   *
 194:   * @param obj the object containing the field to read.
 195:   * @param offset the offset of the integer field within <code>obj</code>.
 196:   */
 197:  public native int getIntVolatile(Object obj, long offset);
 198:
 199:  /**
 200:   * Sets the value of the long field at the specified offset in the
 201:   * supplied object to the given value, with volatile store semantics.
 202:   *
 203:   * @param obj the object containing the field to modify.
 204:   * @param offset the offset of the long field within <code>obj</code>.
 205:   * @param value the new value of the field.
 206:   * @see #putLong(Object,long,long)
 207:   */
 208:  public native void putLongVolatile(Object obj, long offset, long value);
 209:
 210:  /**
 211:   * Sets the value of the long field at the specified offset in the
 212:   * supplied object to the given value.
 213:   *
 214:   * @param obj the object containing the field to modify.
 215:   * @param offset the offset of the long field within <code>obj</code>.
 216:   * @param value the new value of the field.
 217:   * @see #putLongVolatile(Object,long,long)
 218:   */
 219:  public native void putLong(Object obj, long offset, long value);
 220:
 221:  /**
 222:   * Retrieves the value of the long field at the specified offset in the
 223:   * supplied object with volatile load semantics.
 224:   *
 225:   * @param obj the object containing the field to read.
 226:   * @param offset the offset of the long field within <code>obj</code>.
 227:   * @see #getLong(Object,long)
 228:   */
 229:  public native long getLongVolatile(Object obj, long offset);
 230:
 231:  /**
 232:   * Retrieves the value of the long field at the specified offset in the
 233:   * supplied object.
 234:   *
 235:   * @param obj the object containing the field to read.
 236:   * @param offset the offset of the long field within <code>obj</code>.
 237:   * @see #getLongVolatile(Object,long)
 238:   */
 239:  public native long getLong(Object obj, long offset);
 240:
 241:  /**
 242:   * Sets the value of the object field at the specified offset in the
 243:   * supplied object to the given value, with volatile store semantics.
 244:   *
 245:   * @param obj the object containing the field to modify.
 246:   * @param offset the offset of the object field within <code>obj</code>.
 247:   * @param value the new value of the field.
 248:   * @see #putObject(Object,long,Object)
 249:   */
 250:  public native void putObjectVolatile(Object obj, long offset, Object value);
 251:
 252:  /**
 253:   * Sets the value of the object field at the specified offset in the
 254:   * supplied object to the given value.
 255:   *
 256:   * @param obj the object containing the field to modify.
 257:   * @param offset the offset of the object field within <code>obj</code>.
 258:   * @param value the new value of the field.
 259:   * @see #putObjectVolatile(Object,long,Object)
 260:   */
 261:  public native void putObject(Object obj, long offset, Object value);
 262:
 263:  /**
 264:   * Retrieves the value of the object field at the specified offset in the
 265:   * supplied object with volatile load semantics.
 266:   *
 267:   * @param obj the object containing the field to read.
 268:   * @param offset the offset of the object field within <code>obj</code>.
 269:   */
 270:  public native Object getObjectVolatile(Object obj, long offset);
 271:
 272:  /**
 273:   * Returns the offset of the first element for a given array class.
 274:   * To access elements of the array class, this value may be used along
 275:   * with that returned by 
 276:   * <a href="#arrayIndexScale"><code>arrayIndexScale</code></a>,
 277:   * if non-zero.
 278:   *
 279:   * @param arrayClass the class for which the first element's address should
 280:   *                   be obtained.
 281:   * @return the offset of the first element of the array class.
 282:   * @see arrayIndexScale(Class)
 283:   */
 284:  public native int arrayBaseOffset(Class arrayClass);
 285:
 286:  /**
 287:   * Returns the scale factor used for addressing elements of the supplied
 288:   * array class.  Where a suitable scale factor can not be returned (e.g.
 289:   * for primitive types), zero should be returned.  The returned value
 290:   * can be used with 
 291:   * <a href="#arrayBaseOffset"><code>arrayBaseOffset</code></a>
 292:   * to access elements of the class.
 293:   *
 294:   * @param arrayClass the class whose scale factor should be returned.
 295:   * @return the scale factor, or zero if not supported for this array class.
 296:   */
 297:  public native int arrayIndexScale(Class arrayClass);
 298:  
 299:  /**
 300:   * Releases the block on a thread created by 
 301:   * <a href="#park"><code>park</code></a>.  This method can also be used
 302:   * to terminate a blockage caused by a prior call to <code>park</code>.
 303:   * This operation is unsafe, as the thread must be guaranteed to be
 304:   * live.  This is true of Java, but not native code.
 305:   *
 306:   * @param thread the thread to unblock.
 307:   */
 308:  public native void unpark(Thread thread);
 309:
 310:  /**
 311:   * Blocks the thread until a matching 
 312:   * <a href="#unpark"><code>unpark</code></a> occurs, the thread is
 313:   * interrupted or the optional timeout expires.  If an <code>unpark</code>
 314:   * call has already occurred, this also counts.  A timeout value of zero
 315:   * is defined as no timeout.  When <code>isAbsolute</code> is
 316:   * <code>true</code>, the timeout is in milliseconds relative to the
 317:   * epoch.  Otherwise, the value is the number of nanoseconds which must
 318:   * occur before timeout.  This call may also return spuriously (i.e.
 319:   * for no apparent reason).
 320:   *
 321:   * @param isAbsolute true if the timeout is specified in milliseconds from
 322:   *                   the epoch.
 323:   * @param time either the number of nanoseconds to wait, or a time in
 324:   *             milliseconds from the epoch to wait for.
 325:   */
 326:  public native void park(boolean isAbsolute, long time);
 327:
 328:}