com.fluxtion.agrona.hints.package-info Maven / Gradle / Ivy
/*
* Copyright 2014-2024 Real Logic Limited.
* Copyright 2016 Gil Tene
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
*
* 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
* {@link com.fluxtion.agrona.hints.ThreadHints#onSpinWait ThreadHints.onSpinWait()}:
* Per JEP285, it is anticipated that Java SE 9 will include a Thread.onSpinWait()
* method with specified behavior identical to
* {@link com.fluxtion.agrona.hints.ThreadHints#onSpinWait 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 {@link com.fluxtion.agrona.hints.ThreadHints#onSpinWait 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. The implementation can be disabled by setting
* the {@link com.fluxtion.agrona.hints.ThreadHints#DISABLE_ON_SPIN_WAIT_PROP_NAME} system
* property to true.
*
*
* 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, and 8 by JDKs who wish to do so.
*/
package com.fluxtion.agrona.hints;