Skip to content

Conversation

@andidev
Copy link
Contributor

@andidev andidev commented Feb 2, 2026

fixes #1

@ssxv ssxv self-requested a review February 7, 2026 22:16
@ssxv
Copy link
Owner

ssxv commented Feb 8, 2026

Background

The Windows implementation had a critical N-API threading issue where Napi::Reference<Napi::Buffer<char>> was accessed from background threads, causing:

Fatal error in v8::HandleScope::CreateHandle()
Cannot create a handle without a HandleScope

Technical Comparison

Aspect Windows (Before Patch) Windows (After Patch) POSIX (Current)
Small Buffers (≤4MB) Buffer reference ❌ Copy to vector ✅ Copy to string ✅
Large Buffers (>4MB) Temp file ✅ Temp file ✅ Temp file ✅
Thread Safety HandleScope violation ❌ Safe ✅ Safe ✅
V8 Handle Access Background thread ❌ None ✅ None ✅

Root Cause Analysis

The Windows implementation attempted a "zero-copy optimization" by keeping buffer references alive, but this violated N-API threading rules. V8 handles (including Napi::Reference) can only be accessed from the main thread within a proper HandleScope.

The POSIX implementation was designed correctly from the start - it never attempted buffer references and always used the safe copy-or-temp-file strategy.

Conclusion
✅ POSIX implementation requires NO changes - it already follows the safe pattern
✅ Windows patch correctly fixes the threading violation
✅ Both platforms now use identical safe strategies

The memory overhead of copying small buffers (≤4MB) is negligible compared to the benefit of crash-free operation, and large buffers still use efficient temp file streaming on both platforms.

@ssxv ssxv merged commit ff809ff into ssxv:main Feb 8, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fails to work with node-thermal-printer since Buffer passed is referenced instead of copied

2 participants