Skip to content

Commit 6fd87c3

Browse files
authored
[jni] Clarify JBuffer.asUint8List behavior (#3704)
1 parent 6d5bbcf commit 6fd87c3

2 files changed

Lines changed: 13 additions & 1 deletion

File tree

‎pkgs/jni/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
## 1.1.0-wip
22

33
- Add deep conversion utilities for converting between Dart values and Java.
4+
- Clarify the memory behavior of `JByteBuffer.asUint8List`.
45

56
## 1.0.3
67

‎pkgs/jni/lib/src/nio/jbyte_buffer.dart‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,18 @@ extension type JByteBuffer._(JObject _$this) implements JBuffer {
255255

256256
/// Returns this byte buffer as a [Uint8List].
257257
///
258-
/// If [releaseOriginal] is `true`, this byte buffer will be released.
258+
/// The returned [Uint8List] holds a JNI global reference to this buffer.
259+
/// Unlike a [JObject], the [Uint8List] cannot be explicitly released; the
260+
/// reference is only deleted when the list is garbage collected. If
261+
/// [releaseOriginal] is `false` (the default), a new global reference is
262+
/// created for the [Uint8List] and this buffer remains usable. If
263+
/// [releaseOriginal] is `true`, this buffer's reference is transferred to the
264+
/// list and this buffer is released.
265+
///
266+
/// Because the Dart garbage collector is not aware of the limit on JNI global
267+
/// references, avoid keeping many of these lists alive at once. See JNIgen's
268+
/// [lifecycle](https://pub.dev/documentation/jnigen/latest/topics/Lifecycle-topic.html)
269+
/// documentation for more information.
259270
///
260271
/// Throws [StateError] if the buffer is not direct
261272
/// (see [JByteBuffer.allocateDirect]) or the JVM does not support the direct

0 commit comments

Comments
 (0)