1 /* Unsafe.java - Unsafe operations needed for concurrency 2 Copyright (C) 2006, 2010 Free Software Foundation, Inc. 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 final class Unsafe 52 { 53 // Singleton class. 54 private static final Unsafe unsafe = new Unsafe(); 55 56 /** 57 * Private default constructor to prevent creation of an arbitrary 58 * number of instances. 59 */ Unsafe()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 */ getUnsafe()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 */ objectFieldOffset(Field field)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 */ compareAndSwapInt(Object obj, long offset, int expect, int update)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 */ compareAndSwapLong(Object obj, long offset, long expect, long update)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 */ compareAndSwapObject(Object obj, long offset, Object expect, Object update)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 */ putOrderedInt(Object obj, long offset, int value)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 */ putOrderedLong(Object obj, long offset, long value)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 */ putOrderedObject(Object obj, long offset, Object value)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 */ putIntVolatile(Object obj, long offset, int value)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 */ getIntVolatile(Object obj, long offset)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 */ putLongVolatile(Object obj, long offset, long value)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 */ putLong(Object obj, long offset, long value)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 */ getLongVolatile(Object obj, long offset)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 */ getLong(Object obj, long offset)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 */ putObjectVolatile(Object obj, long offset, Object value)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 */ putObject(Object obj, long offset, Object value)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 */ getObjectVolatile(Object obj, long offset)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 */ arrayBaseOffset(Class arrayClass)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 */ arrayIndexScale(Class arrayClass)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 */ unpark(Object thread)308 public native void unpark(Object 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 */ park(boolean isAbsolute, long time)326 public native void park(boolean isAbsolute, long time); 327 328 } 329