com.yahoo.memory.WritableBuffer Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of memory Show documentation
Show all versions of memory Show documentation
Memory provides high-performance native memory access.
/*
* Copyright 2017, Yahoo! Inc. Licensed under the terms of the
* Apache License 2.0. See LICENSE file at the project root for terms.
*/
package com.yahoo.memory;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
/**
* Provides read and write, positional primitive and primitive array access to any of the four
* resources mentioned at the package level.
*
* @author Roman Leventov
* @author Lee Rhodes
*/
public abstract class WritableBuffer extends Buffer {
//Pass-through ctor
WritableBuffer(final Object unsafeObj, final long nativeBaseOffset,
final long regionOffset, final long capacityBytes) {
super(unsafeObj, nativeBaseOffset, regionOffset, capacityBytes);
}
//BYTE BUFFER
/**
* Accesses the given ByteBuffer for write operations. The returned WritableBuffer object has
* the same byte order, as the given ByteBuffer, unless the capacity of the given ByteBuffer is
* zero, then byte order of the returned WritableBuffer object, as well as backing storage and
* read-only status are unspecified.
* @param byteBuf the given ByteBuffer, must not be null.
* @return a new WritableBuffer for write operations on the given ByteBuffer.
*/
public static WritableBuffer wrap(final ByteBuffer byteBuf) {
return wrap(byteBuf, byteBuf.order());
}
/**
* Accesses the given ByteBuffer for write operations. The returned WritableBuffer object has
* the given byte order, ignoring the byte order of the given ByteBuffer. If the capacity of
* the given ByteBuffer is zero the byte order of the returned WritableBuffer object
* (as well as backing storage) is unspecified.
* @param byteBuf the given ByteBuffer, must not be null
* @param byteOrder the byte order to be used, which may be independent of the byte order
* state of the given ByteBuffer
* @return a new WritableBuffer for write operations on the given ByteBuffer.
*/
public static WritableBuffer wrap(final ByteBuffer byteBuf, final ByteOrder byteOrder) {
final BaseWritableMemoryImpl wmem =
BaseWritableMemoryImpl.wrapByteBuffer(byteBuf, false, byteOrder);
final WritableBuffer wbuf = wmem.asWritableBufferImpl(false, byteOrder);
wbuf.setStartPositionEnd(0, byteBuf.position(), byteBuf.limit());
return wbuf;
}
//MAP
//Use WritableMemory for mapping files and then asWritableBuffer()
//ALLOCATE DIRECT
//Use WritableMemory to allocate direct memory and then asWritableBuffer().
//DUPLICATES
/**
* Returns a duplicate writable view of this Buffer with the same but independent values of
* start, position and end.
*
* - Returned object's origin = this object's origin
* - Returned object's start = this object's start
* - Returned object's position = this object's position
* - Returned object's end = this object's end
* - Returned object's capacity = this object' capacityBytes
* - Returned object's start, position and end are mutable and
* independent of this object's start, position and end
*
* If this object's capacity is zero, the returned object is effectively immutable and
* the backing storage and byte order are unspecified.
* @return a duplicate writable view of this Buffer with the same but independent values of
* start, position and end.
*/
public abstract WritableBuffer writableDuplicate();
/**
* Returns a duplicate writable view of this Buffer with the same but independent values of
* start, position and end, but with the specified byteOrder.
*
* - Returned object's origin = this object's origin
* - Returned object's start = this object's start
* - Returned object's position = this object's position
* - Returned object's end = this object's end
* - Returned object's capacity = this object' capacityBytes
* - Returned object's start, position and end are mutable and
* independent of this object's start, position and end
*
* If this object's capacity is zero, the returned object is effectively immutable and
* the backing storage and byte order are unspecified.
* @param byteOrder the given ByteOrder.
* @return a duplicate writable view of this Buffer with the same but independent values of
* start, position and end.
*/
public abstract WritableBuffer writableDuplicate(ByteOrder byteOrder);
//REGIONS
/**
* A writable region is a writable view of this object.
*
* - Returned object's origin = this object's position
* - Returned object's start = 0
* - Returned object's position = 0
* - Returned object's end = this object's (end - position)
* - Returned object's capacity = this object's (end - position)
* - Returned object's start, position and end are mutable and
* independent of this object's start, position and end
*
* If this object's capacity is zero, the returned object is effectively immutable and
* the backing storage and byte order are unspecified.
* @return a new WritableBuffer representing the defined writable region.
*/
public abstract WritableBuffer writableRegion();
/**
* A writable region is a writable view of this object.
*
* - Returned object's origin = this objects' origin + offsetBytes
* - Returned object's start = 0
* - Returned object's position = 0
* - Returned object's end = capacityBytes
* - Returned object's capacity = capacityBytes
* - Returned object's start, position and end are mutable and
* independent of this object's start, position and end
* - Returned object's byte order = byteOrder
*
* If this object's capacity is zero, the returned object is effectively immutable and
* the backing storage and byte order are unspecified.
*
* Note: asWritableMemory() and asMemory()
* will return the originating Memory byte order.
* @param offsetBytes the starting offset with respect to the origin of this WritableBuffer
* @param capacityBytes the capacity of the returned region in bytes
* @param byteOrder the given byte order
* @return a new WritableBuffer representing the defined writable region
* with the given offsetBytes, capacityBytes and byte order.
*/
public abstract WritableBuffer writableRegion(long offsetBytes, long capacityBytes,
ByteOrder byteOrder);
//AS MEMORY
/**
* Convert this WritableBuffer to a WritableMemory.
* If this object's capacity is zero, the returned object is effectively immutable and
* the backing storage and byte order are unspecified.
* @return WritableMemory
*/
public abstract WritableMemory asWritableMemory();
//ACCESS PRIMITIVE HEAP ARRAYS for write
//use WritableMemory and then asWritableBuffer().
//END OF CONSTRUCTOR-TYPE METHODS
//PRIMITIVE putX() and putXArray()
/**
* Puts the boolean value at the current position.
* Increments the position by 1.
* @param value the value to put
*/
public abstract void putBoolean(boolean value);
/**
* Puts the boolean value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start.
* @param value the value to put
*/
public abstract void putBoolean(long offsetBytes, boolean value);
/**
* Puts the boolean array at the current position.
* Increments the position by lengthBooleans - srcOffsetBooleans.
* @param srcArray The source array.
* @param srcOffsetBooleans offset in array units
* @param lengthBooleans number of array units to transfer
*/
public abstract void putBooleanArray(boolean[] srcArray, int srcOffsetBooleans,
int lengthBooleans);
/**
* Puts the byte value at the current position.
* Increments the position by Byte.BYTES.
* @param value the value to put
*/
public abstract void putByte(byte value);
/**
* Puts the byte value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putByte(long offsetBytes, byte value);
/**
* Puts the byte array at the current position.
* Increments the position by Byte.BYTES * (lengthBytes - srcOffsetBytes).
* @param srcArray The source array.
* @param srcOffsetBytes offset in array units
* @param lengthBytes number of array units to transfer
*/
public abstract void putByteArray(byte[] srcArray, int srcOffsetBytes, int lengthBytes);
/**
* Puts the char value at the current position.
* Increments the position by Character.BYTES.
* @param value the value to put
*/
public abstract void putChar(char value);
/**
* Puts the char value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putChar(long offsetBytes, char value);
/**
* Puts the char array at the current position.
* Increments the position by Character.BYTES * (lengthChars - srcOffsetChars).
* @param srcArray The source array.
* @param srcOffsetChars offset in array units
* @param lengthChars number of array units to transfer
*/
public abstract void putCharArray(char[] srcArray, int srcOffsetChars, int lengthChars);
/**
* Puts the double value at the current position.
* Increments the position by Double.BYTES.
* @param value the value to put
*/
public abstract void putDouble(double value);
/**
* Puts the double value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putDouble(long offsetBytes, double value);
/**
* Puts the double array at the current position.
* Increments the position by Double.BYTES * (lengthDoubles - srcOffsetDoubles).
* @param srcArray The source array.
* @param srcOffsetDoubles offset in array units
* @param lengthDoubles number of array units to transfer
*/
public abstract void putDoubleArray(double[] srcArray, int srcOffsetDoubles, int lengthDoubles);
/**
* Puts the float value at the current position.
* Increments the position by Float.BYTES.
* @param value the value to put
*/
public abstract void putFloat(float value);
/**
* Puts the float value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putFloat(long offsetBytes, float value);
/**
* Puts the float array at the current position.
* Increments the position by Float.BYTES * (lengthFloats - srcOffsetFloats).
* @param srcArray The source array.
* @param srcOffsetFloats offset in array units
* @param lengthFloats number of array units to transfer
*/
public abstract void putFloatArray(float[] srcArray, int srcOffsetFloats, int lengthFloats);
/**
* Puts the int value at the current position.
* Increments the position by Integer.BYTES.
* @param value the value to put
*/
public abstract void putInt(int value);
/**
* Puts the int value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putInt(long offsetBytes, int value);
/**
* Puts the int array at the current position.
* Increments the position by Integer.BYTES * (lengthInts - srcOffsetInts).
* @param srcArray The source array.
* @param srcOffsetInts offset in array units
* @param lengthInts number of array units to transfer
*/
public abstract void putIntArray(int[] srcArray, int srcOffsetInts, int lengthInts);
/**
* Puts the long value at the current position.
* Increments the position by Long.BYTES.
* @param value the value to put
*/
public abstract void putLong(long value);
/**
* Puts the long value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putLong(long offsetBytes, long value);
/**
* Puts the long array at the current position.
* Increments the position by Long.BYTES * (lengthLongs - srcOffsetLongs).
* @param srcArray The source array.
* @param srcOffsetLongs offset in array units
* @param lengthLongs number of array units to transfer
*/
public abstract void putLongArray(long[] srcArray, int srcOffsetLongs, int lengthLongs);
/**
* Puts the short value at the current position.
* Increments the position by Short.BYTES.
* @param value the value to put
*/
public abstract void putShort(short value);
/**
* Puts the short value at the given offset.
* This does not change the position.
* @param offsetBytes offset bytes relative to this WritableMemory start
* @param value the value to put
*/
public abstract void putShort(long offsetBytes, short value);
/**
* Puts the short array at the current position.
* Increments the position by Short.BYTES * (lengthShorts - srcOffsetShorts).
* @param srcArray The source array.
* @param srcOffsetShorts offset in array units
* @param lengthShorts number of array units to transfer
*/
public abstract void putShortArray(short[] srcArray, int srcOffsetShorts, int lengthShorts);
//OTHER WRITE METHODS
/**
* Returns the primitive backing array, otherwise null.
* @return the primitive backing array, otherwise null.
*/
public abstract Object getArray();
/**
* Clears all bytes of this Buffer from position to end to zero. The position will be set to end.
*/
public abstract void clear();
/**
* Fills this Buffer from position to end with the given byte value.
* The position will be set to end.
* @param value the given byte value
*/
public abstract void fill(byte value);
//OTHER WRITABLE API METHODS
/**
* For Direct Memory only. Other types of backing resources will return null.
* Gets the MemoryRequestServer object used by dynamic off-heap (Direct) memory objects
* to request additional memory.
* Set using {@link WritableMemory#allocateDirect(long, MemoryRequestServer)}.
* If not explicity set, this returns the {@link DefaultMemoryRequestServer}.
* @return the MemoryRequestServer object (if direct memory) or null.
*/
@Override
public MemoryRequestServer getMemoryRequestServer() {
return null;
}
}