GlueGen: com.jogamp.common.nio.MappedByteBufferInputStream Class Reference

GlueGen v2.6.0-rc-20250722 GlueGen, Native Binding Generator for Java™ (public API).

Classes | Public Member Functions | Static Public Attributes | List of all members
com.jogamp.common.nio.MappedByteBufferInputStream Class Reference

An `InputStream` implementation based on an underlying `FileChannel`'s memory mapped `ByteBuffer`, `supporting` `mark` and `reset()`. More...

Inheritance diagram for com.jogamp.common.nio.MappedByteBufferInputStream:
Collaboration diagram for com.jogamp.common.nio.MappedByteBufferInputStream:

## Classes

enum | CacheMode
interface | FileResizeOp
| File resize interface allowing a file to change its size, e.g. More...

## Public Member Functions

| MappedByteBufferInputStream (final FileChannel fileChannel, final FileChannel.MapMode mmode, final CacheMode cmode, final int sliceShift) throws IOException
| Creates a new instance using the given `FileChannel`. More...
| MappedByteBufferInputStream (final FileChannel fileChannel, final FileChannel.MapMode mmode, final CacheMode cmode) throws IOException
| Creates a new instance using the given `FileChannel`, given mapping-mode, given cache-mode and the `DEFAULT_SLICE_SHIFT`. More...
| MappedByteBufferInputStream (final FileChannel fileChannel) throws IOException
| Creates a new instance using the given `FileChannel`, `read-only` mapping mode, `CacheMode#FLUSH_PRE_HARD` and the `DEFAULT_SLICE_SHIFT`. More...
final synchronized void | setSynchronous (final boolean s)
| Enable or disable synchronous mode. More...
final synchronized boolean | getSynchronous ()
| Return `synchronous mode`. More...
final synchronized void | close () throws IOException
final synchronized void | setFileResizeOp (final FileResizeOp fileResizeOp) throws IllegalStateException
final synchronized void | setLength (final long newTotalSize) throws IOException
| Resize the underlying `FileChannel`'s size and adjusting this instance via `accordingly`. More...
final synchronized void | notifyLengthChange (final long newTotalSize) throws IOException
| Notify this instance that the underlying `FileChannel`'s size has been changed and adjusting this instances buffer slices and states accordingly. More...
final synchronized void | flush (final boolean metaData) throws IOException
| Similar to `OutputStream#flush()`, synchronizes all mapped buffers from local storage via `MappedByteBuffer#force()` as well as the `FileChannel#force(boolean)` w/o `metaData`. More...
final synchronized MappedByteBufferOutputStream | getOutputStream (final FileResizeOp fileResizeOp) throws IllegalStateException, IOException
| Returns a new MappedByteBufferOutputStream instance sharing all resources of this input stream, including all buffer slices. More...
final synchronized ByteBuffer | currentSlice () throws IOException
| Return the mapped `ByteBuffer` slice at the current `position()`. More...
final synchronized ByteBuffer | nextSlice () throws IOException
| Return the next mapped `ByteBuffer` slice from the current `position()`, implicitly setting `position(long)` to the start of the returned next slice, see `currentSlice()`. More...
final synchronized void | flushSlices () throws IOException
| Releases the mapped `ByteBuffer` slices. More...
final synchronized CacheMode | getCacheMode ()
| Return the used `CacheMode`. More...
final synchronized long | length ()
| Returns the total size in bytes of the `InputStream`. More...
final synchronized long | remaining () throws IOException
| Returns the number of remaining available bytes of the `InputStream`, i.e. More...
final synchronized int | available () throws IOException
| See `remaining()` for an accurate variant. More...
final synchronized long | position () throws IOException
| Returns the absolute position of the `InputStream`. More...
final synchronized MappedByteBufferInputStream | position (final long newPosition) throws IOException
| Sets the absolute position of the `InputStream` to `newPosition`. More...
final boolean | markSupported ()
final synchronized void | mark (final int readlimit)
final synchronized void | reset () throws IOException
final synchronized long | skip (final long n) throws IOException
final synchronized int | read () throws IOException
final synchronized int | read (final byte[] b, final int off, final int len) throws IOException
final synchronized int | read (final ByteBuffer b, final int len) throws IOException
| Perform similar to `read(byte[], int, int)` with `ByteBuffer` instead of byte array. More...

