WritableMemory (com.yahoo.datasketches:memory 0.12.1 API)

java.lang.Object
- com.yahoo.memory.Memory
- - com.yahoo.memory.WritableMemory

```
public abstract class WritableMemory
extends Memory
```
Provides read and write primitive and primitive array access to any of the four resources mentioned at the package level.

Author:

Roman Leventov, Lee Rhodes

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static WritableMemory`	`allocate(int capacityBytes)` Creates on-heap WritableMemory with the given capacity and the native byte order.
`static WritableMemory`	`allocate(int capacityBytes, ByteOrder byteOrder)` Creates on-heap WritableMemory with the given capacity and the given byte order.
`static WritableDirectHandle`	`allocateDirect(long capacityBytes)` Allocates and provides access to capacityBytes directly in native (off-heap) memory leveraging the WritableMemory API.
`static WritableDirectHandle`	`allocateDirect(long capacityBytes, MemoryRequestServer memReqSvr)` Allocates and provides access to capacityBytes directly in native (off-heap) memory leveraging the WritableMemory API.
`abstract WritableBuffer`	`asWritableBuffer()` Returns a new WritableBuffer with a writable view of this object.
`abstract WritableBuffer`	`asWritableBuffer(ByteOrder byteOrder)` Returns a new WritableBuffer with a writable view of this object with the given byte order.
`void`	`checkValidAndBounds(long offsetBytes, long lengthBytes)` Checks that the specified range of bytes is within bounds of this object, throws `IllegalArgumentException` if it's not: i.
`abstract void`	`clear()` Clears all bytes of this Memory to zero
`abstract void`	`clear(long offsetBytes, long lengthBytes)` Clears a portion of this Memory to zero.
`abstract void`	`clearBits(long offsetBytes, byte bitMask)` Clears the bits defined by the bitMask
`abstract boolean`	`compareAndSwapLong(long offsetBytes, long expect, long update)` Atomically sets the current value at the memory location to the given updated value if and only if the current value `==` the expected value.
`boolean`	`equals(Object that)` Returns true if the given object is an instance of this class and has equal data contents.
`boolean`	`equalTo(long thisOffsetBytes, Object that, long thatOffsetBytes, long lengthBytes)` Returns true if the given object is an instance of this class and has equal contents to this object in the given range of bytes.
`abstract void`	`fill(byte value)` Fills all bytes of this Memory region to the given byte value.
`abstract void`	`fill(long offsetBytes, long lengthBytes, byte value)` Fills a portion of this Memory region to the given byte value.
`abstract long`	`getAndAddLong(long offsetBytes, long delta)` Atomically adds the given value to the long located at offsetBytes.
`abstract long`	`getAndSetLong(long offsetBytes, long newValue)` Atomically exchanges the given value with the current value located at offsetBytes.
`abstract Object`	`getArray()` Returns the primitive backing array, otherwise null.
`ByteBuffer`	`getByteBuffer()` Gets the backing ByteBuffer if it exists, otherwise returns null.
`ByteOrder`	`getByteOrder()` Gets the current ByteOrder.
`long`	`getCapacity()` Gets the capacity of this object in bytes
`long`	`getCumulativeOffset()` Gets the cumulative offset in bytes of this object from the backing resource.
`long`	`getCumulativeOffset(long offsetBytes)` Gets the cumulative offset in bytes of this object from the backing resource including the given offsetBytes.
`static long`	`getCurrentDirectMemoryAllocated()` Gets the current size of active direct memory allocated.
`static long`	`getCurrentDirectMemoryAllocations()` Gets the current number of active direct memory allocations.
`static long`	`getCurrentDirectMemoryMapAllocated()` Gets the current size of active direct memory map allocated.
`static long`	`getCurrentDirectMemoryMapAllocations()` Gets the current number of active direct memory map allocations.
`MemoryRequestServer`	`getMemoryRequestServer()` For Direct Memory only.
`long`	`getRegionOffset()` Returns the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
`long`	`getRegionOffset(long offsetBytes)` Returns the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
`boolean`	`hasArray()` Returns true if this object is backed by an on-heap primitive array
`boolean`	`hasByteBuffer()` Returns true if this Memory is backed by a ByteBuffer.
`int`	`hashCode()` Returns the hashCode of this object.
`boolean`	`isDirect()` Returns true if the backing resource is direct (off-heap) memory.
`boolean`	`isNativeOrder()` Returns true if the current byte order is native order.
`boolean`	`isReadOnly()` Returns true if this object or the backing resource is read-only.
`boolean`	`isSameResource(Object that)` Returns true if the backing resource of this is identical with the backing resource of that.
`boolean`	`isValid()` Returns true if this object is valid and has not been closed.
`static WritableMapHandle`	`map(File file)` Maps the entire given file into native-ordered Memory for write operations (including those > 2GB).
`static WritableMapHandle`	`map(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder)` Maps the specified portion of the given file into Memory for write operations (including those > 2GB).
`abstract void`	`putBoolean(long offsetBytes, boolean value)` Puts the boolean value at the given offset
`abstract void`	`putBooleanArray(long offsetBytes, boolean[] srcArray, int srcOffsetBooleans, int lengthBooleans)` Puts the boolean array at the given offset
`abstract void`	`putByte(long offsetBytes, byte value)` Puts the byte value at the given offset
`abstract void`	`putByteArray(long offsetBytes, byte[] srcArray, int srcOffsetBytes, int lengthBytes)` Puts the byte array at the given offset
`abstract void`	`putChar(long offsetBytes, char value)` Puts the char value at the given offset
`abstract void`	`putCharArray(long offsetBytes, char[] srcArray, int srcOffsetChars, int lengthChars)` Puts the char array at the given offset
`abstract long`	`putCharsToUtf8(long offsetBytes, CharSequence src)` Encodes characters from the given CharSequence into UTF-8 bytes and puts them into this WritableMemory begining at the given offsetBytes.
`abstract void`	`putDouble(long offsetBytes, double value)` Puts the double value at the given offset
`abstract void`	`putDoubleArray(long offsetBytes, double[] srcArray, int srcOffsetDoubles, int lengthDoubles)` Puts the double array at the given offset
`abstract void`	`putFloat(long offsetBytes, float value)` Puts the float value at the given offset
`abstract void`	`putFloatArray(long offsetBytes, float[] srcArray, int srcOffsetFloats, int lengthFloats)` Puts the float array at the given offset
`abstract void`	`putInt(long offsetBytes, int value)` Puts the int value at the given offset
`abstract void`	`putIntArray(long offsetBytes, int[] srcArray, int srcOffsetInts, int lengthInts)` Puts the int array at the given offset
`abstract void`	`putLong(long offsetBytes, long value)` Puts the long value at the given offset
`abstract void`	`putLongArray(long offsetBytes, long[] srcArray, int srcOffsetLongs, int lengthLongs)` Puts the long array at the given offset
`abstract void`	`putShort(long offsetBytes, short value)` Puts the short value at the given offset
`abstract void`	`putShortArray(long offsetBytes, short[] srcArray, int srcOffsetShorts, int lengthShorts)` Puts the short array at the given offset
`abstract void`	`setBits(long offsetBytes, byte bitMask)` Sets the bits defined by the bitMask
`String`	`toHexString(String header, long offsetBytes, int lengthBytes)` Returns a formatted hex string of a range of this object.
`static WritableMemory`	`wrap(boolean[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(byte[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(byte[] arr, ByteOrder byteOrder)` Wraps the given primitive array for write operations with the given byte order.
`static WritableMemory`	`wrap(byte[] arr, int offsetBytes, int lengthBytes, ByteOrder byteOrder)` Wraps the given primitive array for write operations with the given byte order.
`static WritableMemory`	`wrap(ByteBuffer byteBuf)` Accesses the given ByteBuffer for write operations.
`static WritableMemory`	`wrap(ByteBuffer byteBuf, ByteOrder byteOrder)` Accesses the given ByteBuffer for write operations.
`static WritableMemory`	`wrap(char[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(double[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(float[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(int[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(long[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`static WritableMemory`	`wrap(short[] arr)` Wraps the given primitive array for write operations assuming native byte order.
`abstract WritableMemory`	`writableRegion(long offsetBytes, long capacityBytes)` A writable region is a writable view of this object.
`abstract WritableMemory`	`writableRegion(long offsetBytes, long capacityBytes, ByteOrder byteOrder)` A writable region is a writable view of this object.
`long`	`xxHash64(long offsetBytes, long lengthBytes, long seed)` Returns the 64-bit hash of the sequence of bytes in this object specified by offsetBytes, lengthBytes and a seed.

Methods inherited from class com.yahoo.memory.Memory
asBuffer, asBuffer, compareTo, copyTo, getBoolean, getBooleanArray, getByte, getByteArray, getChar, getCharArray, getCharsFromUtf8, getCharsFromUtf8, getDouble, getDoubleArray, getFloat, getFloatArray, getInt, getIntArray, getLong, getLongArray, getShort, getShortArray, region, region, unsafeByteBufferView, writeTo

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - wrap
```
public static WritableMemory wrap(ByteBuffer byteBuf)
```
    Accesses the given ByteBuffer for write operations. The returned WritableMemory 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 WritableMemory object, as well as backing storage and read-only status are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    byteBuf - the given ByteBuffer
    
    Returns:
    
    a new WritableMemory for write operations on the given ByteBuffer.
  - wrap
```
public static WritableMemory wrap(ByteBuffer byteBuf,
                                  ByteOrder byteOrder)
```
    Accesses the given ByteBuffer for write operations. The returned WritableMemory 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 WritableMemory object (as well as backing storage) is unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    byteBuf - the given ByteBuffer, must not be null
    
    byteOrder - the byte order to be used, which may be independent of the byte order state of the given ByteBuffer
    
    Returns:
    
    a new WritableMemory for write operations on the given ByteBuffer.
  - map
```
public static WritableMapHandle map(File file)
                             throws IOException
```
    Maps the entire given file into native-ordered Memory for write operations (including those > 2GB). Calling this method is equivalent to calling map(file, 0, file.length(), ByteOrder.nativeOrder()).
    Note: Always qualify this method with the class name, e.g., WritableMemory.map(...).
    
    Parameters:
    
    file - the given file to map
    
    Returns:
    
    WritableMapHandle for managing the mapped Memory
    
    Throws:
    
    IOException - file not found or a RuntimeException.
  - map
```
public static WritableMapHandle map(File file,
                                    long fileOffsetBytes,
                                    long capacityBytes,
                                    ByteOrder byteOrder)
                             throws IOException
```
    Maps the specified portion of the given file into Memory for write operations (including those > 2GB).
    Note: Always qualify this method with the class name, e.g., WritableMemory.map(...).
    
    Parameters:
    
    file - the given file to map. It may not be null.
    
    fileOffsetBytes - the position in the given file in bytes. It may not be negative.
    
    capacityBytes - the size of the mapped Memory. It may not be negative or zero.
    
    byteOrder - the byte order to be used for the given file. It may not be null.
    
    Returns:
    
    WritableMapHandle for managing the mapped Memory
    
    Throws:
    
    IOException - file not found or RuntimeException, etc.
  - allocateDirect
```
public static WritableDirectHandle allocateDirect(long capacityBytes)
```
    Allocates and provides access to capacityBytes directly in native (off-heap) memory leveraging the WritableMemory API. Native byte order is assumed. The allocated memory will be 8-byte aligned, but may not be page aligned. If capacityBytes is zero, byte order, backing storage and read-only status of the WritableMemory object, returned from WritableHandle.get() are unspecified.
    The default MemoryRequestServer, which allocates any request for memory onto the heap, will be used.
    
    NOTE: Native/Direct memory acquired using Unsafe may have garbage in it. It is the responsibility of the using class to clear this memory, if required, and to call close() when done.
    
    Parameters:
    
    capacityBytes - the size of the desired memory in bytes.
    
    Returns:
    
    WritableDirectHandle for this off-heap resource
  - allocateDirect
```
public static WritableDirectHandle allocateDirect(long capacityBytes,
                                                  MemoryRequestServer memReqSvr)
```
    Allocates and provides access to capacityBytes directly in native (off-heap) memory leveraging the WritableMemory API. The allocated memory will be 8-byte aligned, but may not be page aligned. If capacityBytes is zero, byte order, backing storage and read-only status of the WritableMemory object, returned from WritableHandle.get() are unspecified.
    NOTE: Native/Direct memory acquired using Unsafe may have garbage in it. It is the responsibility of the using class to clear this memory, if required, and to call close() when done.
    
    Parameters:
    
    capacityBytes - the size of the desired memory in bytes.
    
    memReqSvr - A user-specified MemoryRequestServer. This is a callback mechanism for a user client of direct memory to request more memory.
    
    Returns:
    
    WritableHandle for this off-heap resource
  - writableRegion
```
public abstract WritableMemory writableRegion(long offsetBytes,
                                              long capacityBytes)
```
    A writable region is a writable view of this object. This returns a new WritableMemory representing the defined writable region with the given offsetBytes and capacityBytes.
    - Returned object's origin = this objects' origin + offsetBytes
    - Returned object's capacity = capacityBytes
    If the given capacityBytes is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.
    Parameters:
    
    offsetBytes - the starting offset with respect to this object.
    
    capacityBytes - the capacity of the returned object in bytes.
    
    Returns:
    
    a new WritableMemory representing the defined writable region.
  - writableRegion
```
public abstract WritableMemory writableRegion(long offsetBytes,
                                              long capacityBytes,
                                              ByteOrder byteOrder)
```
    A writable region is a writable view of this object. This returns a new WritableMemory representing the defined writable region with the given offsetBytes, capacityBytes and byte order.
    - Returned object's origin = this objects' origin + offsetBytes
    - Returned object's capacity = capacityBytes
    - Returned object's byte order = byteOrder
    If the given capacityBytes is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.
    Parameters:
    
    offsetBytes - the starting offset with respect to this object.
    
    capacityBytes - the capacity of the returned object in bytes.
    
    byteOrder - the given byte order
    
    Returns:
    
    a new WritableMemory representing the defined writable region.
  - asWritableBuffer
```
public abstract WritableBuffer asWritableBuffer()
```
    Returns a new WritableBuffer with a writable view of this object.
    - Returned object's origin = this object's origin
    - Returned object's start = 0
    - Returned object's position = 0
    - Returned object's end = this object's capacity
    - Returned object's capacity = this object's capacity
    - Returned object's start, position and end are mutable
    If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.
    Returns:
    
    a new WritableBuffer with a view of this WritableMemory
  - asWritableBuffer
```
public abstract WritableBuffer asWritableBuffer(ByteOrder byteOrder)
```
    Returns a new WritableBuffer with a writable view of this object with the given byte order.
    - Returned object's origin = this object's origin
    - Returned object's start = 0
    - Returned object's position = 0
    - Returned object's end = this object's capacity
    - Returned object's capacity = this object's capacity
    - Returned object's start, position and end are mutable
    If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.
    Parameters:
    
    byteOrder - the given byte order
    
    Returns:
    
    a new WritableBuffer with a view of this WritableMemory
  - allocate
```
public static WritableMemory allocate(int capacityBytes)
```
    Creates on-heap WritableMemory with the given capacity and the native byte order. If the given capacityBytes is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    
    Parameters:
    
    capacityBytes - the given capacity in bytes.
    
    Returns:
    
    a new WritableMemory for write operations on a new byte array.
  - allocate
```
public static WritableMemory allocate(int capacityBytes,
                                      ByteOrder byteOrder)
```
    Creates on-heap WritableMemory with the given capacity and the given byte order. If the given capacityBytes is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    
    Parameters:
    
    capacityBytes - the given capacity in bytes.
    
    byteOrder - the given byte order to allocate new Memory object with.
    
    Returns:
    
    a new WritableMemory for write operations on a new byte array.
  - wrap
```
public static WritableMemory wrap(boolean[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(byte[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(byte[] arr,
                                  ByteOrder byteOrder)
```
    Wraps the given primitive array for write operations with the given byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    byteOrder - the byte order to be used
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(byte[] arr,
                                  int offsetBytes,
                                  int lengthBytes,
                                  ByteOrder byteOrder)
```
    Wraps the given primitive array for write operations with the given byte order. If the given lengthBytes is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    offsetBytes - the byte offset into the given array
    
    lengthBytes - the number of bytes to include from the given array
    
    byteOrder - the byte order to be used
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(char[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(short[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(int[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(long[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(float[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - wrap
```
public static WritableMemory wrap(double[] arr)
```
    Wraps the given primitive array for write operations assuming native byte order. If the array size is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.
    Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
    
    Parameters:
    
    arr - the given primitive array.
    
    Returns:
    
    a new WritableMemory for write operations on the given primitive array.
  - putBoolean
```
public abstract void putBoolean(long offsetBytes,
                                boolean value)
```
    Puts the boolean value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putBooleanArray
```
public abstract void putBooleanArray(long offsetBytes,
                                     boolean[] srcArray,
                                     int srcOffsetBooleans,
                                     int lengthBooleans)
```
    Puts the boolean array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetBooleans - offset in array units
    
    lengthBooleans - number of array units to transfer
  - putByte
```
public abstract void putByte(long offsetBytes,
                             byte value)
```
    Puts the byte value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putByteArray
```
public abstract void putByteArray(long offsetBytes,
                                  byte[] srcArray,
                                  int srcOffsetBytes,
                                  int lengthBytes)
```
    Puts the byte array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetBytes - offset in array units
    
    lengthBytes - number of array units to transfer
  - putChar
```
public abstract void putChar(long offsetBytes,
                             char value)
```
    Puts the char value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putCharArray
```
public abstract void putCharArray(long offsetBytes,
                                  char[] srcArray,
                                  int srcOffsetChars,
                                  int lengthChars)
```
    Puts the char array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetChars - offset in array units
    
    lengthChars - number of array units to transfer
  - putCharsToUtf8
```
public abstract long putCharsToUtf8(long offsetBytes,
                                    CharSequence src)
```
    Encodes characters from the given CharSequence into UTF-8 bytes and puts them into this WritableMemory begining at the given offsetBytes. This is specifically designed to reduce the production of intermediate objects (garbage), thus significantly reducing pressure on the JVM Garbage Collector.
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    src - The source CharSequence to be encoded and put into this WritableMemory. It is the responsibility of the caller to provide sufficient capacity in this WritableMemory for the encoded Utf8 bytes. Characters outside the ASCII range can require 2, 3 or 4 bytes per character to encode.
    
    Returns:
    
    the number of bytes encoded
  - putDouble
```
public abstract void putDouble(long offsetBytes,
                               double value)
```
    Puts the double value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putDoubleArray
```
public abstract void putDoubleArray(long offsetBytes,
                                    double[] srcArray,
                                    int srcOffsetDoubles,
                                    int lengthDoubles)
```
    Puts the double array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetDoubles - offset in array units
    
    lengthDoubles - number of array units to transfer
  - putFloat
```
public abstract void putFloat(long offsetBytes,
                              float value)
```
    Puts the float value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putFloatArray
```
public abstract void putFloatArray(long offsetBytes,
                                   float[] srcArray,
                                   int srcOffsetFloats,
                                   int lengthFloats)
```
    Puts the float array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetFloats - offset in array units
    
    lengthFloats - number of array units to transfer
  - putInt
```
public abstract void putInt(long offsetBytes,
                            int value)
```
    Puts the int value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putIntArray
```
public abstract void putIntArray(long offsetBytes,
                                 int[] srcArray,
                                 int srcOffsetInts,
                                 int lengthInts)
```
    Puts the int array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetInts - offset in array units
    
    lengthInts - number of array units to transfer
  - putLong
```
public abstract void putLong(long offsetBytes,
                             long value)
```
    Puts the long value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putLongArray
```
public abstract void putLongArray(long offsetBytes,
                                  long[] srcArray,
                                  int srcOffsetLongs,
                                  int lengthLongs)
```
    Puts the long array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetLongs - offset in array units
    
    lengthLongs - number of array units to transfer
  - putShort
```
public abstract void putShort(long offsetBytes,
                              short value)
```
    Puts the short value at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    value - the value to put
  - putShortArray
```
public abstract void putShortArray(long offsetBytes,
                                   short[] srcArray,
                                   int srcOffsetShorts,
                                   int lengthShorts)
```
    Puts the short array at the given offset
    
    Parameters:
    
    offsetBytes - offset bytes relative to this WritableMemory start
    
    srcArray - The source array.
    
    srcOffsetShorts - offset in array units
    
    lengthShorts - number of array units to transfer
  - getAndAddLong
```
public abstract long getAndAddLong(long offsetBytes,
                                   long delta)
```
    Atomically adds the given value to the long located at offsetBytes.
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start
    
    delta - the amount to add
    
    Returns:
    
    the the previous value
  - compareAndSwapLong
```
public abstract boolean compareAndSwapLong(long offsetBytes,
                                           long expect,
                                           long update)
```
    Atomically sets the current value at the memory location to the given updated value if and only if the current value == the expected value.
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start
    
    expect - the expected value
    
    update - the new value
    
    Returns:
    
    true if successful. False return indicates that the current value at the memory location was not equal to the expected value.
  - getAndSetLong
```
public abstract long getAndSetLong(long offsetBytes,
                                   long newValue)
```
    Atomically exchanges the given value with the current value located at offsetBytes.
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start
    
    newValue - new value
    
    Returns:
    
    the previous value
  - getArray
```
public abstract Object getArray()
```
    Returns the primitive backing array, otherwise null.
    
    Returns:
    
    the primitive backing array, otherwise null.
  - clear
```
public abstract void clear()
```
    Clears all bytes of this Memory to zero
  - clear
```
public abstract void clear(long offsetBytes,
                           long lengthBytes)
```
    Clears a portion of this Memory to zero.
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start
    
    lengthBytes - the length in bytes
  - clearBits
```
public abstract void clearBits(long offsetBytes,
                               byte bitMask)
```
    Clears the bits defined by the bitMask
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start.
    
    bitMask - the bits set to one will be cleared
  - fill
```
public abstract void fill(byte value)
```
    Fills all bytes of this Memory region to the given byte value.
    
    Parameters:
    
    value - the given byte value
  - fill
```
public abstract void fill(long offsetBytes,
                          long lengthBytes,
                          byte value)
```
    Fills a portion of this Memory region to the given byte value.
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start
    
    lengthBytes - the length in bytes
    
    value - the given byte value
  - setBits
```
public abstract void setBits(long offsetBytes,
                             byte bitMask)
```
    Sets the bits defined by the bitMask
    
    Parameters:
    
    offsetBytes - offset bytes relative to this Memory start
    
    bitMask - the bits set to one will be set
  - getMemoryRequestServer
```
public MemoryRequestServer getMemoryRequestServer()
```
    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 allocateDirect(long, MemoryRequestServer). If not explicity set, this returns the DefaultMemoryRequestServer.
    
    Returns:
    
    the MemoryRequestServer object (if direct memory) or null.
  - equals
```
public final boolean equals(Object that)
```
    Returns true if the given object is an instance of this class and has equal data contents.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    that - the given object
    
    Returns:
    
    true if the given Object is an instance of this class and has equal data contents.
  - equalTo
```
public final boolean equalTo(long thisOffsetBytes,
                             Object that,
                             long thatOffsetBytes,
                             long lengthBytes)
```
    Returns true if the given object is an instance of this class and has equal contents to this object in the given range of bytes. This will also check two distinct ranges within the same object for eauals.
    
    Parameters:
    
    thisOffsetBytes - the starting offset in bytes for this object.
    
    that - the given object
    
    thatOffsetBytes - the starting offset in bytes for the given object
    
    lengthBytes - the size of the range in bytes
    
    Returns:
    
    true if the given object has equal contents to this object in the given range of bytes.
  - getByteBuffer
```
public ByteBuffer getByteBuffer()
```
    Gets the backing ByteBuffer if it exists, otherwise returns null.
    
    Returns:
    
    the backing ByteBuffer if it exists, otherwise returns null.
  - getByteOrder
```
public final ByteOrder getByteOrder()
```
    Gets the current ByteOrder. This may be different from the ByteOrder of the backing resource.
    
    Returns:
    
    the current ByteOrder.
  - getCapacity
```
public final long getCapacity()
```
    Gets the capacity of this object in bytes
    
    Returns:
    
    the capacity of this object in bytes
  - getCumulativeOffset
```
public final long getCumulativeOffset()
```
    Gets the cumulative offset in bytes of this object from the backing resource. This offset may also include other offset components such as the native off-heap memory address, DirectByteBuffer split offsets, region offsets, and unsafe arrayBaseOffsets.
    
    Returns:
    
    the cumulative offset in bytes of this object from the backing resource.
  - getCumulativeOffset
```
public final long getCumulativeOffset(long offsetBytes)
```
    Gets the cumulative offset in bytes of this object from the backing resource including the given offsetBytes. This offset may also include other offset components such as the native off-heap memory address, DirectByteBuffer split offsets, region offsets, and unsafe arrayBaseOffsets.
    
    Parameters:
    
    offsetBytes - offset to be added to the cumulative offset.
    
    Returns:
    
    the cumulative offset in bytes of this object from the backing resource including the given offsetBytes.
  - getRegionOffset
```
public final long getRegionOffset()
```
    Returns the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
    
    Returns:
    
    the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
  - getRegionOffset
```
public final long getRegionOffset(long offsetBytes)
```
    Returns the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
    
    Parameters:
    
    offsetBytes - the given offsetBytes
    
    Returns:
    
    the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
  - hasArray
```
public final boolean hasArray()
```
    Returns true if this object is backed by an on-heap primitive array
    
    Returns:
    
    true if this object is backed by an on-heap primitive array
  - hashCode
```
public final int hashCode()
```
    Returns the hashCode of this object.
    The hash code of this object depends upon all of its contents. Because of this, it is inadvisable to use these objects as keys in hash maps or similar data structures unless it is known that their contents will not change.
    
    If it is desirable to use these objects in a hash map depending only on object identity, than the IdentityHashMap can be used.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hashCode of this object.
  - xxHash64
```
public final long xxHash64(long offsetBytes,
                           long lengthBytes,
                           long seed)
```
    Returns the 64-bit hash of the sequence of bytes in this object specified by offsetBytes, lengthBytes and a seed. Note that the sequence of bytes is always processed in the same order independent of endianness.
    
    Parameters:
    
    offsetBytes - the given offset in bytes to the first byte of the byte sequence.
    
    lengthBytes - the given length in bytes of the byte sequence.
    
    seed - the given long seed.
    
    Returns:
    
    the 64-bit hash of the sequence of bytes in this object specified by offsetBytes and lengthBytes.
  - hasByteBuffer
```
public final boolean hasByteBuffer()
```
    Returns true if this Memory is backed by a ByteBuffer.
    
    Returns:
    
    true if this Memory is backed by a ByteBuffer.
  - isDirect
```
public final boolean isDirect()
```
    Returns true if the backing resource is direct (off-heap) memory. This is the case for allocated direct memory, memory mapped files,
    
    Returns:
    
    true if the backing resource is direct (off-heap) memory.
  - isNativeOrder
```
public final boolean isNativeOrder()
```
    Returns true if the current byte order is native order.
    
    Returns:
    
    true if the current byte order is native order.
  - isReadOnly
```
public final boolean isReadOnly()
```
    Returns true if this object or the backing resource is read-only.
    
    Returns:
    
    true if this object or the backing resource is read-only.
  - isSameResource
```
public final boolean isSameResource(Object that)
```
    Returns true if the backing resource of this is identical with the backing resource of that. The capacities must be the same. If this is a region, the region offset must also be the same.
    
    Parameters:
    
    that - A different non-null object
    
    Returns:
    
    true if the backing resource of this is the same as the backing resource of that.
  - isValid
```
public boolean isValid()
```
    Returns true if this object is valid and has not been closed. This is relevant only for direct (off-heap) memory and Mapped Files.
    
    Returns:
    
    true if this object is valid and has not been closed.
  - checkValidAndBounds
```
public final void checkValidAndBounds(long offsetBytes,
                                      long lengthBytes)
```
    Checks that the specified range of bytes is within bounds of this object, throws IllegalArgumentException if it's not: i. e. if offsetBytes < 0, or length < 0, or offsetBytes + length > getCapacity().
    
    Parameters:
    
    offsetBytes - the given offset in bytes of this object
    
    lengthBytes - the given length in bytes of this object
  - getCurrentDirectMemoryAllocations
```
public static final long getCurrentDirectMemoryAllocations()
```
    Gets the current number of active direct memory allocations.
    
    Returns:
    
    the current number of active direct memory allocations.
  - getCurrentDirectMemoryAllocated
```
public static final long getCurrentDirectMemoryAllocated()
```
    Gets the current size of active direct memory allocated.
    
    Returns:
    
    the current size of active direct memory allocated.
  - getCurrentDirectMemoryMapAllocations
```
public static final long getCurrentDirectMemoryMapAllocations()
```
    Gets the current number of active direct memory map allocations.
    
    Returns:
    
    the current number of active direct memory map allocations.
  - getCurrentDirectMemoryMapAllocated
```
public static final long getCurrentDirectMemoryMapAllocated()
```
    Gets the current size of active direct memory map allocated.
    
    Returns:
    
    the current size of active direct memory map allocated.
  - toHexString
```
public final String toHexString(String header,
                                long offsetBytes,
                                int lengthBytes)
```
    Returns a formatted hex string of a range of this object. Used primarily for testing.
    
    Parameters:
    
    header - a descriptive header
    
    offsetBytes - offset bytes relative to this object start
    
    lengthBytes - number of bytes to convert to a hex string
    
    Returns:
    
    a formatted hex string in a human readable array

Class WritableMemory

Method Summary

Methods inherited from class com.yahoo.memory.Memory

Methods inherited from class java.lang.Object

Method Detail

wrap

wrap

map

map

allocateDirect

allocateDirect

writableRegion

writableRegion

asWritableBuffer

asWritableBuffer

allocate

allocate

wrap

wrap

wrap

wrap

wrap

wrap

wrap

wrap

wrap

wrap

putBoolean

putBooleanArray

putByte

putByteArray

putChar

putCharArray

putCharsToUtf8

putDouble

putDoubleArray

putFloat

putFloatArray

putInt

putIntArray

putLong

putLongArray

putShort

putShortArray

getAndAddLong

compareAndSwapLong

getAndSetLong

getArray

clear

clear

clearBits

fill

fill

setBits

getMemoryRequestServer

equals

equalTo

getByteBuffer

getByteOrder

getCapacity

getCumulativeOffset

getCumulativeOffset

getRegionOffset

getRegionOffset

hasArray

hashCode

xxHash64

hasByteBuffer

isDirect

isNativeOrder

isReadOnly

isSameResource

isValid

checkValidAndBounds

getCurrentDirectMemoryAllocations

getCurrentDirectMemoryAllocated

getCurrentDirectMemoryMapAllocations

getCurrentDirectMemoryMapAllocated

toHexString