chore: import upstream snapshot with attribution

2026-07-13 12:47:05 +08:00
commit 4f3b7da785
7394 changed files with 2005594 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Deeplearning4j: Enhanced Stack Trace Feature Overview
+
+## Introduction
+
+For developers who are knee-deep in troubleshooting, understanding where a problem originated can be invaluable. In line with that, Deeplearning4j now introduces an advanced feature that provides an insightful fusion of Java and C++ stack traces. This is especially useful when debugging issues related to memory allocation and deallocation.
+
+## Feature: SD_GCC_FUNCTRACE
+
+When you build Deeplearning4j with the `SD_GCC_FUNCTRACE` option turned on, it activates the ability to display C++ stack traces. This powerful feature, however, comes with a caveat: it requires numerous platform-specific dependencies to function seamlessly.
+
+### What's New?
+
+When the aforementioned feature is active, developers can now enable a fresh capability that showcases both Java and C++ stack traces at every instance of memory allocation and deallocation in the Deeplearning4j codebase.
+
+Here's the crux of this new feature:
+
+1. **Allocation and Deallocation Triggers**: The stack traces will be printed just as a buffer is about to be deallocated.
+2. **Crash Insights**: Typically, the last deallocation that took place will pinpoint the site of the crash.
+3. **Full Problem Context**: By analyzing Java and C++ stack traces side by side, developers can derive a comprehensive understanding of the issue at hand.
+4. **Enhancement Over Sanitizers**: This feature is a supplement to sanitizers, which occasionally falter in showing internal stack traces instead of the real underlying problem.
+
+## Enabling the Feature
+
+Activating this feature is straightforward. Here's a snippet to do just that:
+
+```java
+Nd4j.getEnvironment().setFuncTraceForAllocate(true);
+Nd4j.getEnvironment().setFuncTraceForDeallocate(true);
+```
+
+With these lines of code:
+
+- The first line will enable the printing of stack traces during memory allocation.
+- The second line will do the same for deallocation.
+
+## Conclusion
+
+By leveraging this new feature, developers can achieve a granular understanding of memory-related issues in Deeplearning4j's operations. This comprehensive insight into both Java and C++ realms will significantly streamline the debugging process and enhance code reliability.
+
+_Remember, while powerful, this feature can also be verbose. Hence, it's recommended to use it judiciously, primarily when deep troubleshooting is necessary._