bytedeco 进阶：PointerScope 作用域释放，别再漏 close

BYTEDECO 进阶

bytedeco 进阶 · 第 01 篇 JavaCPP / 内存

PointerScope 作用域释放，别再漏 close

栈 javacpp 1.5.13 · OpenCV 4.13 阅读 ~22 min

系列导读 · 建议先看主线小册

主线之外的硬能力，关键时刻能救命

面向已经会 Session / Mat / classifier 的读者。本系列挖 JavaCPP 绑定层、作用域内存、回调、滤镜图、自建 binding、CUDA 现实、加速库、打包与 EP 冷启动——都是主线跑通之后，排障和加深才会碰到的硬能力。

还没跑通主线？请先看公众号里那篇总览： 《在 Java 里把 ONNX / OpenCV / FFmpeg 跑稳　我写了 28 篇 bytedeco 实战小册》。 完整 28 篇 PDF：关注公众号 Coder建设，回复关键词 bytedeco 或 小册 领取。 主线小册走完（依赖瘦身 → Session → 预处理 → 打包），再回来读本进阶系列，学习曲线会顺很多。

主线小册合集（可点）： 打开 bytedeco 实战小册合集 （微信内一键进入专辑）

学完你应能独立做到

• 用 try (PointerScope s = new PointerScope()) 托管一批临时 Mat / Pointer
• 用 Pointer.totalBytes() 自证 scope 是否真正释放
• 正确使用 scope.attach(ptr)，并避开「返回值被 scope 杀掉」的坑
• 在拉流/批处理热路径设计「每帧一个 scope + 跨请求引擎字段」的分工

本篇目录

1. 为什么 finally 不够用
2. PointerScope 是什么（心智模型）
3. 本机验证结果（原文粘贴）
4. 完整可运行代码
5. attach / deallocate 语义
6. 嵌套 scope：外层必须活着
7. 错误示范 vs 正确示范
8. 热路径架构：帧 scope × 引擎字段
9. 和「手写 close」怎么选
10. 排障清单与自测题

1. 为什么 finally 不够用

主手册已经讲过：native 对象要 close，GC 收不回 native 堆。真正落地时，问题常不是「知不知道要 close」，而是：

• 一条处理链里临时 Mat 有 8～20 个
• 中间有 if / return / throw，finally 里漏一个就泄漏
• 重构时改调用图，close 顺序和对象图不同步

CODE

Mat gray = new Mat();

Mat edges = new Mat();

Mat kernel = getStructuringElement(...);

if (skip) {

return; // gray / edges / kernel 全漏

}

// ... 更多分支

gray.close();

edges.close();

kernel.close();

手写 close 在「对象少、路径直」时完全够用；对象多、分支多时，你需要作用域级释放——这就是 PointerScope。

2. PointerScope 是什么（心智模型）

org.bytedeco.javacpp.PointerScope 实现 AutoCloseable。在 scope 存活期间登记的 Pointer，在 close()（try-with-resources 结束）时统一 deallocate。

• 接近 C++ 局部对象析构 / RAII
• 接近 Arena / Region 分配器：一批一起死
• 接近「多个资源的 try-with-resources」

关键：Scope 管的是登记过的 Pointer，不是「任意 new 出来的 Java 对象」。 不同 JavaCPP 版本对「new Mat 是否自动挂进当前 scope」行为可能不同——所以本系列用 Pointer.totalBytes() 实测，而不是只信文档。

可观察指标：

• Pointer.totalBytes()：当前仍由 JavaCPP 跟踪的 native 字节数（近似）
• 进程 RSS：最终真相，但噪声大，适合对比实验

3. 本机验证结果（原文粘贴）

命令：

CODE

cd examples/jc-verify

# 改 pom 里 platform.classifier 为你的平台

mvn -q compile exec:java

# 期望末尾：=== ALL PASSED ===

本机真实输出（PointerScope 段）：

CODE

=== 1 PointerScope ===

in-scope mats ok, totalBytes=216

attached FloatPointer, get(0)=3.14

PointerScope.attach(Pointer)

PointerScope.deallocate()

[OK] PointerScope.attach(Pointer) exists

[OK] PointerScope.deallocate() exists

[OK] in-scope totalBytes increased (mid=216 before=0)

after scope totalBytes=0 (before=0)

[OK] after scope totalBytes back to baseline (after=0)

[OK] nested inner Mat allocated

[OK] outer Mat still valid after inner close (8x8)

[OK] outer Mat copyTo works after nested scope

[OK] nested PointerScope: outer survives inner close

解读：

• scope 内创建 Mat 后 totalBytes 从 0 升到 216 → 分配被跟踪
• 离开 try 后回到 0 → 释放生效（不是「写了 close 字样」）
• 公开 API 含 attach(Pointer) 与 deallocate()
• 嵌套：内层关后，外层 8×8 Mat 仍可 copyTo

4. 完整可运行代码

教学版（与验证逻辑同源，可单独 main）：

CODE

package com.example;

import org.bytedeco.javacpp.Pointer;

