libjava/sun/misc/Unsafe.java

   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 }