Files
ANSCORE/MediaClient/media/av_frame_ptr.h

73 lines
2.8 KiB
C++

#pragma once
// av_frame_ptr.h — RAII smart pointer for FFmpeg AVFrame*.
//
// Why this exists
// ---------------
// CVideoPlayer::getNV12Frame() / getCudaHWFrame() return cloned AVFrame* and
// the contract is "caller must av_frame_free()". That contract is comment-only
// — nothing in the type system enforces it, so any early return, exception,
// or refactor that drops the pointer leaks the AVFrame *and* the underlying
// NV12/YUV420P/YUVJ420P buffers (~3 MB per 1080p frame, ~50 MB/s under load).
//
// AvFramePtr wraps the raw pointer in std::unique_ptr<AVFrame, AvFrameDeleter>
// so the destructor frees it automatically — leak-by-omission becomes a
// compile-time impossibility on every internal code path that adopts this type.
//
// Scope: INTERNAL TO ANSCORE ONLY.
// -------------------------------
// Do NOT change DLL-exported function signatures to use AvFramePtr.
// std::unique_ptr cannot cross a DLL boundary safely (different runtimes,
// different STL implementations, different allocators). The public
// AVFrame*-returning APIs in ANSRTSP.h / ANSSRT.h / etc. must remain raw
// pointers for ABI stability.
//
// Use this type at the internal *consumer* call site:
//
// AvFramePtr nv12{ player->getNV12Frame() };
// if (nv12) {
// doSomething(nv12.get()); // borrowed access
// } // auto-freed on scope exit
//
// To transfer ownership into ANSCV's pendingFree pipeline (the
// gpu_frame_attach / gpu_frame_attach_cuda functions, which take raw
// AVFrame* and store/defer them), call .release():
//
// AvFramePtr nv12{ player->getNV12Frame() };
// gpu_frame_attach(mat, nv12.release(), gpuIdx, pts);
//
// Every .release() in the codebase is a deliberate ownership hand-off —
// `git grep '\.release()'` over the migrated files gives an audit list.
extern "C" {
#include <libavutil/frame.h>
}
#include <memory>
namespace ansmedia {
// Custom deleter that calls av_frame_free (which takes AVFrame**).
// noexcept because deleters must not throw — av_frame_free is a C function
// and never throws, but tagging makes the contract explicit.
struct AvFrameDeleter {
void operator()(AVFrame* f) const noexcept {
if (f) {
av_frame_free(&f); // takes AVFrame**, sets *f to nullptr internally
}
}
};
// Owning smart pointer for AVFrame*. Frees on destruction via av_frame_free.
//
// Construction:
// AvFramePtr p; // empty
// AvFramePtr p{ av_frame_clone(src) }; // adopt raw clone
//
// Ownership transfer (e.g. handing off to gpu_frame_attach_cuda):
// takes_ownership(p.release()); // raw pointer escapes, no auto-free
//
// Copy is disallowed (unique_ptr semantics). Move is fine.
using AvFramePtr = std::unique_ptr<AVFrame, AvFrameDeleter>;
} // namespace ansmedia