Skip to content

Commit

Permalink
Merge pull request #3680 from armanbilge/doc/no-signals-jdk8
Browse files Browse the repository at this point in the history
Document that signals don't work for fiber dumps on JDK8
  • Loading branch information
armanbilge authored Jun 12, 2023
2 parents 5783a0b + 78e5894 commit 3806bf1
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions docs/core/fiber-dumps.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <pid>` on macOS and `kill -USR1 <pid>` 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 <pid>` on macOS and `kill -USR1 <pid>` 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 <kbd>Ctrl</kbd>-<kbd>T</kbd>** within the active application to trigger a fiber dump, similar to how you can use <kbd>Ctrl</kbd>-<kbd>\\</kbd> 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

Expand Down

0 comments on commit 3806bf1

Please sign in to comment.