From e2f05e6ff97f9568f022391d9b4f6417a59ac722 Mon Sep 17 00:00:00 2001 From: Marc Udoff Date: Thu, 31 Aug 2023 20:07:04 -0400 Subject: [PATCH 1/3] Clarify restart to mean restart in-place Resolves #117 --- .../restart-clarification.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 118-restart-clarification/restart-clarification.md diff --git a/118-restart-clarification/restart-clarification.md b/118-restart-clarification/restart-clarification.md new file mode 100644 index 00000000..3913e0ac --- /dev/null +++ b/118-restart-clarification/restart-clarification.md @@ -0,0 +1,58 @@ +--- +title: Restart Clarification +authors: Marc Udoff (@mlucool) +issue-number: [#117](https://github.com/jupyter/enhancement-proposals/issues) +pr-number: [#118](https://github.com/jupyter/enhancement-proposals/pull/118) +date-started: 2023-08-23 +--- + +# Summary + +The jupyter client protocol around what "restart" means is ambiguous. Per Jupyter Client's [kernel shutdown documention](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-shutdown), the only guidance is: +> 'restart' : bool # False if final shutdown, or True if shutdown precedes a restart + +This has led to a situation where certain jupyter subprojects (e.g. enterprise gateway) have interpreted this to mean a "hard restart", or restart the whole process tree. + +We propose to clarify this to always mean "restart-in-place", that is only restart the kernel itself. For +most usage of Jupyter, this change is a no-op as subprocess kernels already act like this. + +# Motivation + +This greatly improves the usability of remote kernels whose startup includes scheduling. By making this change, +restarts for remote kernels will be nearly as fast as those of local kernels. It also matches what we +believe to be the mental model of users when they click "restart". + +# Guide-level explanation + +The [protocol](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-shutdown) would describe +restart as restarting only the kernel process and its subprocess *not* any parent process. + +When the kernel is a toplevel process (e.g. local kernels), there is no change. + +When the kernel is not a toplevel process (e.g. when used in Enterprise Gateway), restart means only the kernel restarts. To restart the whole progress group, the stop and start messages must be used. It's up to UIs +for how to display this difference (if any). + +# Reference-level explanation + +The `jupyter-client` messaging page would be updated to indicate this nuance. Any implementations that +treat restart differently would be updated to match this clarification. + +# Rationale and alternatives + +A new message could be added, as proposed in the pre-JEP. In the [Jupyter Server meeting](https://github.com/jupyter-server/team-compass/issues/45#issuecomment-1682582186), +we concluded that is is likely most users want restart to only restart the kernel and not potentially reschedule resources. Therefore, a new message was not the best option. +For the vast majority of kernels (local subprocesses), this change is a no-op because restart-in-place +is the same as a hard restart since it is the toplevel kernel process. + +# Prior art + +N/A + +# Unresolved questions + +Only the exact wording changes as proposed in [jupyter_client](https://github.com/jupyter/jupyter_client/pull/966). + +# Future possibilities + +We would make a service that implements a "hard restart" as discussed in the juptyer-server meeting. +No one on the meeting had an immediate use case for it. From 55b11344ce53f11194f28ab9fcf95698637a9c91 Mon Sep 17 00:00:00 2001 From: Marc Udoff Date: Fri, 1 Sep 2023 10:23:00 -0400 Subject: [PATCH 2/3] Review feedback --- 118-restart-clarification/restart-clarification.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/118-restart-clarification/restart-clarification.md b/118-restart-clarification/restart-clarification.md index 3913e0ac..6022d1f3 100644 --- a/118-restart-clarification/restart-clarification.md +++ b/118-restart-clarification/restart-clarification.md @@ -25,11 +25,11 @@ believe to be the mental model of users when they click "restart". # Guide-level explanation The [protocol](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-shutdown) would describe -restart as restarting only the kernel process and its subprocess *not* any parent process. +restart as optimally preserving as many resources outside the kernel as possible (e.g. restarting only the kernel process and its subprocess *not* any parent process). When the kernel is a toplevel process (e.g. local kernels), there is no change. -When the kernel is not a toplevel process (e.g. when used in Enterprise Gateway), restart means only the kernel restarts. To restart the whole progress group, the stop and start messages must be used. It's up to UIs +When the kernel is not a toplevel process (e.g. when used in Enterprise Gateway), restart often means only the kernel restarts. To restart the whole progress group, the stop and start messages could be used. It's up to UIs for how to display this difference (if any). # Reference-level explanation @@ -44,6 +44,8 @@ we concluded that is is likely most users want restart to only restart the kerne For the vast majority of kernels (local subprocesses), this change is a no-op because restart-in-place is the same as a hard restart since it is the toplevel kernel process. +For users that want a hard restart, a stop followed by a start continues to be available. While this may be less convenient, a UI can trivially hide this two call process from the user. + # Prior art N/A From 0e10b12c024e1f3420637d4a5ee74d1eeb920c0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Collonval?= Date: Tue, 24 Oct 2023 08:59:33 +0200 Subject: [PATCH 3/3] Fix typo Co-authored-by: Zachary Sailer --- 118-restart-clarification/restart-clarification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/118-restart-clarification/restart-clarification.md b/118-restart-clarification/restart-clarification.md index 6022d1f3..57a966aa 100644 --- a/118-restart-clarification/restart-clarification.md +++ b/118-restart-clarification/restart-clarification.md @@ -56,5 +56,5 @@ Only the exact wording changes as proposed in [jupyter_client](https://github.co # Future possibilities -We would make a service that implements a "hard restart" as discussed in the juptyer-server meeting. +We would make a service that implements a "hard restart" as discussed in the jupyter-server meeting. No one on the meeting had an immediate use case for it.