From be945f82c1759b04ef887ab2c1d114aceb43095c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dariusz=20J=C4=99drzejczyk?= Date: Mon, 2 Dec 2024 13:40:53 +0100 Subject: [PATCH] [docs] Add warning about static exceptions (#3944) In case of enabled debugging or checkpoints, usage of static exceptions in user code can cause memory leaks. A warning note has been added to the debugging section. Related to #3941 --- docs/modules/ROOT/pages/debugging.adoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/modules/ROOT/pages/debugging.adoc b/docs/modules/ROOT/pages/debugging.adoc index 3a3454f345..e2a9c0aeec 100644 --- a/docs/modules/ROOT/pages/debugging.adoc +++ b/docs/modules/ROOT/pages/debugging.adoc @@ -324,6 +324,20 @@ If that is somehow not desirable, tracebacks can be identified thanks to `Except check, and excluded from such an unwrap by using `Exceptions.unwrapMultipleExcludingTracebacks(Throwable)` instead. +WARNING: *Static exceptions*: +Optimizing exception handling sometimes involves reusing exceptions via pre-creating +global static instances instead of creating new instances upon an exceptional state +occuring. With such reused exceptions, tracebacks will start to accumulate as +appended suppressed exceptions and inevitably lead to memory leaks. In most +circumstances static exceptions are used in combination with disabling stacktrace +capturing which is the biggest contributor to the cost of creating exceptions. However, +exceptions can be created dynamically without a stack trace with only the marginal cost +of memory allocation and no need for static instances. In case your code still needs to +rely on static instances of exceptions, the way to avoid memory leaks with tracebacks is to +https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html#Throwable-java.lang.String-java.lang.Throwable-boolean-boolean-[disable suppression] +at the expense of not being able to see tracebacks if these exceptions are propagated +down the reactive chain. + We deal with a form of instrumentation here, and creating a stack trace is costly. That is why this debugging feature should only be activated in a controlled manner, as a last resort.