1 /*
2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package sun.misc;
27
28 import java.security.*;
29 import java.lang.reflect.*;
30
31 import sun.reflect.CallerSensitive;
32 import sun.reflect.Reflection;
33
34
35 /**
36 * A collection of methods for performing low-level, unsafe operations.
37 * Although the class and all methods are public, use of this class is
38 * limited because only trusted code can obtain instances of it.
39 *
40 * @author John R. Rose
41 * @see #getUnsafe
42 */
43
44 public final class Unsafe {
45
46 private static native void registerNatives();
47 static {
48 registerNatives();
49 sun.reflect.Reflection.registerMethodsToFilter(Unsafe.class, "getUnsafe");
50 }
51
52 private Unsafe() {}
53
54 private static final Unsafe theUnsafe = new Unsafe();
55
56 /**
57 * Provides the caller with the capability of performing unsafe
58 * operations.
59 *
60 * <p> The returned <code>Unsafe</code> object should be carefully guarded
61 * by the caller, since it can be used to read and write data at arbitrary
62 * memory addresses. It must never be passed to untrusted code.
63 *
64 * <p> Most methods in this class are very low-level, and correspond to a
65 * small number of hardware instructions (on typical machines). Compilers
66 * are encouraged to optimize these methods accordingly.
67 *
68 * <p> Here is a suggested idiom for using unsafe operations:
69 *
70 * <blockquote><pre>
71 * class MyTrustedClass {
72 * private static final Unsafe unsafe = Unsafe.getUnsafe();
73 * ...
74 * private long myCountAddress = ...;
75 * public int getCount() { return unsafe.getByte(myCountAddress); }
76 * }
77 * </pre></blockquote>
78 *
79 * (It may assist compilers to make the local variable be
80 * <code>final</code>.)
81 *
82 * @exception SecurityException if a security manager exists and its
83 * <code>checkPropertiesAccess</code> method doesn't allow
84 * access to the system properties.
85 */
86 @CallerSensitive
87 public static Unsafe getUnsafe() {
88 Class<?> caller = Reflection.getCallerClass();
89 if (!VM.isSystemDomainLoader(caller.getClassLoader()))
90 throw new SecurityException("Unsafe");
91 return theUnsafe;
92 }
93
94 /// peek and poke operations
95 /// (compilers should optimize these to memory ops)
96
97 // These work on object fields in the Java heap.
98 // They will not work on elements of packed arrays.
99
100 /**
101 * Fetches a value from a given Java variable.
102 * More specifically, fetches a field or array element within the given
103 * object <code>o</code> at the given offset, or (if <code>o</code> is
104 * null) from the memory address whose numerical value is the given
105 * offset.
106 * <p>
107 * The results are undefined unless one of the following cases is true:
108 * <ul>
109 * <li>The offset was obtained from {@link #objectFieldOffset} on
110 * the {@link java.lang.reflect.Field} of some Java field and the object
111 * referred to by <code>o</code> is of a class compatible with that
112 * field's class.
113 *
114 * <li>The offset and object reference <code>o</code> (either null or
115 * non-null) were both obtained via {@link #staticFieldOffset}
116 * and {@link #staticFieldBase} (respectively) from the
117 * reflective {@link Field} representation of some Java field.
118 *
119 * <li>The object referred to by <code>o</code> is an array, and the offset
120 * is an integer of the form <code>B+N*S</code>, where <code>N</code> is
121 * a valid index into the array, and <code>B</code> and <code>S</code> are
122 * the values obtained by {@link #arrayBaseOffset} and {@link
123 * #arrayIndexScale} (respectively) from the array's class. The value
124 * referred to is the <code>N</code><em>th</em> element of the array.
125 *
126 * </ul>
127 * <p>
128 * If one of the above cases is true, the call references a specific Java
129 * variable (field or array element). However, the results are undefined
130 * if that variable is not in fact of the type returned by this method.
131 * <p>
132 * This method refers to a variable by means of two parameters, and so
133 * it provides (in effect) a <em>double-register</em> addressing mode
134 * for Java variables. When the object reference is null, this method
135 * uses its offset as an absolute address. This is similar in operation
136 * to methods such as {@link #getInt(long)}, which provide (in effect) a
137 * <em>single-register</em> addressing mode for non-Java variables.
138 * However, because Java variables may have a different layout in memory
139 * from non-Java variables, programmers should not assume that these
140 * two addressing modes are ever equivalent. Also, programmers should
141 * remember that offsets from the double-register addressing mode cannot
142 * be portably confused with longs used in the single-register addressing
143 * mode.
144 *
145 * @param o Java heap object in which the variable resides, if any, else
146 * null
147 * @param offset indication of where the variable resides in a Java heap
148 * object, if any, else a memory address locating the variable
149 * statically
150 * @return the value fetched from the indicated Java variable
151 * @throws RuntimeException No defined exceptions are thrown, not even
152 * {@link NullPointerException}
153 */
154 public native int getInt(Object o, long offset);
155
156 /**
157 * Stores a value into a given Java variable.
158 * <p>
159 * The first two parameters are interpreted exactly as with
160 * {@link #getInt(Object, long)} to refer to a specific
161 * Java variable (field or array element). The given value
162 * is stored into that variable.
163 * <p>
164 * The variable must be of the same type as the method
165 * parameter <code>x</code>.
166 *
167 * @param o Java heap object in which the variable resides, if any, else
168 * null
169 * @param offset indication of where the variable resides in a Java heap
170 * object, if any, else a memory address locating the variable
171 * statically
172 * @param x the value to store into the indicated Java variable
173 * @throws RuntimeException No defined exceptions are thrown, not even
174 * {@link NullPointerException}
175 */
176 public native void putInt(Object o, long offset, int x);
177
178 /**
179 * Fetches a reference value from a given Java variable.
180 * @see #getInt(Object, long)
181 */
182 public native Object getObject(Object o, long offset);
183
184 /**
185 * Stores a reference value into a given Java variable.
186 * <p>
187 * Unless the reference <code>x</code> being stored is either null
188 * or matches the field type, the results are undefined.
189 * If the reference <code>o</code> is non-null, car marks or
190 * other store barriers for that object (if the VM requires them)
191 * are updated.
192 * @see #putInt(Object, int, int)
193 */
194 public native void putObject(Object o, long offset, Object x);
195
196 /** @see #getInt(Object, long) */
197 public native boolean getBoolean(Object o, long offset);
198 /** @see #putInt(Object, int, int) */
199 public native void putBoolean(Object o, long offset, boolean x);
200 /** @see #getInt(Object, long) */
201 public native byte getByte(Object o, long offset);
202 /** @see #putInt(Object, int, int) */
203 public native void putByte(Object o, long offset, byte x);
204 /** @see #getInt(Object, long) */
205 public native short getShort(Object o, long offset);
206 /** @see #putInt(Object, int, int) */
207 public native void putShort(Object o, long offset, short x);
208 /** @see #getInt(Object, long) */
209 public native char getChar(Object o, long offset);
210 /** @see #putInt(Object, int, int) */
211 public native void putChar(Object o, long offset, char x);
212 /** @see #getInt(Object, long) */
213 public native long getLong(Object o, long offset);
214 /** @see #putInt(Object, int, int) */
215 public native void putLong(Object o, long offset, long x);
216 /** @see #getInt(Object, long) */
217 public native float getFloat(Object o, long offset);
218 /** @see #putInt(Object, int, int) */
219 public native void putFloat(Object o, long offset, float x);
220 /** @see #getInt(Object, long) */
221 public native double getDouble(Object o, long offset);
222 /** @see #putInt(Object, int, int) */
223 public native void putDouble(Object o, long offset, double x);
224
225 /**
226 * This method, like all others with 32-bit offsets, was native
227 * in a previous release but is now a wrapper which simply casts
228 * the offset to a long value. It provides backward compatibility
229 * with bytecodes compiled against 1.4.
230 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
231 * See {@link #staticFieldOffset}.
232 */
233 @Deprecated
234 public int getInt(Object o, int offset) {
235 return getInt(o, (long)offset);
236 }
237
238 /**
239 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
240 * See {@link #staticFieldOffset}.
241 */
242 @Deprecated
243 public void putInt(Object o, int offset, int x) {
244 putInt(o, (long)offset, x);
245 }
246
247 /**
248 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
249 * See {@link #staticFieldOffset}.
250 */
251 @Deprecated
252 public Object getObject(Object o, int offset) {
253 return getObject(o, (long)offset);
254 }
255
256 /**
257 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
258 * See {@link #staticFieldOffset}.
259 */
260 @Deprecated
261 public void putObject(Object o, int offset, Object x) {
262 putObject(o, (long)offset, x);
263 }
264
265 /**
266 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
267 * See {@link #staticFieldOffset}.
268 */
269 @Deprecated
270 public boolean getBoolean(Object o, int offset) {
271 return getBoolean(o, (long)offset);
272 }
273
274 /**
275 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
276 * See {@link #staticFieldOffset}.
277 */
278 @Deprecated
279 public void putBoolean(Object o, int offset, boolean x) {
280 putBoolean(o, (long)offset, x);
281 }
282
283 /**
284 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
285 * See {@link #staticFieldOffset}.
286 */
287 @Deprecated
288 public byte getByte(Object o, int offset) {
289 return getByte(o, (long)offset);
290 }
291
292 /**
293 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
294 * See {@link #staticFieldOffset}.
295 */
296 @Deprecated
297 public void putByte(Object o, int offset, byte x) {
298 putByte(o, (long)offset, x);
299 }
300
301 /**
302 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
303 * See {@link #staticFieldOffset}.
304 */
305 @Deprecated
306 public short getShort(Object o, int offset) {
307 return getShort(o, (long)offset);
308 }
309
310 /**
311 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
312 * See {@link #staticFieldOffset}.
313 */
314 @Deprecated
315 public void putShort(Object o, int offset, short x) {
316 putShort(o, (long)offset, x);
317 }
318
319 /**
320 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
321 * See {@link #staticFieldOffset}.
322 */
323 @Deprecated
324 public char getChar(Object o, int offset) {
325 return getChar(o, (long)offset);
326 }
327
328 /**
329 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
330 * See {@link #staticFieldOffset}.
331 */
332 @Deprecated
333 public void putChar(Object o, int offset, char x) {
334 putChar(o, (long)offset, x);
335 }
336
337 /**
338 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
339 * See {@link #staticFieldOffset}.
340 */
341 @Deprecated
342 public long getLong(Object o, int offset) {
343 return getLong(o, (long)offset);
344 }
345
346 /**
347 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
348 * See {@link #staticFieldOffset}.
349 */
350 @Deprecated
351 public void putLong(Object o, int offset, long x) {
352 putLong(o, (long)offset, x);
353 }
354
355 /**
356 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
357 * See {@link #staticFieldOffset}.
358 */
359 @Deprecated
360 public float getFloat(Object o, int offset) {
361 return getFloat(o, (long)offset);
362 }
363
364 /**
365 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
366 * See {@link #staticFieldOffset}.
367 */
368 @Deprecated
369 public void putFloat(Object o, int offset, float x) {
370 putFloat(o, (long)offset, x);
371 }
372
373 /**
374 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
375 * See {@link #staticFieldOffset}.
376 */
377 @Deprecated
378 public double getDouble(Object o, int offset) {
379 return getDouble(o, (long)offset);
380 }
381
382 /**
383 * @deprecated As of 1.4.1, cast the 32-bit offset argument to a long.
384 * See {@link #staticFieldOffset}.
385 */
386 @Deprecated
387 public void putDouble(Object o, int offset, double x) {
388 putDouble(o, (long)offset, x);
389 }
390
391 // These work on values in the C heap.
392
393 /**
394 * Fetches a value from a given memory address. If the address is zero, or
395 * does not point into a block obtained from {@link #allocateMemory}, the
396 * results are undefined.
397 *
398 * @see #allocateMemory
399 */
400 public native byte getByte(long address);
401
402 /**
403 * Stores a value into a given memory address. If the address is zero, or
404 * does not point into a block obtained from {@link #allocateMemory}, the
405 * results are undefined.
406 *
407 * @see #getByte(long)
408 */
409 public native void putByte(long address, byte x);
410
411 /** @see #getByte(long) */
412 public native short getShort(long address);
413 /** @see #putByte(long, byte) */
414 public native void putShort(long address, short x);
415 /** @see #getByte(long) */
416 public native char getChar(long address);
417 /** @see #putByte(long, byte) */
418 public native void putChar(long address, char x);
419 /** @see #getByte(long) */
420 public native int getInt(long address);
421 /** @see #putByte(long, byte) */
422 public native void putInt(long address, int x);
423 /** @see #getByte(long) */
424 public native long getLong(long address);
425 /** @see #putByte(long, byte) */
426 public native void putLong(long address, long x);
427 /** @see #getByte(long) */
428 public native float getFloat(long address);
429 /** @see #putByte(long, byte) */
430 public native void putFloat(long address, float x);
431 /** @see #getByte(long) */
432 public native double getDouble(long address);
433 /** @see #putByte(long, byte) */
434 public native void putDouble(long address, double x);
435
436 /**
437 * Fetches a native pointer from a given memory address. If the address is
438 * zero, or does not point into a block obtained from {@link
439 * #allocateMemory}, the results are undefined.
440 *
441 * <p> If the native pointer is less than 64 bits wide, it is extended as
442 * an unsigned number to a Java long. The pointer may be indexed by any
443 * given byte offset, simply by adding that offset (as a simple integer) to
444 * the long representing the pointer. The number of bytes actually read
445 * from the target address maybe determined by consulting {@link
446 * #addressSize}.
447 *
448 * @see #allocateMemory
449 */
450 public native long getAddress(long address);
451
452 /**
453 * Stores a native pointer into a given memory address. If the address is
454 * zero, or does not point into a block obtained from {@link
455 * #allocateMemory}, the results are undefined.
456 *
457 * <p> The number of bytes actually written at the target address maybe
458 * determined by consulting {@link #addressSize}.
459 *
460 * @see #getAddress(long)
461 */
462 public native void putAddress(long address, long x);
463
464 /// wrappers for malloc, realloc, free:
465
466 /**
467 * Allocates a new block of native memory, of the given size in bytes. The
468 * contents of the memory are uninitialized; they will generally be
469 * garbage. The resulting native pointer will never be zero, and will be
470 * aligned for all value types. Dispose of this memory by calling {@link
471 * #freeMemory}, or resize it with {@link #reallocateMemory}.
472 *
473 * @throws IllegalArgumentException if the size is negative or too large
474 * for the native size_t type
475 *
476 * @throws OutOfMemoryError if the allocation is refused by the system
477 *
478 * @see #getByte(long)
479 * @see #putByte(long, byte)
480 */
481 public native long allocateMemory(long bytes);
482
483 /**
484 * Resizes a new block of native memory, to the given size in bytes. The
485 * contents of the new block past the size of the old block are
486 * uninitialized; they will generally be garbage. The resulting native
487 * pointer will be zero if and only if the requested size is zero. The
488 * resulting native pointer will be aligned for all value types. Dispose
489 * of this memory by calling {@link #freeMemory}, or resize it with {@link
490 * #reallocateMemory}. The address passed to this method may be null, in
491 * which case an allocation will be performed.
492 *
493 * @throws IllegalArgumentException if the size is negative or too large
494 * for the native size_t type
495 *
496 * @throws OutOfMemoryError if the allocation is refused by the system
497 *
498 * @see #allocateMemory
499 */
500 public native long reallocateMemory(long address, long bytes);
501
502 /**
503 * Sets all bytes in a given block of memory to a fixed value
504 * (usually zero).
505 *
506 * <p>This method determines a block's base address by means of two parameters,
507 * and so it provides (in effect) a <em>double-register</em> addressing mode,
508 * as discussed in {@link #getInt(Object,long)}. When the object reference is null,
509 * the offset supplies an absolute base address.
510 *
511 * <p>The stores are in coherent (atomic) units of a size determined
512 * by the address and length parameters. If the effective address and
513 * length are all even modulo 8, the stores take place in 'long' units.
514 * If the effective address and length are (resp.) even modulo 4 or 2,
515 * the stores take place in units of 'int' or 'short'.
516 *
517 * @since 1.7
518 */
519 public native void setMemory(Object o, long offset, long bytes, byte value);
520
521 /**
522 * Sets all bytes in a given block of memory to a fixed value
523 * (usually zero). This provides a <em>single-register</em> addressing mode,
524 * as discussed in {@link #getInt(Object,long)}.
525 *
526 * <p>Equivalent to <code>setMemory(null, address, bytes, value)</code>.
527 */
528 public void setMemory(long address, long bytes, byte value) {
529 setMemory(null, address, bytes, value);
530 }
531
532 /**
533 * Sets all bytes in a given block of memory to a copy of another
534 * block.
535 *
536 * <p>This method determines each block's base address by means of two parameters,
537 * and so it provides (in effect) a <em>double-register</em> addressing mode,
538 * as discussed in {@link #getInt(Object,long)}. When the object reference is null,
539 * the offset supplies an absolute base address.
540 *
541 * <p>The transfers are in coherent (atomic) units of a size determined
542 * by the address and length parameters. If the effective addresses and
543 * length are all even modulo 8, the transfer takes place in 'long' units.
544 * If the effective addresses and length are (resp.) even modulo 4 or 2,
545 * the transfer takes place in units of 'int' or 'short'.
546 *
547 * @since 1.7
548 */
549 public native void copyMemory(Object srcBase, long srcOffset,
550 Object destBase, long destOffset,
551 long bytes);
552 /**
553 * Sets all bytes in a given block of memory to a copy of another
554 * block. This provides a <em>single-register</em> addressing mode,
555 * as discussed in {@link #getInt(Object,long)}.
556 *
557 * Equivalent to <code>copyMemory(null, srcAddress, null, destAddress, bytes)</code>.
558 */
559 public void copyMemory(long srcAddress, long destAddress, long bytes) {
560 copyMemory(null, srcAddress, null, destAddress, bytes);
561 }
562
563 /**
564 * Disposes of a block of native memory, as obtained from {@link
565 * #allocateMemory} or {@link #reallocateMemory}. The address passed to
566 * this method may be null, in which case no action is taken.
567 *
568 * @see #allocateMemory
569 */
570 public native void freeMemory(long address);
571
572 /// random queries
573
574 /**
575 * This constant differs from all results that will ever be returned from
576 * {@link #staticFieldOffset}, {@link #objectFieldOffset},
577 * or {@link #arrayBaseOffset}.
578 */
579 public static final int INVALID_FIELD_OFFSET = -1;
580
581 /**
582 * Returns the offset of a field, truncated to 32 bits.
583 * This method is implemented as follows:
584 * <blockquote><pre>
585 * public int fieldOffset(Field f) {
586 * if (Modifier.isStatic(f.getModifiers()))
587 * return (int) staticFieldOffset(f);
588 * else
589 * return (int) objectFieldOffset(f);
590 * }
591 * </pre></blockquote>
592 * @deprecated As of 1.4.1, use {@link #staticFieldOffset} for static
593 * fields and {@link #objectFieldOffset} for non-static fields.
594 */
595 @Deprecated
596 public int fieldOffset(Field f) {
597 if (Modifier.isStatic(f.getModifiers()))
598 return (int) staticFieldOffset(f);
599 else
600 return (int) objectFieldOffset(f);
601 }
602
603 /**
604 * Returns the base address for accessing some static field
605 * in the given class. This method is implemented as follows:
606 * <blockquote><pre>
607 * public Object staticFieldBase(Class c) {
608 * Field[] fields = c.getDeclaredFields();
609 * for (int i = 0; i < fields.length; i++) {
610 * if (Modifier.isStatic(fields[i].getModifiers())) {
611 * return staticFieldBase(fields[i]);
612 * }
613 * }
614 * return null;
615 * }
616 * </pre></blockquote>
617 * @deprecated As of 1.4.1, use {@link #staticFieldBase(Field)}
618 * to obtain the base pertaining to a specific {@link Field}.
619 * This method works only for JVMs which store all statics
620 * for a given class in one place.
621 */
622 @Deprecated
623 public Object staticFieldBase(Class<?> c) {
624 Field[] fields = c.getDeclaredFields();
625 for (int i = 0; i < fields.length; i++) {
626 if (Modifier.isStatic(fields[i].getModifiers())) {
627 return staticFieldBase(fields[i]);
628 }
629 }
630 return null;
631 }
632
633 /**
634 * Report the location of a given field in the storage allocation of its
635 * class. Do not expect to perform any sort of arithmetic on this offset;
636 * it is just a cookie which is passed to the unsafe heap memory accessors.
637 *
638 * <p>Any given field will always have the same offset and base, and no
639 * two distinct fields of the same class will ever have the same offset
640 * and base.
641 *
642 * <p>As of 1.4.1, offsets for fields are represented as long values,
643 * although the Sun JVM does not use the most significant 32 bits.
644 * However, JVM implementations which store static fields at absolute
645 * addresses can use long offsets and null base pointers to express
646 * the field locations in a form usable by {@link #getInt(Object,long)}.
647 * Therefore, code which will be ported to such JVMs on 64-bit platforms
648 * must preserve all bits of static field offsets.
649 * @see #getInt(Object, long)
650 */
651 public native long staticFieldOffset(Field f);
652
653 /**
654 * Report the location of a given static field, in conjunction with {@link
655 * #staticFieldBase}.
656 * <p>Do not expect to perform any sort of arithmetic on this offset;
657 * it is just a cookie which is passed to the unsafe heap memory accessors.
658 *
659 * <p>Any given field will always have the same offset, and no two distinct
660 * fields of the same class will ever have the same offset.
661 *
662 * <p>As of 1.4.1, offsets for fields are represented as long values,
663 * although the Sun JVM does not use the most significant 32 bits.
664 * It is hard to imagine a JVM technology which needs more than
665 * a few bits to encode an offset within a non-array object,
666 * However, for consistency with other methods in this class,
667 * this method reports its result as a long value.
668 * @see #getInt(Object, long)
669 */
670 public native long objectFieldOffset(Field f);
671
672 /**
673 * Report the location of a given static field, in conjunction with {@link
674 * #staticFieldOffset}.
675 * <p>Fetch the base "Object", if any, with which static fields of the
676 * given class can be accessed via methods like {@link #getInt(Object,
677 * long)}. This value may be null. This value may refer to an object
678 * which is a "cookie", not guaranteed to be a real Object, and it should
679 * not be used in any way except as argument to the get and put routines in
680 * this class.
681 */
682 public native Object staticFieldBase(Field f);
683
684 /**
685 * Detect if the given class may need to be initialized. This is often
686 * needed in conjunction with obtaining the static field base of a
687 * class.
688 * @return false only if a call to {@code ensureClassInitialized} would have no effect
689 */
690 public native boolean shouldBeInitialized(Class<?> c);
691
692 /**
693 * Ensure the given class has been initialized. This is often
694 * needed in conjunction with obtaining the static field base of a
695 * class.
696 */
697 public native void ensureClassInitialized(Class<?> c);
698
699 /**
700 * Report the offset of the first element in the storage allocation of a
701 * given array class. If {@link #arrayIndexScale} returns a non-zero value
702 * for the same class, you may use that scale factor, together with this
703 * base offset, to form new offsets to access elements of arrays of the
704 * given class.
705 *
706 * @see #getInt(Object, long)
707 * @see #putInt(Object, long, int)
708 */
709 public native int arrayBaseOffset(Class<?> arrayClass);
710
711 /** The value of {@code arrayBaseOffset(boolean[].class)} */
712 public static final int ARRAY_BOOLEAN_BASE_OFFSET
713 = theUnsafe.arrayBaseOffset(boolean[].class);
714
715 /** The value of {@code arrayBaseOffset(byte[].class)} */
716 public static final int ARRAY_BYTE_BASE_OFFSET
717 = theUnsafe.arrayBaseOffset(byte[].class);
718
719 /** The value of {@code arrayBaseOffset(short[].class)} */
720 public static final int ARRAY_SHORT_BASE_OFFSET
721 = theUnsafe.arrayBaseOffset(short[].class);
722
723 /** The value of {@code arrayBaseOffset(char[].class)} */
724 public static final int ARRAY_CHAR_BASE_OFFSET
725 = theUnsafe.arrayBaseOffset(char[].class);
726
727 /** The value of {@code arrayBaseOffset(int[].class)} */
728 public static final int ARRAY_INT_BASE_OFFSET
729 = theUnsafe.arrayBaseOffset(int[].class);
730
731 /** The value of {@code arrayBaseOffset(long[].class)} */
732 public static final int ARRAY_LONG_BASE_OFFSET
733 = theUnsafe.arrayBaseOffset(long[].class);
734
735 /** The value of {@code arrayBaseOffset(float[].class)} */
736 public static final int ARRAY_FLOAT_BASE_OFFSET
737 = theUnsafe.arrayBaseOffset(float[].class);
738
739 /** The value of {@code arrayBaseOffset(double[].class)} */
740 public static final int ARRAY_DOUBLE_BASE_OFFSET
741 = theUnsafe.arrayBaseOffset(double[].class);
742
743 /** The value of {@code arrayBaseOffset(Object[].class)} */
744 public static final int ARRAY_OBJECT_BASE_OFFSET
745 = theUnsafe.arrayBaseOffset(Object[].class);
746
747 /**
748 * Report the scale factor for addressing elements in the storage
749 * allocation of a given array class. However, arrays of "narrow" types
750 * will generally not work properly with accessors like {@link
751 * #getByte(Object, int)}, so the scale factor for such classes is reported
752 * as zero.
753 *
754 * @see #arrayBaseOffset
755 * @see #getInt(Object, long)
756 * @see #putInt(Object, long, int)
757 */
758 public native int arrayIndexScale(Class<?> arrayClass);
759
760 /** The value of {@code arrayIndexScale(boolean[].class)} */
761 public static final int ARRAY_BOOLEAN_INDEX_SCALE
762 = theUnsafe.arrayIndexScale(boolean[].class);
763
764 /** The value of {@code arrayIndexScale(byte[].class)} */
765 public static final int ARRAY_BYTE_INDEX_SCALE
766 = theUnsafe.arrayIndexScale(byte[].class);
767
768 /** The value of {@code arrayIndexScale(short[].class)} */
769 public static final int ARRAY_SHORT_INDEX_SCALE
770 = theUnsafe.arrayIndexScale(short[].class);
771
772 /** The value of {@code arrayIndexScale(char[].class)} */
773 public static final int ARRAY_CHAR_INDEX_SCALE
774 = theUnsafe.arrayIndexScale(char[].class);
775
776 /** The value of {@code arrayIndexScale(int[].class)} */
777 public static final int ARRAY_INT_INDEX_SCALE
778 = theUnsafe.arrayIndexScale(int[].class);
779
780 /** The value of {@code arrayIndexScale(long[].class)} */
781 public static final int ARRAY_LONG_INDEX_SCALE
782 = theUnsafe.arrayIndexScale(long[].class);
783
784 /** The value of {@code arrayIndexScale(float[].class)} */
785 public static final int ARRAY_FLOAT_INDEX_SCALE
786 = theUnsafe.arrayIndexScale(float[].class);
787
788 /** The value of {@code arrayIndexScale(double[].class)} */
789 public static final int ARRAY_DOUBLE_INDEX_SCALE
790 = theUnsafe.arrayIndexScale(double[].class);
791
792 /** The value of {@code arrayIndexScale(Object[].class)} */
793 public static final int ARRAY_OBJECT_INDEX_SCALE
794 = theUnsafe.arrayIndexScale(Object[].class);
795
796 /**
797 * Report the size in bytes of a native pointer, as stored via {@link
798 * #putAddress}. This value will be either 4 or 8. Note that the sizes of
799 * other primitive types (as stored in native memory blocks) is determined
800 * fully by their information content.
801 */
802 public native int addressSize();
803
804 /** The value of {@code addressSize()} */
805 public static final int ADDRESS_SIZE = theUnsafe.addressSize();
806
807 /**
808 * Report the size in bytes of a native memory page (whatever that is).
809 * This value will always be a power of two.
810 */
811 public native int pageSize();
812
813
814 /// random trusted operations from JNI:
815
816 /**
817 * Tell the VM to define a class, without security checks. By default, the
818 * class loader and protection domain come from the caller's class.
819 */
820 public native Class<?> defineClass(String name, byte[] b, int off, int len,
821 ClassLoader loader,
822 ProtectionDomain protectionDomain);
823
824 /**
825 * Define a class but do not make it known to the class loader or system dictionary.
826 * <p>
827 * For each CP entry, the corresponding CP patch must either be null or have
828 * the a format that matches its tag:
829 * <ul>
830 * <li>Integer, Long, Float, Double: the corresponding wrapper object type from java.lang
831 * <li>Utf8: a string (must have suitable syntax if used as signature or name)
832 * <li>Class: any java.lang.Class object
833 * <li>String: any object (not just a java.lang.String)
834 * <li>InterfaceMethodRef: (NYI) a method handle to invoke on that call site's arguments
835 * </ul>
836 * @params hostClass context for linkage, access control, protection domain, and class loader
837 * @params data bytes of a class file
838 * @params cpPatches where non-null entries exist, they replace corresponding CP entries in data
839 */
840 public native Class<?> defineAnonymousClass(Class<?> hostClass, byte[] data, Object[] cpPatches);
841
842
843 /** Allocate an instance but do not run any constructor.
844 Initializes the class if it has not yet been. */
845 public native Object allocateInstance(Class<?> cls)
846 throws InstantiationException;
847
848 /** Lock the object. It must get unlocked via {@link #monitorExit}. */
849 public native void monitorEnter(Object o);
850
851 /**
852 * Unlock the object. It must have been locked via {@link
853 * #monitorEnter}.
854 */
855 public native void monitorExit(Object o);
856
857 /**
858 * Tries to lock the object. Returns true or false to indicate
859 * whether the lock succeeded. If it did, the object must be
860 * unlocked via {@link #monitorExit}.
861 */
862 public native boolean tryMonitorEnter(Object o);
863
864 /** Throw the exception without telling the verifier. */
865 public native void throwException(Throwable ee);
866
867
868 /**
869 * Atomically update Java variable to <tt>x</tt> if it is currently
870 * holding <tt>expected</tt>.
871 * @return <tt>true</tt> if successful
872 */
873 public final native boolean compareAndSwapObject(Object o, long offset,
874 Object expected,
875 Object x);
876
877 /**
878 * Atomically update Java variable to <tt>x</tt> if it is currently
879 * holding <tt>expected</tt>.
880 * @return <tt>true</tt> if successful
881 */
882 public final native boolean compareAndSwapInt(Object o, long offset,
883 int expected,
884 int x);
885
886 /**
887 * Atomically update Java variable to <tt>x</tt> if it is currently
888 * holding <tt>expected</tt>.
889 * @return <tt>true</tt> if successful
890 */
891 public final native boolean compareAndSwapLong(Object o, long offset,
892 long expected,
893 long x);
894
895 /**
896 * Fetches a reference value from a given Java variable, with volatile
897 * load semantics. Otherwise identical to {@link #getObject(Object, long)}
898 */
899 public native Object getObjectVolatile(Object o, long offset);
900
901 /**
902 * Stores a reference value into a given Java variable, with
903 * volatile store semantics. Otherwise identical to {@link #putObject(Object, long, Object)}
904 */
905 public native void putObjectVolatile(Object o, long offset, Object x);
906
907 /** Volatile version of {@link #getInt(Object, long)} */
908 public native int getIntVolatile(Object o, long offset);
909
910 /** Volatile version of {@link #putInt(Object, long, int)} */
911 public native void putIntVolatile(Object o, long offset, int x);
912
913 /** Volatile version of {@link #getBoolean(Object, long)} */
914 public native boolean getBooleanVolatile(Object o, long offset);
915
916 /** Volatile version of {@link #putBoolean(Object, long, boolean)} */
917 public native void putBooleanVolatile(Object o, long offset, boolean x);
918
919 /** Volatile version of {@link #getByte(Object, long)} */
920 public native byte getByteVolatile(Object o, long offset);
921
922 /** Volatile version of {@link #putByte(Object, long, byte)} */
923 public native void putByteVolatile(Object o, long offset, byte x);
924
925 /** Volatile version of {@link #getShort(Object, long)} */
926 public native short getShortVolatile(Object o, long offset);
927
928 /** Volatile version of {@link #putShort(Object, long, short)} */
929 public native void putShortVolatile(Object o, long offset, short x);
930
931 /** Volatile version of {@link #getChar(Object, long)} */
932 public native char getCharVolatile(Object o, long offset);
933
934 /** Volatile version of {@link #putChar(Object, long, char)} */
935 public native void putCharVolatile(Object o, long offset, char x);
936
937 /** Volatile version of {@link #getLong(Object, long)} */
938 public native long getLongVolatile(Object o, long offset);
939
940 /** Volatile version of {@link #putLong(Object, long, long)} */
941 public native void putLongVolatile(Object o, long offset, long x);
942
943 /** Volatile version of {@link #getFloat(Object, long)} */
944 public native float getFloatVolatile(Object o, long offset);
945
946 /** Volatile version of {@link #putFloat(Object, long, float)} */
947 public native void putFloatVolatile(Object o, long offset, float x);
948
949 /** Volatile version of {@link #getDouble(Object, long)} */
950 public native double getDoubleVolatile(Object o, long offset);
951
952 /** Volatile version of {@link #putDouble(Object, long, double)} */
953 public native void putDoubleVolatile(Object o, long offset, double x);
954
955 /**
956 * Version of {@link #putObjectVolatile(Object, long, Object)}
957 * that does not guarantee immediate visibility of the store to
958 * other threads. This method is generally only useful if the
959 * underlying field is a Java volatile (or if an array cell, one
960 * that is otherwise only accessed using volatile accesses).
961 *
962 * Corresponds to C11 atomic_store_explicit(..., memory_order_release).
963 */
964 public native void putOrderedObject(Object o, long offset, Object x);
965
966 /** Ordered/Lazy version of {@link #putIntVolatile(Object, long, int)} */
967 public native void putOrderedInt(Object o, long offset, int x);
968
969 /** Ordered/Lazy version of {@link #putLongVolatile(Object, long, long)} */
970 public native void putOrderedLong(Object o, long offset, long x);
971
972 /**
973 * Unblock the given thread blocked on <tt>park</tt>, or, if it is
974 * not blocked, cause the subsequent call to <tt>park</tt> not to
975 * block. Note: this operation is "unsafe" solely because the
976 * caller must somehow ensure that the thread has not been
977 * destroyed. Nothing special is usually required to ensure this
978 * when called from Java (in which there will ordinarily be a live
979 * reference to the thread) but this is not nearly-automatically
980 * so when calling from native code.
981 * @param thread the thread to unpark.
982 *
983 */
984 public native void unpark(Object thread);
985
986 /**
987 * Block current thread, returning when a balancing
988 * <tt>unpark</tt> occurs, or a balancing <tt>unpark</tt> has
989 * already occurred, or the thread is interrupted, or, if not
990 * absolute and time is not zero, the given time nanoseconds have
991 * elapsed, or if absolute, the given deadline in milliseconds
992 * since Epoch has passed, or spuriously (i.e., returning for no
993 * "reason"). Note: This operation is in the Unsafe class only
994 * because <tt>unpark</tt> is, so it would be strange to place it
995 * elsewhere.
996 */
997 public native void park(boolean isAbsolute, long time);
998
999 /**
1000 * Gets the load average in the system run queue assigned
1001 * to the available processors averaged over various periods of time.
1002 * This method retrieves the given <tt>nelem</tt> samples and
1003 * assigns to the elements of the given <tt>loadavg</tt> array.
1004 * The system imposes a maximum of 3 samples, representing
1005 * averages over the last 1, 5, and 15 minutes, respectively.
1006 *
1007 * @params loadavg an array of double of size nelems
1008 * @params nelems the number of samples to be retrieved and
1009 * must be 1 to 3.
1010 *
1011 * @return the number of samples actually retrieved; or -1
1012 * if the load average is unobtainable.
1013 */
1014 public native int getLoadAverage(double[] loadavg, int nelems);
1015
1016 // The following contain CAS-based Java implementations used on
1017 // platforms not supporting native instructions
1018
1019 /**
1020 * Atomically adds the given value to the current value of a field
1021 * or array element within the given object <code>o</code>
1022 * at the given <code>offset</code>.
1023 *
1024 * @param o object/array to update the field/element in
1025 * @param offset field/element offset
1026 * @param delta the value to add
1027 * @return the previous value
1028 * @since 1.8
1029 */
1030 public final int getAndAddInt(Object o, long offset, int delta) {
1031 int v;
1032 do {
1033 v = getIntVolatile(o, offset);
1034 } while (!compareAndSwapInt(o, offset, v, v + delta));
1035 return v;
1036 }
1037
1038 /**
1039 * Atomically adds the given value to the current value of a field
1040 * or array element within the given object <code>o</code>
1041 * at the given <code>offset</code>.
1042 *
1043 * @param o object/array to update the field/element in
1044 * @param offset field/element offset
1045 * @param delta the value to add
1046 * @return the previous value
1047 * @since 1.8
1048 */
1049 public final long getAndAddLong(Object o, long offset, long delta) {
1050 long v;
1051 do {
1052 v = getLongVolatile(o, offset);
1053 } while (!compareAndSwapLong(o, offset, v, v + delta));
1054 return v;
1055 }
1056
1057 /**
1058 * Atomically exchanges the given value with the current value of
1059 * a field or array element within the given object <code>o</code>
1060 * at the given <code>offset</code>.
1061 *
1062 * @param o object/array to update the field/element in
1063 * @param offset field/element offset
1064 * @param newValue new value
1065 * @return the previous value
1066 * @since 1.8
1067 */
1068 public final int getAndSetInt(Object o, long offset, int newValue) {
1069 int v;
1070 do {
1071 v = getIntVolatile(o, offset);
1072 } while (!compareAndSwapInt(o, offset, v, newValue));
1073 return v;
1074 }
1075
1076 /**
1077 * Atomically exchanges the given value with the current value of
1078 * a field or array element within the given object <code>o</code>
1079 * at the given <code>offset</code>.
1080 *
1081 * @param o object/array to update the field/element in
1082 * @param offset field/element offset
1083 * @param newValue new value
1084 * @return the previous value
1085 * @since 1.8
1086 */
1087 public final long getAndSetLong(Object o, long offset, long newValue) {
1088 long v;
1089 do {
1090 v = getLongVolatile(o, offset);
1091 } while (!compareAndSwapLong(o, offset, v, newValue));
1092 return v;
1093 }
1094
1095 /**
1096 * Atomically exchanges the given reference value with the current
1097 * reference value of a field or array element within the given
1098 * object <code>o</code> at the given <code>offset</code>.
1099 *
1100 * @param o object/array to update the field/element in
1101 * @param offset field/element offset
1102 * @param newValue new value
1103 * @return the previous value
1104 * @since 1.8
1105 */
1106 public final Object getAndSetObject(Object o, long offset, Object newValue) {
1107 Object v;
1108 do {
1109 v = getObjectVolatile(o, offset);
1110 } while (!compareAndSwapObject(o, offset, v, newValue));
1111 return v;
1112 }
1113
1114
1115 /**
1116 * Ensures that loads before the fence will not be reordered with loads and
1117 * stores after the fence; a "LoadLoad plus LoadStore barrier".
1118 *
1119 * Corresponds to C11 atomic_thread_fence(memory_order_acquire)
1120 * (an "acquire fence").
1121 *
1122 * A pure LoadLoad fence is not provided, since the addition of LoadStore
1123 * is almost always desired, and most current hardware instructions that
1124 * provide a LoadLoad barrier also provide a LoadStore barrier for free.
1125 * @since 1.8
1126 */
1127 public native void loadFence();
1128
1129 /**
1130 * Ensures that loads and stores before the fence will not be reordered with
1131 * stores after the fence; a "StoreStore plus LoadStore barrier".
1132 *
1133 * Corresponds to C11 atomic_thread_fence(memory_order_release)
1134 * (a "release fence").
1135 *
1136 * A pure StoreStore fence is not provided, since the addition of LoadStore
1137 * is almost always desired, and most current hardware instructions that
1138 * provide a StoreStore barrier also provide a LoadStore barrier for free.
1139 * @since 1.8
1140 */
1141 public native void storeFence();
1142
1143 /**
1144 * Ensures that loads and stores before the fence will not be reordered
1145 * with loads and stores after the fence. Implies the effects of both
1146 * loadFence() and storeFence(), and in addition, the effect of a StoreLoad
1147 * barrier.
1148 *
1149 * Corresponds to C11 atomic_thread_fence(memory_order_seq_cst).
1150 * @since 1.8
1151 */
1152 public native void fullFence();
1153
1154 /**
1155 * Throws IllegalAccessError; for use by the VM.
1156 * @since 1.8
1157 */
1158 private static void throwIllegalAccessError() {
1159 throw new IllegalAccessError();
1160 }
1161
1162 }