From 78e5894e9deb16bb228952e69dec33f6fd171f10 Mon Sep 17 00:00:00 2001 From: Arman Bilge Date: Fri, 26 May 2023 12:30:14 -0400 Subject: [PATCH] Document that signals don't work for fiber dumps on JDK8 --- docs/core/fiber-dumps.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/fiber-dumps.md b/docs/core/fiber-dumps.md index 490756fd45..a6650808a5 100644 --- a/docs/core/fiber-dumps.md +++ b/docs/core/fiber-dumps.md @@ -70,11 +70,11 @@ Summary statistics for the global fiber runtime are printed following the fiber ## Triggering a fiber dump -Triggering the above fiber dump is a matter of sending a POSIX signal to the process using the `kill` command. The exact signal is dependent on the JVM (and version thereof) and operating system under which your application is running. Rather than attempting to hard-code all possible compatible signal configurations, Cats Effect simply *attempts* to register *both* `INFO` and `USR1` (for JVM applications) or `USR2` (for Node.js applications). In practice, `INFO` will most commonly be used on macOS and BSD, while `USR1` is more common on Linux. Thus, `kill -INFO ` on macOS and `kill -USR1 ` on Linux (or `USR2` for Node.js applications). POSIX signals do not exist on Windows (except under WSL, which behaves exactly like a normal Linux), and thus the mechanism is disabled. +Triggering the above fiber dump is a matter of sending a POSIX signal to the process using the `kill` command. The exact signal is dependent on the JVM (and version thereof) and operating system under which your application is running. Rather than attempting to hard-code all possible compatible signal configurations, Cats Effect simply *attempts* to register *both* `INFO` and `USR1` (for JVM applications) or `USR2` (for Node.js applications). In practice, `INFO` will most commonly be used on macOS and BSD, while `USR1` is more common on Linux. Thus, `kill -INFO ` on macOS and `kill -USR1 ` on Linux (or `USR2` for Node.js applications). POSIX signals do not exist on Windows (except under WSL, which behaves exactly like a normal Linux), and thus the mechanism is disabled. Unfortunately it is also disabled on JDK 8, which does not have any free signals available for applications to use. Since `INFO` is the signal used on macOS and BSD, this combined with a quirk of Apple's TTY implementation means that **anyone running a Cats Effect application on macOS can simply hit Ctrl-T** within the active application to trigger a fiber dump, similar to how you can use Ctrl-\\ to trigger a thread dump. Note that this trick only works on macOS, since that is the only platform which maps a particular keybind to either the `INFO` or `USR1` signals. -In the event that you're either running on a platform which doesn't support POSIX signals, or the signal registration failed for whatever reason, Cats Effect on the JVM will *also* automatically register an [MBean](https://docs.oracle.com/javase/7/docs/technotes/guides/management/overview.html) under `cats.effect.unsafe.metrics.LiveFiberSnapshotTriggerMBean` which can produce a string representation of the fiber dump when its only method is invoked. +In the event that you're either running on a platform which doesn't support POSIX signals, or the signal registration failed for whatever reason, Cats Effect on the JVM will *also* automatically register an [MBean](https://docs.oracle.com/javase/8/docs/technotes/guides/management/overview.html) under `cats.effect.unsafe.metrics.LiveFiberSnapshotTriggerMBean` which can produce a string representation of the fiber dump when its only method is invoked. ## Configuration