Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.squawk.realtime
Class RawMemoryAccess

    java.lang.Object
      com.sun.squawk.realtime.RawMemoryAccess

Direct Known Subclasses:
  RawMemoryFloatAccess

    public class RawMemoryAccess

extends Object

An instance of `RawMemoryAccess` models a range of physical memory as a fixed sequence of bytes. A full complement of accessor methods allow the contents of the physical area to be accessed through offsets from the base, interpreted as byte, short, int, or long data values or as arrays of these types.

The `RawMemoryAccess` class allows a real-time program to implement device drivers, memory-mapped I/O, flash memory, battery-backed RAM, and similar low-level software.

A raw memory area cannot contain references to Java objects. Such a capability would be unsafe (since it could be used to defeat Java's type checking) and error-prone (since it is sensitive to the specific representational choices made by the Java compiler).

Many of the constructors and methods in this class throw `OffsetOutOfBoundsException`. This exception means that the value given in the offset parameter is either negative or outside the memory area.

Many of the constructors and methods in this class throw `SizeOutOfBoundsException`. This exception means that the value given in the size parameter is either negative, larger than an allowable range, or would cause an accessor method to access an address outside of the memory area.

Unlike other integral parameters in this chapter, negative values are valid for `byte, short, int,` and `long` values that are copied in and out of memory by the `set` and `get` methods of this class.

All offset values used in this class are measured in bytes.

Atomic loads and stores on raw memory are defined in terms of physical memory. This memory may be accessible to threads outside the JVM and to non-programmed access (e.g., DMA), consequently atomic access must be supported by hardware. This specification is written with the assumption that all suitable hardware platforms support atomic loads for aligned bytes, shorts, and ints. Atomic access beyond the specified minimum may be supported by the implementation.

Storing values into raw memory is more hardware-dependent than loading values. Many processor architectures do not support atomic stores of variables except for aligned stores of the processor's word size. For instance, storing a byte into memory might require reading a 32-bit quantity into a processor register, updating the register to reflect the new byte value, then re-storing the whole 32-bit quantity. Changes to other bytes in the 32-bit quantity that take place between the load and the store will be lost.

Some processors have mechanisms that can be used to implement an atomic store of a byte, but those mechanisms are often slow and not universally supported.

This class supports unaligned access to data, but it does not require the implementation to make such access atomic. Accesses to data aligned on its natural boundary will be atomic if the processor implements atomic loads and stores of that data size.

Except where noted, accesses to raw memory are not atomic with respect to the memory or with respect to schedulable objects. A raw memory area could be updated by another schedulable object, or even unmapped in the middle of a method.

The characteristics of raw-memory access are necessarily platform dependent. This specification provides a minimum requirement for the RTSJ platform, but it also supports optional system properties that identify a platform's level of support for atomic raw put and get. The properties represent a four-dimensional sparse array with boolean values indicating whether that combination of access attributes is atomic. The default value for array entries is false. The dimension are

Attribute | Values | Comment
Access type | read, write |
Data type | byte, short, int, long, float, double |
Alignment | 0 to 7 | For each data type, the possible alignments range from 0 == aligned to data size - 1 == only the first byte of the data is alignment bytes away from natural alignment.
Atomicity | processor, smp, memory | processor means access is atomic with respect to other schedulable objects on that processor. smp means that access is processor atomic, and atomic with respect across the processors in an SMP. memory means that access is smp atomic, and atomic with respect to all access to the memory including DMA.

The true values in the table are represented by properties of the following form. javax.realtime.atomicaccess_<access>_<type>_<alignment>_atomicity=true for example:

      javax.realtime.atomicaccess_read_byte_0_memory=true

Table entries with a value of false may be explicitly represented, but since false is the default value, such properties are redundant.

All raw memory access is treated as volatile, and serialized. The run-time must be forced to re-read memory or write to memory on each call to a raw memory getxxx or putxxx method, and to complete the reads and writes in the order they appear in the program order.

Field Summary
`protected Address` | `vbase` Virtual base address.

Constructor Summary
`RawMemoryAccess(Object type, long size)` Construct an instance of `RawMemoryAccess` with the given parameters, and set the object to the mapped state.
`RawMemoryAccess(Object type, long base, long size)` Construct an instance of `RawMemoryAccess` with the given parameters, and set the object to the mapped state.

Method Summary
`protected static void` | `checkBounds(int length, int offset, int size)` Do a bounds check on a write.
`protected static void` | `checkMultiBounds(int length, int offset, int number, int elemsize)` Do a bounds check on accessing a range.
`protected void` | `checkMultiRead(int offset, int number, int elemsize)` Do a bounds check on reading a range.
`protected void` | `checkMultiWrite(int offset, int number, int elemsize)` Do a bounds check on writing a range.
`protected Address` | `getAddress()` Gets the virtual memory location at which the memory region is mapped.
`byte` | `getByte(long offset)` Gets the `byte` at the given offset in the memory area associated with this object.
`void` | `getBytes(long offset, byte[] bytes, int low, int number)` Gets `number` bytes starting at the given offset in the memory area associated with this object and assigns them to the byte array passed starting at position `low`.
`int` | `getInt(long offset)` Gets the `int` at the given offset in the memory area associated with this object.
`void` | `getInts(long offset, int[] ints, int low, int number)` Gets `number` integers starting at the given offset in the memory area associated with this object and assign them to the int array passed starting at position `low`.
`long` | `getLong(long offset)` Gets the `long` at the given offset in the memory area associated with this object.
`void` | `getLongs(long offset, long[] longs, int low, int number)` Gets `number` longs starting at the given offset in the memory area associated with this object and assign them to the long array passed starting at position `low`.
`long` | `getMappedAddress()` Gets the virtual memory location at which the memory region is mapped.
`short` | `getShort(long offset)` Gets the `short` at the given offset in the memory area associated with this object.
`void` | `getShorts(long offset, short[] shorts, int low, int number)` Gets `number` shorts starting at the given offset in the memory area associated with this object and assign them to the short array passed starting at position `low`.
`protected void` | `invalidate()` Set the pointer value to NULL
`long` | `map()` Maps the physical memory range into virtual memory.
`long` | `map(long base)` Maps the physical memory range into virtual memory at the specified location.
`long` | `map(long base, long size)` Maps the physical memory range into virtual memory.
`void` | `setByte(long offset, byte value)` Sets the `byte` at the given offset in the memory area associated with this object.
`void` | `setBytes(long offset, byte[] bytes, int low, int number)` Sets `number` bytes starting at the given offset in the memory area associated with this object from the byte array passed starting at position `low`.
`void` | `setInt(long offset, int value)` Sets the `int` at the given offset in the memory area associated with this object.
`void` | `setInts(long offset, int[] ints, int low, int number)` Sets `number` ints starting at the given offset in the memory area associated with this object from the int array passed starting at position `low`.
`void` | `setLong(long offset, long value)` Sets the `long` at the given offset in the memory area associated with this object.
`void` | `setLongs(long offset, long[] longs, int low, int number)` Sets `number` longs starting at the given offset in the memory area associated with this object from the long array passed starting at position `low`.
`void` | `setShort(long offset, short value)` Sets the `short` at the given offset in the memory area associated with this object.
`void` | `setShorts(long offset, short[] shorts, int low, int number)` Sets `number` shorts starting at the given offset in the memory area associated with this object from the short array passed starting at position `low`.
`protected UWord` | `size()` Gets the virtual memory location at which the memory region is mapped.
`protected boolean` | `wasMalloced()` Return true if this specific RawMemoryAccess allocated native memory.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### vbase

    protected Address vbase

  Virtual base address.

  It is null if the RawMemoryAccess object is not mapped.

Constructor Detail

### RawMemoryAccess

    public RawMemoryAccess(Object type,
                           long size)
                    throws SizeOutOfBoundsException,
                           OutOfMemoryError

  Construct an instance of `RawMemoryAccess` with the given parameters, and set the object to the mapped state. If the platform supports virtual memory, map the raw memory into virtual memory.

  The run time environment is allowed to choose the virtual address where the raw memory area corresponding to this object will be mapped.

  Parameters:
    `type` - An instance of `Object` representing the type of memory required (e.g., dma, shared) - used to define the base address and control the mapping. If the required memory has more than one attribute, `type` may be an array of objects. If `type` is null or a reference to an array with no entries, any type of memory is acceptable.
    `size` - The size of the area in bytes.
  Throws:
    `SecurityException` - Thrown if the application doesn't have permissions to access physical memory, the specified range of addresses, or the given type of memory.
    `SizeOutOfBoundsException` - Thrown if the size is negative or extends into an invalid range of memory.
    `UnsupportedPhysicalMemoryException` - Thrown if the underlying hardware does not support the given type.
    `MemoryTypeConflictException` - Thrown if the specified base does not point to memory that matches the request type, or if `type` specifies incompatible memory attributes.
    `OutOfMemoryError` - Thrown if the requested type of memory exists, but there is not enough of it free to satisfy the request.

### RawMemoryAccess

    public RawMemoryAccess(Object type,
                           long base,
                           long size)
                    throws SizeOutOfBoundsException,
                           OffsetOutOfBoundsException

  Construct an instance of `RawMemoryAccess` with the given parameters, and set the object to the mapped state. If the platform supports virtual memory, map the raw memory into virtual memory.

  The run time environment is allowed to choose the virtual address where the raw memory area corresponding to this object will be mapped.

  Parameters:
    `type` - An instance of `Object` representing the type of memory required (e.g., dma, shared) - used to define the base address and control the mapping. If the required memory has more than one attribute, `type` may be an array of objects. If `type` is null or a reference to an array with no entries, any type of memory is acceptable.
    `base` - The physical memory address of the region.
    `size` - The size of the area in bytes.
  Throws:
    `SecurityException` - Thrown if application doesn't have permissions to access physical memory, the specified range of addresses, or the given type of memory.
    `OffsetOutOfBoundsException` - Thrown if the address is invalid.
    `SizeOutOfBoundsException` - Thrown if the size is negative or extends into an invalid range of memory.
    `UnsupportedPhysicalMemoryException` - Thrown if the underlying hardware does not support the given type.
    `MemoryTypeConflictException` - Thrown if the specified base does not point to memory that matches the request type, or if `type` specifies incompatible memory attributes.
    `OutOfMemoryError` - Thrown if the requested type of memory exists, but there is not enough of it free to satisfy the request.

Method Detail

### checkMultiRead

    protected final void checkMultiRead(int offset,
                                        int number,
                                        int elemsize)
                                 throws OffsetOutOfBoundsException,
                                        SizeOutOfBoundsException

  Do a bounds check on reading a range.

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to read.
    `number` - The number of items to load.
    `elemsize` - The size of the read in bytes
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the short falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### checkMultiBounds

    protected static void checkMultiBounds(int length,
                                           int offset,
                                           int number,
                                           int elemsize)
                                    throws OffsetOutOfBoundsException,
                                           SizeOutOfBoundsException

  Do a bounds check on accessing a range.

  Parameters:
    `length` - the length pof the memory area being accessed, in bytes
    `offset` - The offset in bytes from the beginning of the raw memory area from which to read.
    `number` - The number of items to load.
    `elemsize` - The size of the each item in bytes
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the short falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getByte

    public byte getByte(long offset)

  Gets the `byte` at the given offset in the memory area associated with this object. The byte is always loaded from memory in a single atomic operation.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory from which to load the byte.
  Returns:
    The byte from raw memory.
  Throws:
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the byte falls in an invalid address range.
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getBytes

    public void getBytes(long offset,
                         byte[] bytes,
                         int low,
                         int number)

  Gets `number` bytes starting at the given offset in the memory area associated with this object and assigns them to the byte array passed starting at position `low`. Each byte is loaded from memory in a single atomic operation. Groups of bytes may be loaded together, but this is unspecified.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory from which to start loading.
    `bytes` - The array into which the loaded items are placed.
    `low` - The offset which is the starting point in the given array for the loaded items to be placed.
    `number` - The number of items to load.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the byte falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The `bytes` array could, therefore, be partially updated if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getInt

    public int getInt(long offset)

  Gets the `int` at the given offset in the memory area associated with this object. If the integer is aligned on a "natural" boundary it is always loaded from memory in a single atomic operation. If it is not on a natural boundary it may not be loaded atomically, and the number and order of the load operations is unspecified.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to load the integer.
  Returns:
    The integer from raw memory.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the integer falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getInts

    public void getInts(long offset,
                        int[] ints,
                        int low,
                        int number)

  Gets `number` integers starting at the given offset in the memory area associated with this object and assign them to the int array passed starting at position `low`.

  If the integers are aligned on natural boundaries each integer is loaded from memory in a single atomic operation. Groups of integers may be loaded together, but this is unspecified.

  If the integers are not aligned on natural boundaries they may not be loaded atomically and the number and order of load operations is unspecified.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to start loading.
    `ints` - The array into which the integers read from the raw memory are placed.
    `low` - The offset which is the starting point in the given array for the loaded items to be placed.
    `number` - The number of integers to loaded.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the integers fall in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The `ints` array could, therefore, be partially updated if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getLong

    public long getLong(long offset)

  Gets the `long` at the given offset in the memory area associated with this object.

  The load is not required to be atomic even it is located on a natural boundary.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to load the long.
  Returns:
    The long from raw memory.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is invalid.
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the double falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getLongs

    public void getLongs(long offset,
                         long[] longs,
                         int low,
                         int number)

  Gets `number` longs starting at the given offset in the memory area associated with this object and assign them to the long array passed starting at position `low`.

  The loads are not required to be atomic even if they are located on natural boundaries.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to start loading.
    `longs` - The array into which the loaded items are placed.
    `low` - The offset which is the starting point in the given array for the loaded items to be placed.
    `number` - The number of longs to load.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if a long falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The `longs` array could, therefore, be partially updated if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getMappedAddress

    public long getMappedAddress()

  Gets the virtual memory location at which the memory region is mapped.

  Returns:
    The virtual address to which this is mapped (for reference purposes). Same as the base address if virtual memory is not supported.
  Throws:
    `IllegalStateException` - Thrown if the raw memory object is not in the mapped state.

### getAddress

    protected final Address getAddress()

  Gets the virtual memory location at which the memory region is mapped.

  Returns:
    The virtual address to which this is mapped (for reference purposes). Same as the base address if virtual memory is not supported.
  Throws:
    `IllegalStateException` - Thrown if the raw memory object is not in the mapped state.

### size

    protected final UWord size()

  Gets the virtual memory location at which the memory region is mapped.

  Returns:
    The virtual address to which this is mapped (for reference purposes). Same as the base address if virtual memory is not supported.
  Throws:
    `IllegalStateException` - Thrown if the raw memory object is not in the mapped state.

### getShort

    public short getShort(long offset)

  Gets the `short` at the given offset in the memory area associated with this object. If the short is aligned on a natural boundary it is always loaded from memory in a single atomic operation. If it is not on a natural boundary it may not be loaded atomically, and the number and order of the load operations is unspecified.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to load the short.
  Returns:
    The short loaded from raw memory.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the short falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### getShorts

    public void getShorts(long offset,
                          short[] shorts,
                          int low,
                          int number)

  Gets `number` shorts starting at the given offset in the memory area associated with this object and assign them to the short array passed starting at position `low`.

  If the shorts are located on natural boundaries each short is loaded from memory in a single atomic operation. Groups of shorts may be loaded together, but this is unspecified.

  If the shorts are not located on natural boundaries the load may not be atomic, and the number and order of load operations is unspecified.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to start loading.
    `shorts` - The array into which the loaded items are placed.
    `low` - The offset which is the starting point in the given array for the loaded shorts to be placed.
    `number` - The number of shorts to load.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if a short falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The `shorts` array could, therefore, be partially updated if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### map

    public long map()
             throws OutOfMemoryError

  Maps the physical memory range into virtual memory. No-op if the system doesn't support virtual memory.

  The run time environment is allowed to choose the virtual address where the raw memory area corresponding to this object will be mapped.

  If the object is already mapped into virtual memory, this method does not change anything.

  Returns:
    The starting point of the virtual memory range.
  Throws:
    `OutOfMemoryError` - Thrown if there is insufficient free virtual address space to map the object.

### map

    public long map(long base)

  Maps the physical memory range into virtual memory at the specified location. No-op if the system doesn't support virtual memory.

  If the object is already mapped into virtual memory at a different address, this method remaps it to `base`.

  If a remap is requested while another schedulable object is accessing the raw memory, the map will block until one load or store completes. It can interrupt an array operation between entries.

  Parameters:
    `base` - The location to map at the virtual memory space.
  Returns:
    The starting point of the virtual memory.
  Throws:
    `OutOfMemoryError` - Thrown if there is insufficient free virtual memory at the specified address.
    `IllegalArgumentException` - Thrown if `base` is not a legal value for a virtual address.

### map

    public long map(long base,
                    long size)

  Maps the physical memory range into virtual memory. No-op if the system doesn't support virtual memory.

  If the object is already mapped into virtual memory at a different address, this method remaps it to `base`.

  If a remap is requested while another schedulable object is accessing the raw memory, the map will block until one load or store completes. It can interrupt an array operation between entries.

  Parameters:
    `base` - The location to map at the virtual memory space.
    `size` - The size of the block to map in. If the size of the raw memory area is greater than `size`, the object is unchanged but accesses beyond the mapped region will throw `SizeOutOfBoundsException`. If the size of the raw memory area is smaller than the mapped region access to the raw memory will behave as if the mapped region matched the raw memory area, but additional virtual address space will be consumed after the end of the raw memory area.
  Returns:
    The starting point of the virtual memory.
  Throws:
    `IllegalArgumentException` - Thrown if size is not greater than zero, or `base` is not a legal value for a virtual address.

### checkBounds

    protected static void checkBounds(int length,
                                      int offset,
                                      int size)
                               throws OffsetOutOfBoundsException,
                                      SizeOutOfBoundsException

  Do a bounds check on a write.

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to write.
    `size` - The size of the write in bytes
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the short falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### checkMultiWrite

    protected final void checkMultiWrite(int offset,
                                         int number,
                                         int elemsize)
                                  throws OffsetOutOfBoundsException,
                                         SizeOutOfBoundsException

  Do a bounds check on writing a range.

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area from which to read
    `number` - The number of items to store.
    `elemsize` - The size of each element in bytes
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the short falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setByte

    public void setByte(long offset,
                        byte value)

  Sets the `byte` at the given offset in the memory area associated with this object.

  This memory access may involve a load and a store, and it may have unspecified effects on surrounding bytes in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area to which to write the byte.
    `value` - The byte to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the byte falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setBytes

    public void setBytes(long offset,
                         byte[] bytes,
                         int low,
                         int number)

  Sets `number` bytes starting at the given offset in the memory area associated with this object from the byte array passed starting at position `low`.

  This memory access may involve multiple load and a store operations, and it may have unspecified effects on surrounding bytes (even bytes in the range being stored) in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area to which to start writing.
    `bytes` - The array from which the items are obtained.
    `low` - The offset which is the starting point in the given array for the items to be obtained.
    `number` - The number of items to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the a short falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The store of the array into memory could, therefore, be only partially complete if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setInt

    public void setInt(long offset,
                       int value)

  Sets the `int` at the given offset in the memory area associated with this object. On most processor architectures an aligned integer can be stored in an atomic operation, but this is not required.

  This memory access may involve multiple load and a store operations, and it may have unspecified effects on surrounding bytes (even bytes in the range being stored) in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to write the integer.
    `value` - The integer to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the integer falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setInts

    public void setInts(long offset,
                        int[] ints,
                        int low,
                        int number)

  Sets `number` ints starting at the given offset in the memory area associated with this object from the int array passed starting at position `low`. On most processor architectures each aligned integer can be stored in an atomic operation, but this is not required.

  This memory access may involve multiple load and a store operations, and it may have unspecified effects on surrounding bytes (even bytes in the range being stored) in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to start writing.
    `ints` - The array from which the items are obtained.
    `low` - The offset which is the starting point in the given array for the items to be obtained.
    `number` - The number of items to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if an int falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The store of the array into memory could, therefore, be only partially complete if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setLong

    public void setLong(long offset,
                        long value)

  Sets the `long` at the given offset in the memory area associated with this object. Even if it is aligned, the long value may not be updated atomically. It is unspecified how many load and store operations will be used or in what order.

  This memory access may involve multiple load and a store operations, and it may have unspecified effects on surrounding bytes (even bytes in the range being stored) in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to write the long.
    `value` - The long to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the long falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setLongs

    public void setLongs(long offset,
                         long[] longs,
                         int low,
                         int number)

  Sets `number` longs starting at the given offset in the memory area associated with this object from the long array passed starting at position `low`. Even if they are aligned, the long values may not be updated atomically. It is unspecified how many load and store operations will be used or in what order.

  This memory access may involve multiple load and a store operations, and it may have unspecified effects on surrounding bytes (even bytes in the range being stored) in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to start writing.
    `longs` - The array from which the items are obtained.
    `low` - The offset which is the starting point in the given array for the items to be obtained.
    `number` - The number of items to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the a short falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The store of the array into memory could, therefore, be only partially complete if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setShort

    public void setShort(long offset,
                         short value)

  Sets the `short` at the given offset in the memory area associated with this object.

  This memory access may involve a load and a store, and it may have unspecified effects on surrounding shorts in the presence of concurrent access.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to write the short.
    `value` - The short to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the short falls in an invalid address range.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### setShorts

    public void setShorts(long offset,
                          short[] shorts,
                          int low,
                          int number)

  Sets `number` shorts starting at the given offset in the memory area associated with this object from the short array passed starting at position `low`.

  Each write of a short value may involve a load and a store, and it may have unspecified effects on surrounding shorts in the presence of concurrent access - even on other shorts in the array.

  Caching of the memory access is controlled by the memory `type` requested when the `RawMemoryAccess` instance was created. If the memory is not cached, this method guarantees serialized access (that is, the memory access at the memory occurs in the same order as in the program. Multiple writes to the same location may not be coalesced.)

  Parameters:
    `offset` - The offset in bytes from the beginning of the raw memory area at which to start writing.
    `shorts` - The array from which the items are obtained.
    `low` - The offset which is the starting point in the given array for the items to be obtained.
    `number` - The number of items to write.
  Throws:
    `OffsetOutOfBoundsException` - Thrown if the offset is negative or greater than the size of the raw memory area. The role of the `SizeOutOfBoundsException` somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area. (See `map(long base, long size)`).
    `SizeOutOfBoundsException` - Thrown if the object is not mapped, or if the a short falls in an invalid address range. This is checked at every entry in the array to allow for the possibility that the memory area could be unmapped or remapped. The store of the array into memory could, therefore, be only partially complete if the raw memory is unmapped or remapped mid-method.
    `ArrayIndexOutOfBoundsException` - Thrown if `low` is less than 0 or greater than `bytes.length - 1`, or if `low + number` is greater than or equal to `bytes.length`.
    `SecurityException` - Thrown if this access is not permitted by the security manager.

### wasMalloced

    protected boolean wasMalloced()

  Return true if this specific RawMemoryAccess allocated native memory.

  Returns:
    true if the memory referred to by this RawMemoryAccess was allocated by this RawMemoryAccess

### invalidate

    protected final void invalidate()

  Set the pointer value to NULL

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

"
For updated information see the Java FRC site
"