/*=========================================================================

  Program:   FusionViewer
  Module:    $RCSfile: NativeBuffer.java,v $
  Language:  Java
  Date:      $Date: 2007/02/02 19:26:29 $
  Version:   $Revision: 1.2 $
  
  Copyright (c) Insightful Corporation.  All rights reserved.
  See Copyright.txt for details.
  
  This software is distributed WITHOUT ANY WARRANTY; without even
  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  PURPOSE.  See the above copyright notice for more information.

=========================================================================*/

package org.fusionviewer.io;


/**\class NativeBuffer
 *\brief There is a limit to the amount of memory java.nio.ByteBuffer can allocate
 * in direct mode.
 * (see Java bug parade #4879883).  Adding a flag such as
 * -XX:MaxDirectMemorySize=256m is supposed to be a temporary workaround,
 * but it is not working on Mac OS X as of JDK 1.4.2 update 2.
 * 
 * This class has native methods to manage memory and share it with other
 * native methods.  The user must call release to dispose of the buffer.
 */
public class NativeBuffer {
	static {
		System.loadLibrary("FusionViewer");
	}
	
	private long m_nativePointer = 0;
	
	
	/**
	 * Allocate a buffer.
	 * 
	 * @param size length of the buffer
	 */
	public NativeBuffer(long size) {
		if (!allocate(size)) {
			m_nativePointer = 0;
			throw new OutOfMemoryError();
		}
	}
	
	/**
	 * Get the address of the beginning of the buffer.
	 * 
	 * @return buffer address
	 */
	public long getPointer() {
		return m_nativePointer;
	}
	
	/**
	 * Dispose of the buffer.
	 */
	public void release() {
		dispose();
		m_nativePointer = 0;
	}
	
	/*
	 * In case release is not called, the finalizer will call it.
	 * Users should not depend on this cleanup method, however.
	 */
	protected void finalize() throws Throwable {
		if (m_nativePointer != 0)
			release();
	}
	
	/**
	 * Allocate a buffer.
	 * 
	 * @param size lengt of the buffer
	 * @return true if the buffer was allocated
	 */
	native public boolean allocate(long size);
	
	/*
	 * Frees the buffer.
	 */
	native private void dispose();
}