CacheUtil.java

/*
 * Copyright (c) 2002-2011 LWJGL Project
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of 'LWJGL' nor the names of
 *   its contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.lwjgl.util.mapped;

import org.lwjgl.LWJGLUtil;
import org.lwjgl.MemoryUtil;
import org.lwjgl.PointerBuffer;

import java.nio.*;

/**
 * This class provides utility methods for allocating cache-line-aligned
 * NIO buffers. The CPU cache line size is detected using a micro-benchmark
 * that exploits the performation degredation that occurs when different
 * threads write to different locations of the same cache line. The detection
 * should be reasonably robust on both the server and client VM, but there
 * are a few system properties that can be used to tune it.
 *
 * @author Spasi
 */
public final class CacheUtil {

	private static final int CACHE_LINE_SIZE;

	static {
		final Integer size = LWJGLUtil.getPrivilegedInteger("org.lwjgl.util.mapped.CacheLineSize"); // forces a specific cache line size

		if ( size != null ) {
			if ( size < 1 )
				throw new IllegalStateException("Invalid CacheLineSize specified: " + size);
			CACHE_LINE_SIZE = size;
		} else if ( Runtime.getRuntime().availableProcessors() == 1 ) { // We cannot use false sharing to detect it
			/*
			    Spasi:

			    I have implemented a single-threaded benchmark for this, but it requires
			    lots of memory allocations and could not tune it for both the client and
			    server VM. It's not a big deal anyway, 64 bytes should be ok for any
			    single-core CPU.
			*/
			if ( LWJGLUtil.DEBUG )
				LWJGLUtil.log("Cannot detect cache line size on single-core CPUs, assuming 64 bytes.");
			CACHE_LINE_SIZE = 64;
		} else
			CACHE_LINE_SIZE = CacheLineSize.getCacheLineSize();
	}

	private CacheUtil() {
	}

	/**
	 * Returns the CPU cache line size, in number of bytes.
	 *
	 * @return the cache line size
	 */
	public static int getCacheLineSize() {
		return CACHE_LINE_SIZE;
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned bytebuffer with the specified size.
	 *
	 * @param size The size, in bytes
	 *
	 * @return a ByteBuffer
	 */
	public static ByteBuffer createByteBuffer(int size) {
		ByteBuffer buffer = ByteBuffer.allocateDirect(size + CACHE_LINE_SIZE);

		// Align to cache line.
		if ( MemoryUtil.getAddress(buffer) % CACHE_LINE_SIZE != 0 ) {
			// Round up to cache line boundary
			buffer.position(CACHE_LINE_SIZE - (int)(MemoryUtil.getAddress(buffer) & (CACHE_LINE_SIZE - 1)));
		}

		buffer.limit(buffer.position() + size);
		return buffer.slice().order(ByteOrder.nativeOrder());
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned shortbuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in shorts
	 *
	 * @return a ShortBuffer
	 */
	public static ShortBuffer createShortBuffer(int size) {
		return createByteBuffer(size << 1).asShortBuffer();
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned charbuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in chars
	 *
	 * @return an CharBuffer
	 */
	public static CharBuffer createCharBuffer(int size) {
		return createByteBuffer(size << 1).asCharBuffer();
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned intbuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in ints
	 *
	 * @return an IntBuffer
	 */
	public static IntBuffer createIntBuffer(int size) {
		return createByteBuffer(size << 2).asIntBuffer();
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned longbuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in longs
	 *
	 * @return an LongBuffer
	 */
	public static LongBuffer createLongBuffer(int size) {
		return createByteBuffer(size << 3).asLongBuffer();
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned floatbuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in floats
	 *
	 * @return a FloatBuffer
	 */
	public static FloatBuffer createFloatBuffer(int size) {
		return createByteBuffer(size << 2).asFloatBuffer();
	}

	/**
	 * Construct a direct, native-ordered and cache-line-aligned doublebuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in floats
	 *
	 * @return a FloatBuffer
	 */
	public static DoubleBuffer createDoubleBuffer(int size) {
		return createByteBuffer(size << 3).asDoubleBuffer();
	}

	/**
	 * Construct a cache-line-aligned PointerBuffer with the specified number
	 * of elements.
	 *
	 * @param size The size, in memory addresses
	 *
	 * @return a PointerBuffer
	 */
	public static PointerBuffer createPointerBuffer(int size) {
		return new PointerBuffer(createByteBuffer(size * PointerBuffer.getPointerSize()));
	}

}