docs: Add notes about thread safety and using heap from ISRs

Closes https://github.com/espressif/esp-idf/issues/3768

diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst
index cf6eb5020dc1cf1ffe1a142732c54330b550d10c..d2e5222f40ef783697a098d48663732152a820a1 100644 (file)
--- a/docs/en/api-reference/system/mem_alloc.rst
+++ b/docs/en/api-reference/system/mem_alloc.rst
@@ -113,6 +113,13 @@ API Reference - Heap Allocation
 
 .. include:: /_build/inc/esp_heap_caps.inc
 
+Thread Safety
+^^^^^^^^^^^^^
+
+Heap functions are thread safe, meaning they can be called from different tasks simultaneously without any limitations.
+
+It is technically possible to call ``malloc``, ``free``, and related functions from interrupt handler (ISR) context. However this is not recommended, as heap function calls may delay other interrupts. It is strongly recommended to refactor applications so that any buffers used by an ISR are pre-allocated outside of the ISR. Support for calling heap functions from ISRs may be removed in a future update.
+
 Heap Tracing & Debugging
 ------------------------