import org.bytedeco.javacpp.PointerScope;

import org.bytedeco.opencv.opencv_core.Mat;

import org.bytedeco.opencv.opencv_core.Size;

import static org.bytedeco.opencv.global.opencv_core.*;

import static org.bytedeco.opencv.global.opencv_imgproc.*;

public class ScopeDemo {

public static void main(String[] args) {

long before = Pointer.totalBytes();

try (PointerScope scope = new PointerScope()) {

Mat bgr = new Mat(64, 64, CV_8UC3);

Mat gray = new Mat();

cvtColor(bgr, gray, COLOR_BGR2GRAY);

GaussianBlur(gray, gray, new Size(3, 3), 0);

System.out.println("in-scope bytes=" + Pointer.totalBytes());

// 已有 Pointer 可显式挂上：

// scope.attach(somePointer);

}

System.out.println("after=" + Pointer.totalBytes() + " before=" + before);

// 期望：after ≈ before（通常为 0）

}

}

生产味一点的工具方法模板——结果缓冲在 scope 外：

CODE

public static void preprocess(Mat bgr, Mat outGray) {

try (PointerScope scope = new PointerScope()) {

Mat tmp = new Mat();

cvtColor(bgr, tmp, COLOR_BGR2GRAY);

GaussianBlur(tmp, tmp, new Size(3, 3), 0);

tmp.copyTo(outGray); // outGray 由调用方持有，不随 scope 死

}

}

5. attach / deallocate 语义

本机反射确认（1.5.13）：

CODE

PointerScope.attach(Pointer)

PointerScope.deallocate()

• attach(p)：把已有 Pointer 登记进当前 scope；scope 关闭时会释放它
• deallocate()：scope 的释放入口（try-with-resources 的 close 会走到释放路径）

所有权铁律：

• 调用方传入、调用方仍拥有的 Pointer → 不要 attach 进你的短 scope
• 你在方法内 new 的临时量 → 可以交给 scope
• 要返回给调用方的结果 → scope 外分配，或 clone/copyTo 到外部缓冲

6. 嵌套 scope：外层必须活着

验证工程里测过：

CODE

try (PointerScope outer = new PointerScope()) {

Mat keep = new Mat(8, 8, CV_8UC1);

try (PointerScope inner = new PointerScope()) {

Mat temp = new Mat(32, 32, CV_8UC3);

// temp 随 inner 释放

}

// keep 仍有效

Mat dst = new Mat();

keep.copyTo(dst);

dst.close();

}

断言结果：outer Mat still valid after inner close、copyTo works 均 OK。

用途：外层管「请求级」临时图，内层管「某一步算法」的中间量，避免一步算法爆炸污染整个请求的记账。

7. 错误示范 vs 正确示范

错 1：返回值绑进 scope

CODE

Mat leakDemo(String path) {

try (PointerScope s = new PointerScope()) {

Mat m = imread(path);

return m; // s 结束 m 被释放 → 调用方野指针

}

}

对 1：结果在 scope 外，或 copyTo

CODE

void okDemo(String path, Mat out) {

try (PointerScope s = new PointerScope()) {

Mat m = imread(path);

Mat small = new Mat();

resize(m, small, new Size(320, 240));

small.copyTo(out);

}

}

错 2：把 Session / 预分配 tensor attach 进每帧 scope

引擎级对象生命周期是「进程/服务」，不是「这一帧」。attach 进帧 scope = 第一帧结束就拆掉引擎。

错 3：假设 Deallocator 线程会救你

JavaCPP 有延迟释放机制，但延迟可能秒级到更久，热路径不可依赖。Scope 给的是确定性释放时机。

8. 热路径架构：帧 scope × 引擎字段

CODE

// 伪代码：拉流循环

OrtSession session = factory.create(...); // 循环外

Mat reuseBuf = new Mat(); // 循环外预分配输出

for (;;) {

Frame f = grabber.grab();

try (PointerScope frameScope = new PointerScope()) {

Mat bgr = converter.convert(f); // 临时

Mat small = new Mat();

resize(bgr, small, new Size(640, 640));

runInfer(session, small, reuseBuf); // session/reuseBuf 不进 scope

} // 本帧临时 Mat 释放

}

session.close();

reuseBuf.close();

9. 和「手写 close」怎么选

10. 排障清单与自测题

1. 跑 mvn -q compile exec:java，确认 after scope totalBytes 回到 baseline
2. 故意去掉 try-with-resources，循环 1 万次，对比 RSS（应明显变差）
3. 写单测：scope 内 if (cond) return; 后 totalBytes 仍应回到 baseline
4. 若 scope 后 totalBytes 不降：对象可能没挂进 scope → 显式 attach 或继续手写 close
5. 排查 double-free：是否把调用方 Pointer attach 进了短 scope

自测题：写一个方法，输入 BGR Mat，输出边缘图到调用方提供的 out。 要求：方法内至少 3 个临时 Mat，全部由 PointerScope 管理，且方法可提前 return 而不泄漏。