BEGIN LICENSE BLOCK *****
Version: EPL 2.0/GPL 2.0/LGPL 2.1
The contents of this file are subject to the Eclipse Public
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.eclipse.org/legal/epl-v20.html
Software distributed under the License is distributed on an "AS
IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
implied. See the License for the specific language governing
rights and limitations under the License.
Copyright (C) 2008 JRuby project
Alternatively, the contents of this file may be used under the terms of
either of the GNU General Public License Version 2 or later (the "GPL"),
or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
in which case the provisions of the GPL or the LGPL are applicable instead
of those above. If you wish to allow use of your version of this file only
under the terms of either the GPL or the LGPL, and not to allow others to
use your version of this file under the terms of the EPL, indicate your
decision by deleting the provisions above and replace them with the notice
and other provisions required by the GPL or the LGPL. If you do not delete
the provisions above, a recipient may use your version of this file under
the terms of any one of the EPL, the GPL or the LGPL.
END LICENSE BLOCK /***** BEGIN LICENSE BLOCK *****
 * Version: EPL 2.0/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Eclipse Public
 * 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.eclipse.org/legal/epl-v20.html
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * Copyright (C) 2008 JRuby project
 * 
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the EPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the EPL, the GPL or the LGPL.
 ***** END LICENSE BLOCK *****/

package org.jruby.ext.ffi;

import java.nio.ByteOrder;

Abstracted memory operations.

This abstracts read/write operations to either a native memory area, or a java
ByteBuffer.

/**
 * Abstracted memory operations.
 * <p>
 * This abstracts read/write operations to either a native memory area, or a java
 * ByteBuffer.
 * </p>
 */
abstract public class MemoryIO {
    protected final boolean isDirect;
    protected final long address;

    protected MemoryIO(boolean direct, long address) {
        isDirect = direct;
        this.address = address;
    }

    
Checks if the memory area is NULL.
Returns:
true if the memory area is invalid./**
     * Checks if the memory area is NULL.
     * 
     * @return <tt>true</tt> if the memory area is invalid.
     */
    public final boolean isNull() {
        return address == 0L;
    }

    
Checks if the memory area is a native memory pointer.
Returns:
true if the memory area is a native pointer./**
     * Checks if the memory area is a native memory pointer.
     *
     * @return <tt>true</tt> if the memory area is a native pointer.
     */
    public final boolean isDirect() {
        return isDirect;
    }

    
Gets the native address of this memory region.  May return NULL (0) if this is not a direct pointer.
Returns:
A long value containing the native memory address/**
     * Gets the native address of this memory region.  May return NULL (0) if this is not a direct pointer.
     *
     * @return A long value containing the native memory address
     */
    public final long address() {
        return address;
    }

