Skip to content

Clarify exception recovery documentation regarding suppressed exceptions #2544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 2, 2021
Merged

Clarify exception recovery documentation regarding suppressed exceptions #2544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/topics/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ It is easy to demonstrate with actual stacktraces of the same program that await

The only downside of this approach is losing referential transparency of the exception.

> Note that suppressed exceptions are not copied and are left intact in the cause
> in order to prevent cycles in the exceptions chain, obscure`[CIRCULAR REFERENCE]` messages
> and even [crashes](https://jira.qos.ch/browse/LOGBACK-1027) in some frameworks

### Stacktrace recovery machinery

This section explains the inner mechanism of stacktrace recovery and can be skipped.
Expand Down
1 change: 1 addition & 0 deletions kotlinx-coroutines-core/common/src/Debug.common.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable
* For better debuggability, it is recommended to use original exception as [cause][Throwable.cause] of the resulting one.
* Stacktrace of copied exception will be overwritten by stacktrace recovery machinery by [Throwable.setStackTrace] call.
* An exception can opt-out of copying by returning `null` from this function.
* Suppressed exceptions of the original exception should not be copied in order to avoid circular exceptions.
*/
public fun createCopy(): T?
}