## Static Public Attributes

static final int | DEFAULT_SLICE_SHIFT
| Default slice shift, i.e. More...

## Detailed Description

An `InputStream` implementation based on an underlying `FileChannel`'s memory mapped `ByteBuffer`, `supporting` `mark` and `reset()`.

Implementation allows full memory mapped `ByteBuffer` coverage via `FileChannel` beyond its size limitation of `Integer#MAX_VALUE` utilizing an array of `ByteBuffer` slices.

Implementation further allows full random access via `position()` and `position(long)` and accessing the memory mapped `ByteBuffer` slices directly via `currentSlice()` and `nextSlice()`.

Since
  2.3.0

Definition at line 59 of file MappedByteBufferInputStream.java.

## Constructor & Destructor Documentation

## ◆ MappedByteBufferInputStream() [1/3]

com.jogamp.common.nio.MappedByteBufferInputStream.MappedByteBufferInputStream | ( | final FileChannel | fileChannel,
|  | final FileChannel.MapMode | mmode,
|  | final CacheMode | cmode,
|  | final int | sliceShift
| ) |  | throws IOException

Creates a new instance using the given `FileChannel`.

The `ByteBuffer` slices will be mapped lazily at first usage.

Parameters

  fileChannel | the file channel to be mapped lazily.
  mmode | the map mode, default is `FileChannel.MapMode#READ_ONLY`.
  cmode | the caching mode, default is `CacheMode#FLUSH_PRE_HARD`.
  sliceShift | the pow2 slice size, default is `DEFAULT_SLICE_SHIFT`.

Exceptions

  IOException |

Definition at line 250 of file MappedByteBufferInputStream.java.

## ◆ MappedByteBufferInputStream() [2/3]

com.jogamp.common.nio.MappedByteBufferInputStream.MappedByteBufferInputStream | ( | final FileChannel | fileChannel,
|  | final FileChannel.MapMode | mmode,
|  | final CacheMode | cmode
| ) |  | throws IOException

Creates a new instance using the given `FileChannel`, given mapping-mode, given cache-mode and the `DEFAULT_SLICE_SHIFT`.

The `ByteBuffer` slices will be mapped lazily at first usage.

Parameters

  fileChannel | the file channel to be used.
  mmode | the map mode, default is `FileChannel.MapMode#READ_ONLY`.
  cmode | the caching mode, default is `CacheMode#FLUSH_PRE_HARD`.

Exceptions

  IOException |

Definition at line 268 of file MappedByteBufferInputStream.java.

## ◆ MappedByteBufferInputStream() [3/3]

com.jogamp.common.nio.MappedByteBufferInputStream.MappedByteBufferInputStream | ( | final FileChannel | fileChannel | ) | throws IOException

Creates a new instance using the given `FileChannel`, `read-only` mapping mode, `CacheMode#FLUSH_PRE_HARD` and the `DEFAULT_SLICE_SHIFT`.

The `ByteBuffer` slices will be mapped `FileChannel.MapMode#READ_ONLY` lazily at first usage.

Parameters

  fileChannel | the file channel to be used.

Exceptions

  IOException |

Definition at line 282 of file MappedByteBufferInputStream.java.

## Member Function Documentation

## ◆ available()

final synchronized int com.jogamp.common.nio.MappedByteBufferInputStream.available | ( |  | ) | throws IOException

See `remaining()` for an accurate variant.

Exceptions

  IOException | if a buffer slice operation failed.

Definition at line 705 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ close()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.close | ( |  | ) | throws IOException

Definition at line 315 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ currentSlice()

final synchronized ByteBuffer com.jogamp.common.nio.MappedByteBufferInputStream.currentSlice | ( |  | ) | throws IOException

Return the mapped `ByteBuffer` slice at the current `position()`.

Due to the nature of using sliced buffers mapping the whole region, user has to determine whether the returned buffer covers the desired region and may fetch the `nextSlice()` until satisfied.
It is also possible to repeat this operation after reposition the stream via `position(long)` or `skip(long)` to a position within the next block, similar to `nextSlice()`.

