On Mon, 4 Jul 2022 16:47:28 GMT, Chris Hegarty <che...@openjdk.org> wrote:
>> I think the wording in the latest commit (9d972b) is problematic. One reason >> is that you've changed it to "will run shutdown hooks" but it doesn't run >> the hooks, it starts them, and so conflicts with the previous paragraph. I >> also think "That invocation may be initiated via platform specific signal >> handlers" is confusing here as there is no notion of "signal handler" to >> reference. There may be scope for text elsewhere, maybe with an implNote for >> signals such as HUP, but I don't think this is the PR for this. So I think >> it better to try the wording that David suggested and see if it needs any >> improvement. > > YAO (Yet Another Opinion)! But I think we're actually converging. > > David's wording: >>Invocations of this method are serialized such that only one invocation will >>actually proceed with the shutdown sequence and terminate the VM with the >>given status code. > > ... gives the impression that an invocation of this method WILL terminate the > VM with the given status code - which is not actually true, given the > potential for signals. This is already alluded to in > `Runtime::addShutdownHook`. I agree that this could be resolved separately, > but we should _allow_ for signals (even if we don't explicitly mention them). > > The original wording: >> If this method is invoked after all shutdown hooks have already been run ... > > ... seems quite clever (and allows for signals). Maybe we could keep things > super simple: >> If this method is invoked after shutdown hooks have already been started, it >> will block indefinitely. If this method is invoked from a shutdown hook the >> system will deadlock. I like the new suggested wording, but I would slightly tweak it. As Alan mentioned in another comment the first paragraph makes clear the method never returns normally. How does the following sound? > If this method is invoked after shutdown hooks have already been started, the > supplied status code will be ignored. If this method is invoked from a > shutdown hook the system will deadlock. ------------- PR: https://git.openjdk.org/jdk/pull/9351