Where is sun.misc.Unsafe documented?

Question

Does anyone know of any comprehensive documentation for sun.misc.Unsafe?

I'm looking for documentation on Unsafe.putOrderedInt(). This was all I was able to find.

public native  void putOrderedInt(Object o,
    long offset,
    int x)

     Ordered/Lazy version of #putIntVolatile(Object, long, int)

Does anyone know of a better source?

My understanding of the `sun.*` classes is that they are **specifically** undocumented/unsupported. You're not *supposed* to be using them, in that there is no published API that they agree to stick to, or semantics that they guarantee will hold. As such it's not surprising that the only documentation is unofficial - use at your own risk. — Andrzej Doyle, May 29 '13 at 16:28
Take note - it's supposed to be removed in Java 9 - http://blog.dripstat.com/removal-of-sun-misc-unsafe-a-disaster-in-the-making — Eyal, Jul 15 '15 at 09:26
That's a rather inflammatory blog post. Unsurprisingly, the "absolute catastrophy" that post is fear-mongering about is being addressed. The [current proposal](http://openjdk.java.net/jeps/260) will leave `sun.misc.Unsafe` and some other classes, like `sun.misc.Signal`, available by default. — dimo414, Dec 09 '15 at 20:37

score 67 · Accepted Answer · edited Jun 27 '19 at 03:42

67

There is a nice post about it on mishadoff's blog here.

The class is officially undocumented though.

edited Jun 27 '19 at 03:42

MultiplyByZer0

6,302
3
32
48

answered May 29 '13 at 16:30

mwerschy

1,698
1
15
26

19

There is quite a lot documentation attached to the source code of the class: http://www.docjar.com/html/api/sun/misc/Unsafe.java.html – Rafael Winterhalter Dec 10 '13 at 11:35
2

@raphw This is for the OpenJDK though, the devs must be more open-minded than Oracle. Thanks for the link, it's very handy. – jlr Jan 24 '14 at 16:23
3

Other JDKs might not even provide `sun.misc.Unsafe` since it is an internal class. Thos JDKs that provider the class normally choose an identical implementation, though. Even Android has one with identical "public" API. – Rafael Winterhalter Jan 24 '14 at 16:40

score 9 · Answer 2 · answered Nov 18 '14 at 10:44

Regarding the putOrdered methods..

You can call this method to set the volatile field without using a volatile store.. If you execute a volatile store, you basically have a store memory barrier which ensures that all store instruction prior the barrier, happen before barrier and that memory is visible by ensuring the data is propagated to the cache sub-system.. So when you have the volatile store you must wait for the store buffer to drain.. With putOrdered thread executing will not wait for the store buffer to drain and this can improve performance.. However as a consequence stored value will not be visible to other threads immediately..

If you have a look on AtomicLong (or other Atomic classes) there is a lazySet method that actually executes putOrderedLong. The javadoc on this method is:

Eventually sets to the given value.

Where is sun.misc.Unsafe documented?

2 Answers2

Linked