Skip navigation links

Package org.agrona.hints

This package captures hints that may be used by some runtimes to improve code performance.

See: Description

Package org.agrona.hints Description

This package captures hints that may be used by some runtimes to improve code performance. It is intended to provide a portable means for using performance hinting APIs across Java and JDK versions, such that calling code can avoid maintaining version-specific sources for various JDK or Java version capabilities.

All the features supported by this package are (by definition) hints. A no-op implementation of a hint is always considered valid.

When executing on Java versions for which corresponding capabilities exist and are specified in the Java version spec, the hint implementations in this package will attempt to use the appropriate JDK calls.

Some JDKs may choose to "intrinsify" some APIs in this package to e.g. provide runtime support for certain hints on java versions that do not yet have specified support for those capabilities.

A good example of the purpose of this package and an example of how it may be used can be found with ThreadHints.onSpinWait(): Per JEP285, it is anticipated that Java SE 9 will include a Thread.onSpinWait() method with specified behavior identical to ThreadHints.onSpinWait(). However, earlier Java SE versions do not include this behavior, forcing code that wants to make use of this hinting capability to be written and maintained separately when targeting Java versions before and after Java SE 9.

The implementation of ThreadHints.onSpinWait() resolves this problem by calling Thread.onSpinWait() if it exists, and doing nothing if it does not. This allows code that wants to include spin wait hinting to remain portable across Java versions, without needing separate implementations for versions prior to and following Java SE 9. The mechanism used to conditionally make this call was specifically designed and tested for efficient inlining and by common JVMs, such that there is no extra no overhead associated with making the hint call: in JIT'ted code it becomes either an nop or an efficient, inlined intrinsic.

In addition, JDKs that wish to introduce support for newer hinting capabilities in their implementations of older Java SE versions can do so by "inrinsifying" associated org.agrona.hints classes and methods. Code that makes use of org.agrona.hints hinting methods will then benefit from potential performance improvements even on prior java SE versions. E.g. the example onSpinWait capability discussed above can be added in such a way to Java SE 6, 7, 8 by JDKs who wish to do so.

Skip navigation links

Copyright © 2014-2019 Real Logic Ltd. All Rights Reserved.