Exceptions

  IOException | if a buffer slice operation failed.

Definition at line 506 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ flush()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.flush | ( | final boolean | metaData | ) | throws IOException

Similar to `OutputStream#flush()`, synchronizes all mapped buffers from local storage via `MappedByteBuffer#force()` as well as the `FileChannel#force(boolean)` w/o `metaData`.

Parameters

  metaData | TODO

Exceptions

  IOException | if this stream has been `closed`.

Definition at line 456 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ flushSlices()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.flushSlices | ( |  | ) | throws IOException

Releases the mapped `ByteBuffer` slices.

Exceptions

  IOException | if a buffer slice operation failed.

Definition at line 557 of file MappedByteBufferInputStream.java.

## ◆ getCacheMode()

final synchronized CacheMode com.jogamp.common.nio.MappedByteBufferInputStream.getCacheMode | ( |  | ) |

Return the used `CacheMode`.

If a desired `CacheMode` is not available, it may fall back to an available one at runtime, see `CacheMode#FLUSH_PRE_HARD`.
This evaluation only happens if the `CacheMode` != `CacheMode#FLUSH_NONE` and while attempting to flush an unused buffer slice.

Definition at line 668 of file MappedByteBufferInputStream.java.

## ◆ getOutputStream()

final synchronized MappedByteBufferOutputStream com.jogamp.common.nio.MappedByteBufferInputStream.getOutputStream | ( | final FileResizeOp | fileResizeOp | ) | throws IllegalStateException, IOException

Returns a new MappedByteBufferOutputStream instance sharing all resources of this input stream, including all buffer slices.

Exceptions

  IllegalStateException | if attempting to set the `FileResizeOp` to a different value than before
  IOException | if this instance was opened w/ `FileChannel.MapMode#READ_ONLY` or if this stream has been `closed`.

Definition at line 486 of file MappedByteBufferInputStream.java.

## ◆ getSynchronous()

final synchronized boolean com.jogamp.common.nio.MappedByteBufferInputStream.getSynchronous | ( |  | ) |

Return `synchronous mode`.

Definition at line 304 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ length()

final synchronized long com.jogamp.common.nio.MappedByteBufferInputStream.length | ( |  | ) |

Returns the total size in bytes of the `InputStream`.

      0 <= position() <= length()

Definition at line 677 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ mark()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.mark | ( | final int | readlimit | ) |

Parameter `readLimit` is not used in this implementation, since the whole file is memory mapped and no read limitation occurs.

Definition at line 785 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

## ◆ markSupported()

final boolean com.jogamp.common.nio.MappedByteBufferInputStream.markSupported | ( |  | ) |

Definition at line 773 of file MappedByteBufferInputStream.java.

## ◆ nextSlice()

final synchronized ByteBuffer com.jogamp.common.nio.MappedByteBufferInputStream.nextSlice | ( |  | ) | throws IOException

Return the next mapped `ByteBuffer` slice from the current `position()`, implicitly setting `position(long)` to the start of the returned next slice, see `currentSlice()`.

If no subsequent slice is available, `null` is being returned.

Exceptions

  IOException | if a buffer slice operation failed.

Definition at line 541 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ notifyLengthChange()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.notifyLengthChange | ( | final long | newTotalSize | ) | throws IOException

Notify this instance that the underlying `FileChannel`'s size has been changed and adjusting this instances buffer slices and states accordingly.

Should be called by user API when aware of such event.

Parameters

  newTotalSize | the new total size

Exceptions

  IOException | if a buffer slice operation failed

Definition at line 394 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ position() [1/2]

final synchronized long com.jogamp.common.nio.MappedByteBufferInputStream.position | ( |  | ) | throws IOException

Returns the absolute position of the `InputStream`.

      0 <= position() <= length()

Exceptions

  IOException | if a buffer slice operation failed.

Definition at line 718 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ position() [2/2]

final synchronized MappedByteBufferInputStream com.jogamp.common.nio.MappedByteBufferInputStream.position | ( | final long | newPosition | ) | throws IOException

Sets the absolute position of the `InputStream` to `newPosition`.

      0 <= position() <= length()

Parameters

  newPosition | The new position, which must be non-negative and ≤ `length()`.

