This refactor implements a new class hierarchy to manage the lifetime of a
Jupyter kernel. The first node in this hierarchy is the
`jupyter-kernel-lifetime` class which defines a set of methods to manage the
lifetime of a kernel. An object that inherits from `jupyter-kernel-lifetime` is
stating that it has an association with a kernel and can be used to manage the
lifetime of the associated kernel.
The `jupyter-meta-kernel` class inherits from `jupyter-kernel-lifetime` and
mainly defines a `spec` slot used to hold the `kernelspec` from which a command
can be constructed to start a kernel and a `session` slot used to hold the
`jupyter-session` object that clients can use to establish communication with a
kernel once its live. Concrete classes that actually launch kernels are
intended to inherit from this class and use its slots.
`jupyter-kernel-process` manages the lifetime of a kernel started as a process
using the function `start-file-process`, `jupyter-command-kernel` calls the
`jupyter kernel` shell command to start a kernel, finally `jupyter-spec-kernel`
uses the `spec` slot to construct a shell command to start a kernel.
A `jupyter-kernel-manager` now consists of a `kernel` slot that holds a
`jupyter-meta-kernel` and a `control-channel` slot and inherits from
`jupyter-kernel-lifetime`. The `jupyter-kernel-lifetime` methods of the manager
just defer to those of `kernel` while also taking into account the
`control-channel`.
* jupyter-base.el (jupyter-write-connection-file): New function.
* jupyter-channel-ioloop.el
(jupyter-channel-ioloop-add-start-channel-event): Remove `sleep-for` call.
The startup message is not so important anymore.
* jupyter-client.el (jupyter-wait-until-startup: New function.
* jupyter-kernel-manager.el (jupyter-kernel-lifetime)
(jupyter-kernel, jupyter-kernel-process, jupyter-command-kernel)
(jupyter-spec-kernel): New classes.
(jupyter-kernel-manager): Inherit from jupyter-kernel-lifetime only and
implement its methods.
(jupyter-kernel-manager--cleanup, jupyter-kernel-managers)
(jupyter-delete-all-kernels, jupyter--kernel-sentinel)
(jupyter--start-kernel): Remove and remove related, their functionality has
been generalized in the new classes.
(jupyter-interrupt-kernel, jupyter-shutdown-kernel)
(jupyter-start-channels, jupyter-start-kernel, jupyter-kernel-alive-p)
(jupyter-kill-kernel): Refactor and implement to use the new class hierarchy.
* test/jupyter-test.el: Refactor tests to account for changes.
(jupyter-write-connect-file, jupyter-command-kernel): New tests.
* jupyter-kernelspec.el (jupyter-guess-kernelspec): New function.
The previous mechanism to communicate with a kernel was too low level from the
perspective of a client. The client interfaced directly with the subprocess
abstraction, `jupyter-ioloop`, and had to handle all "events" that occurred in
the `jupyter-ioloop`, e.g. when a channel was started or stopped. But in
reality such events should not be the concern of a client.
A client should only care about events that are directly related to kernel
messages and not events related to the implementation details of *how*
communication occurs.
This commit abstracts out the way in which a client communicates with its
kernel by introducing a new `jupyter-comm-layer` class. The
`jupyter-comm-layer` class takes care of managing the communication channel
between a kernel and its clients as well as sending events to all registered
clients. This way, clients operate solely at the level of events on the
communication layer. All a client does is register itself to receive events on
the communication layer and send events on the layer.
* jupyter-base.el (jupyter-session-endpoints): New function.
* jupyter-client.el (jupyter-kernel-client): Remove ioloop and channels slots.
Add kcomm slot.
(initialize-instance): Unconditionally stop channels.
(jupyter-initialize-connection): Change into a method call.
Call `jupyter-initialize-connection` on the `kcomm` slot.
(jupyter-with-client-buffer): Remove stale comment.
(jupyter-send): Call `jupyter-send` on the `kcomm` slot.
(jupyter-ioloop-handler): Remove all method definitions, replace `sent` and
`message` methods with their `jupyter-event-handler` equivalents.
(jupyter-hb-pause, jupyter-hb-unpause, jupyter-hb-beating):
(jupyter-channel-alive-p, jupyter-start-channel, jupyter-stop-channel):
(jupyter-start-channels, jupyter-stop-channels):
Replace with calls to their equivalents using the `kcomm` slot.
* jupyter-comm-layer.el: New file.
* jupyter-kernel-manager (jupyter-make-client): Set a client's `kcomm` slot to
`jupyter-channel-ioloop-comm`.
* jupyter-messages.el (jupyter-decode-message): Use `list` directly. There
seemed to be issues when using the new `jupyter-sync-channel-comm` due to
using quoted lists.
* test/jupyter-test.el: Add `jupyter-comm-layer` test. Update other tests.
* test/test-helper.el: Add `jupyter-comm-layer` mock objects. Update
`jupyter-echo-client`.
See https://github.com/dzop/emacs-jupyter/issues/70#issuecomment-476940527
* jupyter-kernel-manager.el
(jupyter--kernel-sentinel): Make ignored argument optional.
(jupyter--start-kernel): Don't set the process sentinel.
(jupyter-start-kernel): Report any errors after timeout.
Set the process sentinel as a last step.
When a kernel restarts, `jupyter-start-kernel` will overwrite the slots
corresponding to external resources of the old, shutdown, kernel, like the
connection file. Ensure resources are cleaned up before overwriting those
slots.
Add this to `kill-emacs-hook` to ensure that connection files are cleaned up in
a more reliable fashion. The connection files are cleaned up when the kernel
process is garbage collected, but this won't happen when killing Emacs.
* jupyter-kernel-manager.el (jupyter-delete-all-kernels): Do it.
Add to `kill-emacs-hook`.
It still sometimes isn't caught but it is more reliable. This mainly affects
testing.
* jupyter-client.el (jupyter-start-channels): Add a small delay after starting
channels.
* jupyter-kernel-manager.el (jupyter-start-kernel): Remove superfluous delay.
This is needed as opposed to eieio-instance-tracker so that we can create weak
references to objects. We don't want to have to manually delete an instance.
* jupyter-base.el (jupyter-instance-tracker): Do it.
(jupyter-all-objects): New function.
* jupyter-client.el (jupyter--clients): New variable.
(jupyter-kernel-client): Inherit from new class.
(jupyter-clients): Use jupyter-all-objects.
* jupyter-kernel-manager.el (jupyter-kernel-managers): New function.
* jupyter-base.el (jupyter-default-timeout)
(jupyter-long-timeout): Moved from jupyter-client.el
(jupyter-with-timeout): Do it.
* jupyter-client.el (jupyter-wait-until): Use it.
* jupyter-kernel-manager.el (jupyter-shutdown-kernel)
(jupyter-interrupt-kernel, jupyter-start-new-kernel):
(jupyter-start-kernel): Use it.
use timeout
* jupyter-client.el (jupyter-kernel-client): Do it.
(jupyter-run-hook-with-args-until-success): Pass client as first argument to
hooks.
(jupyter-execution-state): New convenience function.
(jupyter--set-execution-state): New helper function. Add as global IOPUB
message hook to set the execution-state slot.
* jupyter-repl.el (jupyter-repl-client): Remove execution-state slot.
(jupyter-handle-status): Don't set the execution-state slot.
(jupyter-repl-ret, jupyter-repl-interaction-mode-line): Use
jupyter-execution-state.
(jupyter-repl-initialize-hooks): Take into account changes to message hooks.
* jupyter-kernel-manager (jupyter-start-new-kernel): Update callback.
* Declare undeclared external functions
* Add ext: prefix to filename of external packages that may not be present on
every system
* Remove `company-grab-symbol-cons` function declaration since this function is
no longer used.
If `kill-emacs` is called while the kernel process or client channel processes
are still alive, the process sentinels do not run and thus the cleanup of the
clients and managers does not happen. Thus we need to explicitly do this
cleanup when `kill-emacs` is called.
* Define new method `jupyter-kernel-info` which takes care
of caching the result of a kernel info request. All
access of the kernel info plist should happen through
this method.
* Do not return the kernel info plist in
`jupyter-start-new-kernel`, callers should access the
kernel info through `jupyter-kernel-info`