    abstract public Object array();
    abstract public int arrayOffset();
    abstract public int arrayLength();

    
Gets the ByteOrder this MemoryIO instance will read/write values to memory in. 
Returns:
The current ByteOrder/**
     * Gets the {@link ByteOrder} this {@code MemoryIO} instance will read/write
     * values to memory in.
     *
     * @return The current ByteOrder
     */
    abstract public ByteOrder order();

    
Creates a new MemoryIO pointing to a subset of the memory area of this
MemoryIO.
Params:
offset – The offset within the existing memory area to start the
new MemoryIO at.
Returns:
A MemoryIO instance./**
     * Creates a new MemoryIO pointing to a subset of the memory area of this
     * <tt>MemoryIO</tt>.
     * @param offset The offset within the existing memory area to start the
     * new <tt>MemoryIO</tt> at.
     * @return A <tt>MemoryIO</tt> instance.
     */
    abstract public MemoryIO slice(long offset);

    
Creates a new MemoryIO pointing to a subset of the memory area of this
MemoryIO.
Params:
offset – The offset within the existing memory area to start the
new MemoryIO at.
size – The size of the new slice.
Returns:
A MemoryIO instance./**
     * Creates a new MemoryIO pointing to a subset of the memory area of this
     * <tt>MemoryIO</tt>.
     * @param offset The offset within the existing memory area to start the
     * new <tt>MemoryIO</tt> at.
     * @param size The size of the new slice.
     *
     * @return A <tt>MemoryIO</tt> instance.
     */
    abstract public MemoryIO slice(long offset, long size);

    
Duplicates this MemoryIO, including its contents.
Returns:
A MemoryIO instance./**
     * Duplicates this <tt>MemoryIO</tt>, including its contents.
     * 
     * @return A <tt>MemoryIO</tt> instance.
     */
    abstract public MemoryIO dup();

    
Creates a view of this memory object as a java NIO byte buffer.
Returns:
A ByteBuffer instance/**
     * Creates a view of this memory object as a java NIO byte buffer.
     *
     * @return A ByteBuffer instance
     */
    abstract public java.nio.ByteBuffer asByteBuffer();
    
    
Reads an 8 bit integer value from the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
The 8 bit integer value read from offset/**
     * Reads an 8 bit integer value from the memory area.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The 8 bit integer value read from <tt>offset</tt>
     */
    abstract public byte getByte(long offset);
    
    
Reads a 16 bit integer value from the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
The 16 bit integer value read from offset/**
     * Reads a 16 bit integer value from the memory area.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The 16 bit integer value read from <tt>offset</tt>
     */
    abstract public short getShort(long offset);
    
    
Reads a 32 bit integer value from the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
The 32 bit integer value read from offset/**
     * Reads a 32 bit integer value from the memory area.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The 32 bit integer value read from <tt>offset</tt>
     */
    abstract public int getInt(long offset);
    
    
Reads a 64 bit integer value from the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
The 64 bit integer value read from offset/**
     * Reads a 64 bit integer value from the memory area.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The 64 bit integer value read from <tt>offset</tt>
     */
    abstract public long getLong(long offset);
    
    
Reads a native long integer value from the memory area.

A native long is 32bits on either ILP32 or LLP64 architectures, and 
64 bits on an LP64 architecture.


This means that it will always read a 32bit value on Windows, but on
Unix systems such as MacOS or Linux, it will read a 32bit value on 32bit
systems, and a 64bit value on 64bit systems.
Params:
offset – The offset within the memory area to read the value.
Returns:
The native long value read from offset/**
     * Reads a native long integer value from the memory area.
     * <p>
     * A native long is 32bits on either ILP32 or LLP64 architectures, and 
     * 64 bits on an LP64 architecture.
     * </p>
     * <p>
     * This means that it will always read a 32bit value on Windows, but on
     * Unix systems such as MacOS or Linux, it will read a 32bit value on 32bit
     * systems, and a 64bit value on 64bit systems.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The native long value read from <tt>offset</tt>
     */
    abstract public long getNativeLong(long offset);
    
    
Reads a float value from the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
The float value read from offset/**
     * Reads a float value from the memory area.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The float value read from <tt>offset</tt>
     */
    abstract public float getFloat(long offset);
    
    
Reads a double value from the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
The double value read from offset/**
     * Reads a double value from the memory area.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return The double value read from <tt>offset</tt>
     */
    abstract public double getDouble(long offset);

     
Reads a pointer value at the specified offset within the memory area.
Params:
offset – The offset within the memory area to read the value.
Returns:
A long value that represents the address./**
     * Reads a pointer value at the specified offset within the memory area.
     *
     * @param offset The offset within the memory area to read the value.
     * @return A <tt>long</tt> value that represents the address.
     */
     abstract public long getAddress(long offset);

    
Reads a pointer value at the specified offset within the memory area, and
wraps it in an abstract memory accessor.
Params:
offset – The offset within the memory area to read the value.
Returns:
A DirectMemoryIO accessor that can be used to access the memory
pointed to by the address./**
     * Reads a pointer value at the specified offset within the memory area, and
     * wraps it in an abstract memory accessor.
     * 
     * @param offset The offset within the memory area to read the value.
     * @return A <tt>DirectMemoryIO</tt> accessor that can be used to access the memory
     * pointed to by the address.
     */
    abstract public MemoryIO getMemoryIO(long offset);
    
    
Writes an 8 bit integer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The 8 bit integer value to write to the memory location./**
     * Writes an 8 bit integer value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The 8 bit integer value to write to the memory location.
     */
    abstract public void putByte(long offset, byte value);
    
    
Writes a 16 bit integer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The 16 bit integer value to write to the memory location./**
     * Writes a 16 bit integer value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The 16 bit integer value to write to the memory location.
     */
    abstract public void putShort(long offset, short value);
    
    
Writes a 32 bit integer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The 32 bit integer value to write to the memory location./**
     * Writes a 32 bit integer value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The 32 bit integer value to write to the memory location.
     */
    abstract public void putInt(long offset, int value);
    
    
Writes a 64 bit integer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The 64 bit integer value to write to the memory location./**
     * Writes a 64 bit integer value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The 64 bit integer value to write to the memory location.
     */
    abstract public void putLong(long offset, long value);
    
    
Writes a native long integer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The native long integer value to write to the memory location./**
     * Writes a native long integer value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The native long integer value to write to the memory location.
     */
    abstract public void putNativeLong(long offset, long value);
    
    
Writes a 32 bit float value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The 32 bit float value to write to the memory location./**
     * Writes a 32 bit float value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The 32 bit float value to write to the memory location.
     */
    abstract public void putFloat(long offset, float value);
    
    
Writes a 64 bit float value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The 64 bit float value to write to the memory location./**
     * Writes a 64 bit float value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The 64 bit float value to write to the memory location.
     */
    abstract public void putDouble(long offset, double value);
    
    
Writes a pointer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The pointer value to write to the memory location./**
     * Writes a pointer value to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to write the value.
     * @param value The pointer value to write to the memory location.
     */
    abstract public void putMemoryIO(long offset, MemoryIO value);

    
Writes a pointer value to the memory area at the specified offset.
Params:
offset – The offset within the memory area to write the value.
value – The pointer value to write to the memory location./**
     * Writes a pointer value to the memory area at the specified offset.
     *
     * @param offset The offset within the memory area to write the value.
     * @param value The pointer value to write to the memory location.
     */
    abstract public void putAddress(long offset, long value);
    
    
Reads an array of bytes from the memory area at the specified offset.
Params:
offset – The offset within the memory area to read the bytes.
dst – The output byte array to place the data.
off – The offset within the byte array to start copying.
len – The length of data to read./**
     * Reads an array of bytes from the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to read the bytes.
     * @param dst The output byte array to place the data.
     * @param off The offset within the byte array to start copying.
     * @param len The length of data to read.
     */
    abstract public void get(long offset, byte[] dst, int off, int len);
    
    
Writes an array of bytes to the memory area at the specified offset.
Params:
offset – The offset within the memory area to start writing the bytes.
src – The byte array to write to the memory area.
off – The offset within the byte array to start copying.
len – The length of data to write./**
     * Writes an array of bytes to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to start writing the bytes.
     * @param src The byte array to write to the memory area.
     * @param off The offset within the byte array to start copying.
     * @param len The length of data to write.
     */
    abstract public void put(long offset, byte[] src, int off, int len);

    
Reads an array of shorts from the memory area at the specified offset.
Params:
offset – The offset within the memory area to read the shorts.
dst – The output array to place the data in.
off – The offset within the array to start copying.
len – The number of shorts to read./**
     * Reads an array of shorts from the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to read the shorts.
     * @param dst The output array to place the data in.
     * @param off The offset within the array to start copying.
     * @param len The number of shorts to read.
     */
    abstract public void get(long offset, short[] dst, int off, int len);

    
Writes an array of shorts to the memory area at the specified offset.
Params:
offset – The offset within the memory area to start writing the shorts.
src – The array to write to the memory area.
off – The offset within the array to start copying.
len – The number of shorts to write./**
     * Writes an array of shorts to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to start writing the shorts.
     * @param src The array to write to the memory area.
     * @param off The offset within the array to start copying.
     * @param len The number of shorts to write.
     */
    abstract public void put(long offset, short[] src, int off, int len);
    
    
Reads an array of ints from the memory area at the specified offset.
Params:
offset – The offset within the memory area to read the ints.
dst – The output array to place the data in.
off – The offset within the array to start copying.
len – The number of ints to read./**
     * Reads an array of ints from the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to read the ints.
     * @param dst The output array to place the data in.
     * @param off The offset within the array to start copying.
     * @param len The number of ints to read.
     */
    abstract public void get(long offset, int[] dst, int off, int len);

    
Writes an array of ints to the memory area at the specified offset.
Params:
offset – The offset within the memory area to start writing the ints.
src – The array to write to the memory area.
off – The offset within the array to start copying.
len – The number of ints to write./**
     * Writes an array of ints to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to start writing the ints.
     * @param src The array to write to the memory area.
     * @param off The offset within the array to start copying.
     * @param len The number of ints to write.
     */
    abstract public void put(long offset, int[] src, int off, int len);
    
    
Reads an array of longs from the memory area at the specified offset.
Params:
offset – The offset within the memory area to read the longs.
dst – The output array to place the data in.
off – The offset within the array to start copying.
len – The number of longs to read./**
     * Reads an array of longs from the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to read the longs.
     * @param dst The output array to place the data in.
     * @param off The offset within the array to start copying.
     * @param len The number of longs to read.
     */
    abstract public void get(long offset, long[] dst, int off, int len);

    
Writes an array of longs to the memory area at the specified offset.
Params:
offset – The offset within the memory area to start writing the longs.
src – The array to write to the memory area.
off – The offset within the array to start copying.
len – The number of longs to write./**
     * Writes an array of longs to the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to start writing the longs.
     * @param src The array to write to the memory area.
     * @param off The offset within the array to start copying.
     * @param len The number of longs to write.
     */
    abstract public void put(long offset, long[] src, int off, int len);

    
Reads an array of floats from the memory area at the specified offset.
Params:
offset – The offset within the memory area to read the floats.
dst – The output array to place the data in.
off – The offset within the array to start copying.
len – The number of floats to read./**
     * Reads an array of floats from the memory area at the specified offset.
     * 
     * @param offset The offset within the memory area to read the floats.
     * @param dst The output array to place the data in.
     * @param off The offset within the array to start copying.
     * @param len The number of floats to read.
     */
    abstract public void get(long offset, float[] dst, int off, int len);

    
Writes an array of floats to the memory area at the specified offset.
Params:
offset – The offset within the memory area to start writing the floats.
src – The array to write to the memory area.
off – The offset within the array to start copying.
len – The number of floats to write./**
     * Writes an array of floats to the memory area at the specified offset.
     *
     * @param offset The offset within the memory area to start writing the floats.
     * @param src The array to write to the memory area.
     * @param off The offset within the array to start copying.
     * @param len The number of floats to write.
     */
    abstract public void put(long offset, float[] src, int off, int len);

    
Reads an array of doubles from the memory area at the specified offset.
Params:
offset – The offset within the memory area to read the doubles.
dst – The output array to place the data in.
off – The offset within the array to start copying.
len – The number of doubles to read./**
     * Reads an array of doubles from the memory area at the specified offset.
     *
     * @param offset The offset within the memory area to read the doubles.
     * @param dst The output array to place the data in.
     * @param off The offset within the array to start copying.
     * @param len The number of doubles to read.
     */
    abstract public void get(long offset, double[] dst, int off, int len);

    
Writes an array of doubles to the memory area at the specified offset.
Params:
offset – The offset within the memory area to start writing the doubles.
src – The array to write to the memory area.
off – The offset within the array to start copying.
len – The number of doubles to write./**
     * Writes an array of doubles to the memory area at the specified offset.
     *
     * @param offset The offset within the memory area to start writing the doubles.
     * @param src The array to write to the memory area.
     * @param off The offset within the array to start copying.
     * @param len The number of doubles to write.
     */
    abstract public void put(long offset, double[] src, int off, int len);

    
Gets the first index within the memory area of a particular 8 bit value.
Params:
offset – The offset within the memory area to start searching.
value – The value to search for.
Returns:
The index of the value, relative to offset./**
     * Gets the first index within the memory area of a particular 8 bit value.
     * 
     * @param offset The offset within the memory area to start searching.
     * @param value The value to search for.
     * 
     * @return The index of the value, relative to offset.
     */
    abstract public int indexOf(long offset, byte value);
    
    
Gets the first index within the memory area of a particular 8 bit value.
Params:
offset – The offset within the memory area to start searching.
value – The value to search for.
Returns:
The index of the value, relative to offset./**
     * Gets the first index within the memory area of a particular 8 bit value.
     * 
     * @param offset The offset within the memory area to start searching.
     * @param value The value to search for.
     * 
     * @return The index of the value, relative to offset.
     */
    abstract public int indexOf(long offset, byte value, int maxlen);

    
Sets the contents of the memory area to the value.
Params:
offset – The offset within the memory area to start writing.
size – The number of bytes to set to the value.
value – The value to set each byte to./**
     * Sets the contents of the memory area to the value.
     * 
     * @param offset The offset within the memory area to start writing.
     * @param size The number of bytes to set to the value.
     * @param value The value to set each byte to.
     */
    abstract public void setMemory(long offset, long size, byte value);

    
Reads a zero terminated byte array (e.g. an ascii or utf-8 string)
Params:
offset – The offset within the memory area of the start of the string.
Returns:
A byte array containing a copy of the data./**
     * Reads a zero terminated byte array (e.g. an ascii or utf-8 string)
     *
     * @param offset The offset within the memory area of the start of the string.
     * @return A byte array containing a copy of the data.
     */
    abstract public byte[] getZeroTerminatedByteArray(long offset);

    
Reads a zero terminated byte array (e.g. an ascii or utf-8 string)
Params:
offset – The offset within the memory area of the start of the string.
maxlen – The maximum length to search for the zero byte terminator.
Returns:
A byte array containing a copy of the data./**
     * Reads a zero terminated byte array (e.g. an ascii or utf-8 string)
     *
     * @param offset The offset within the memory area of the start of the string.
     * @param maxlen The maximum length to search for the zero byte terminator.
     * @return A byte array containing a copy of the data.
     */
    abstract public byte[] getZeroTerminatedByteArray(long offset, int maxlen);

    
Writes a byte array to memory, and appends a zero terminator
Params:
offset – The offset within the memory area of the start of the string.
bytes – The byte array to write to the memory.
off – The offset with the byte array to start copying.
maxlen – The number of bytes of the byte array to write to the memory area. (not including zero byte)/**
     * Writes a byte array to memory, and appends a zero terminator
     *
     * @param offset The offset within the memory area of the start of the string.
     * @param bytes The byte array to write to the memory.
     * @param off The offset with the byte array to start copying.
     * @param maxlen The number of bytes of the byte array to write to the memory area. (not including zero byte)
     */
    abstract public void putZeroTerminatedByteArray(long offset, byte[] bytes, int off, int len);
}