Returns
  this instance

Exceptions

  IOException | if a buffer slice operation failed or stream is `closed`.

Definition at line 736 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

## ◆ read() [1/3]

final synchronized int com.jogamp.common.nio.MappedByteBufferInputStream.read | ( |  | ) | throws IOException

Definition at line 827 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ read() [2/3]

final synchronized int com.jogamp.common.nio.MappedByteBufferInputStream.read | ( | final byte[] | b,
|  | final int | off,
|  | final int | len
| ) |  | throws IOException

Definition at line 839 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

## ◆ read() [3/3]

final synchronized int com.jogamp.common.nio.MappedByteBufferInputStream.read | ( | final ByteBuffer | b,
|  | final int | len
| ) |  | throws IOException

Perform similar to `read(byte[], int, int)` with `ByteBuffer` instead of byte array.

Parameters

  b | the `ByteBuffer` sink, data is written at current `ByteBuffer#position()`
  len | the number of bytes to read

Returns
  the number of bytes read, -1 for EOS

Exceptions

  IOException | if a buffer slice operation failed or stream has been `closed`.

Definition at line 884 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

## ◆ remaining()

final synchronized long com.jogamp.common.nio.MappedByteBufferInputStream.remaining | ( |  | ) | throws IOException

Returns the number of remaining available bytes of the `InputStream`, i.e.

``length()` - `position()``.

      0 <= position() <= length()

<p<blockquote>‍

In contrast to `InputStream`'s `available()` method, this method returns the proper return type `long`.

Exceptions

  IOException | if a buffer slice operation failed.

Definition at line 693 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ reset()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.reset | ( |  | ) | throws IOException

Exceptions

  IOException | if this stream has not been marked, a buffer slice operation failed or stream has been `closed`.

Definition at line 801 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

## ◆ setFileResizeOp()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.setFileResizeOp | ( | final FileResizeOp | fileResizeOp | ) | throws IllegalStateException

Parameters

  fileResizeOp | the new `FileResizeOp`.

Exceptions

  IllegalStateException | if attempting to set the `FileResizeOp` to a different value than before

Definition at line 341 of file MappedByteBufferInputStream.java.

## ◆ setLength()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.setLength | ( | final long | newTotalSize | ) | throws IOException

Resize the underlying `FileChannel`'s size and adjusting this instance via `accordingly`.

User must have a `FileResizeOp` `registered` before.

Implementation calls `notifyLengthChange(long)` after `FileResizeOp#setLength(long)`.

Parameters

  newTotalSize | the new total size

Exceptions

  IOException | if no `FileResizeOp` has been `registered` or if a buffer slice operation failed

Definition at line 361 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ setSynchronous()

final synchronized void com.jogamp.common.nio.MappedByteBufferInputStream.setSynchronous | ( | final boolean | s | ) |

Enable or disable synchronous mode.

If synchronous mode is enabled, mapped buffers will be `flushed` if `resized`, written to or `closing` in `read-write` mapping mode.

If synchronous mode is enabled, `FileChannel#force(boolean)` is issued if `resizing` or `closing` and not in `read-only` mapping mode.

Parameters

  s | `true` to enable synchronous mode

Definition at line 298 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

## ◆ skip()

final synchronized long com.jogamp.common.nio.MappedByteBufferInputStream.skip | ( | final long | n | ) | throws IOException

Exceptions

  IOException | if a buffer slice operation failed or stream is `closed`.

Definition at line 814 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## Member Data Documentation

## ◆ DEFAULT_SLICE_SHIFT

final int com.jogamp.common.nio.MappedByteBufferInputStream.DEFAULT_SLICE_SHIFT

static

Default slice shift, i.e.

1L << shift, denoting slice size in MiB:

- `64bit machines` -> 30 = 1024 MiB
- `32bit machines` -> 29 = 512 MiB

In case the default is too much of-used up address-space, one may choose other values:

- 29 -> 512 MiB
- 28 -> 256 MiB
- 27 -> 128 MiB
- 26 -> 64 MiB

Definition at line 135 of file MappedByteBufferInputStream.java.

The documentation for this class was generated from the following file:

- src/java/com/jogamp/common/nio/MappedByteBufferInputStream.java