package-info.java

/*
 *  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
 *
 * http://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.
 */

/**
 * <p>
 * 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.
 * </p>
 * <p>
 * All the features supported by this package are (by definition) hints.
 * A no-op implementation of a hint is always considered valid.
 * </p>
 * <p>
 * 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.
 * </p>
 * <p>
 * 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.
 * </p>
 * <p>
 * A good example of the purpose of this package and an example of how it may
 * be used can be found with
 * {@link org.agrona.hints.ThreadHints#onSpinWait ThreadHints.onSpinWait()}:
 * Per JEP285, it is anticipated that Java SE 9 will include a <code>Thread.onSpinWait()</code>
 * method with specified behavior identical to
 * {@link org.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.
 * </p>
 * <p>
 * The implementation
 * of {@link org.agrona.hints.ThreadHints#onSpinWait ThreadHints.onSpinWait()}
 * resolves this problem by calling <code>Thread.onSpinWait()</code> 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.
 * </p>
 * <p>
 * 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.
 */

package org.agrona.hints;