Class KernelConnection

Implementation of the Kernel object.

Notes

Messages from the server are handled in the order they were received and asynchronously. Any message handler can return a promise, and message handling will pause until the promise is fulfilled.

Hierarchy

  • KernelConnection

Implements

Constructors

Properties

_anyMessage: any
_assertCurrentMessage: any

Check to make sure it is okay to proceed to handle a message.

Notes

Because we handle messages asynchronously, before a message is handled the kernel might be disposed or restarted (and have a different session id). This function throws an error in each of these cases. This is meant to be called at the start of an asynchronous message handler to cancel message processing if the message no longer is valid.

_clearKernelState: any

Clear the internal state.

_clearSocket: any

Forcefully clear the socket state.

Notes

This will clear all socket state without calling any handlers and will not update the connection status. If you call this method, you are responsible for updating the connection status as needed and recreating the socket if you plan to reconnect.

_clientId: any
_comms: any
_connectionStatus: any
_connectionStatusChanged: any
_createSocket: any

Create the kernel websocket connection and add socket status handlers.

_displayIdToParentIds: any
_disposed: any
_errorIfDisposed: any

Utility function to throw an error if this instance is disposed.

_futures: any
_handleCommClose: any

Handle 'comm_close' kernel message.

_handleCommMsg: any

Handle a 'comm_msg' kernel message.

_handleCommOpen: any

Handle a comm_open kernel message.

_handleDisplayId: any

Handle a message with a display id.

Returns

Whether the message was handled.

_handleMessage: any
_hasPendingInput: any
_id: any
_info: any
_iopubMessage: any
_isDisposed: any
_kernelSession: any
_model: any
_msgChain: any
_msgIdToDisplayIds: any
_name: any
_noOp: any
_onWSClose: any

Handle a websocket close event.

_onWSMessage: any

Handle a websocket message, validating and routing appropriately.

_onWSOpen: any

Handle a websocket open event.

_pendingInput: any
_pendingMessages: any
_reason: any
_reconnect: any

Attempt a connection if we have not exhausted connection attempts.

_reconnectAttempt: any
_reconnectLimit: any
_reconnectTimeout: any
_selectedProtocol: any
_sendKernelShellControl: any
_sendMessage: any

Send a message on the websocket.

If queue is true, queue the message for later sending if we cannot send now. Otherwise throw an error.

Notes

As an exception to the queueing, if we are sending a kernel_info_request message while we think the kernel is restarting, we send the message immediately without queueing. This is so that we can trigger a message back, which will then clear the kernel restarting state.

_sendPending: any

Send pending messages to the kernel.

_specPromise: any
_status: any
_statusChanged: any
_supportedProtocols: any
_targetRegistry: any
_unhandledMessage: any
_unregisterComm: any

Unregister a comm instance.

_updateConnectionStatus: any

Handle connection status changes.

_updateStatus: any

Handle status iopub messages from the kernel.

_username: any
_ws: any

Websocket to communicate with kernel.

handleComms: boolean

Handle comm messages

Notes

The comm message protocol currently has implicit assumptions that only one kernel connection is handling comm messages. This option allows a kernel connection to opt out of handling comms.

See https://github.com/jupyter/jupyter_client/issues/263

serverSettings: ServerConnection.ISettings

The server settings for the kernel.

Accessors

  • get anyMessage(): ISignal<this, IAnyMessageArgs>
  • A signal emitted for any kernel message.

    Notes

    This signal is emitted when a message is received, before it is handled asynchronously.

    This message is emitted when a message is queued for sending (either in the websocket buffer, or our own pending message buffer). The message may actually be sent across the wire at a later time.

    The message emitted in this signal should not be modified in any way.

    Returns ISignal<this, IAnyMessageArgs>

  • get clientId(): string
  • The client unique id.

    Returns string

  • get disposed(): ISignal<this, void>
  • A signal emitted when the object is disposed.

    Returns ISignal<this, void>

  • get hasPendingInput(): boolean
  • Whether the kernel connection has pending input.

    Notes

    This is a guard to avoid deadlock is the user asks input as second time before submitting his first input

    Returns boolean

  • set hasPendingInput(value): void
  • Whether the kernel connection has pending input.

    Notes

    This is a guard to avoid deadlock is the user asks input as second time before submitting his first input

    Parameters

    • value: boolean

    Returns void

  • get id(): string
  • The id of the server-side kernel.

    Returns string

  • get isDisposed(): boolean
  • Test whether the kernel has been disposed.

    Returns boolean

  • get name(): string
  • The name of the server-side kernel.

    Returns string

  • get pendingInput(): ISignal<this, boolean>
  • A signal emitted when a kernel has pending inputs from the user.

    Returns ISignal<this, boolean>

  • get username(): string
  • The client username.

    Returns string

Methods

  • Create a new comm.

    Notes

    If a client-side comm already exists with the given commId, an error is thrown. If the kernel does not handle comms, an error is thrown.

    Parameters

    • targetName: string
    • Optional commId: string

    Returns IComm

  • Dispose of the resources held by the kernel.

    Returns void

  • Handles a kernel shutdown.

    Notes

    This method should be called if we know from outside information that a kernel is dead (for example, we cannot find the kernel model on the server).

    Returns void

  • Check if a comm exists.

    Parameters

    • commId: string

    Returns boolean

  • Interrupt a kernel.

    Notes

    Uses the Jupyter Notebook API.

    The promise is fulfilled on a valid response and rejected otherwise.

    It is assumed that the API call does not mutate the kernel id or name.

    The promise will be rejected if the kernel status is Dead or if the request fails or the response is invalid.

    Returns Promise<void>

  • Reconnect to a kernel.

    Notes

    This may try multiple times to reconnect to a kernel, and will sever any existing connection.

    Returns Promise<void>

  • Register a comm target handler.

    Parameters

    • targetName: string

      The name of the comm target.

    • callback: ((comm, msg) => void | PromiseLike<void>)

      The callback invoked for a comm open message.

        • (comm, msg): void | PromiseLike<void>
        • Parameters

          Returns void | PromiseLike<void>

    Returns void

    A disposable used to unregister the comm target.

    Notes

    Only one comm target can be registered to a target name at a time, an existing callback for the same target name will be overridden. A registered comm target handler will take precedence over a comm which specifies a target_module.

    If the callback returns a promise, kernel message processing will pause until the returned promise is fulfilled.

  • Register an IOPub message hook.

    Parameters

    • msgId: string
    • hook: ((msg) => boolean | PromiseLike<boolean>)

      The callback invoked for the message.

      Notes

      The IOPub hook system allows you to preempt the handlers for IOPub messages that are responses to a given message id.

      The most recently registered hook is run first. A hook can return a boolean or a promise to a boolean, in which case all kernel message processing pauses until the promise is fulfilled. If a hook return value resolves to false, any later hooks will not run and the function will return a promise resolving to false. If a hook throws an error, the error is logged to the console and the next hook is run. If a hook is registered during the hook processing, it will not run until the next message. If a hook is removed during the hook processing, it will be deactivated immediately.

      See also [[IFuture.registerMessageHook]].

    Returns void

  • Remove a comm target handler.

    Parameters

    • targetName: string

      The name of the comm target to remove.

    • callback: ((comm, msg) => void | PromiseLike<void>)

      The callback to remove.

      Notes

      The comm target is only removed if the callback argument matches.

        • (comm, msg): void | PromiseLike<void>
        • Parameters

          Returns void | PromiseLike<void>

    Returns void

  • Remove the input guard, if any.

    Returns void

  • Remove an IOPub message hook.

    Parameters

    • msgId: string
    • hook: ((msg) => boolean | PromiseLike<boolean>)

      The callback invoked for the message.

    Returns void

  • Send a comm_info_request message.

    Notes

    Fulfills with the comm_info_reply content when the shell reply is received and validated.

    Parameters

    • content: {
          target_name?: string;
      }
      • Optional target_name?: string

        The comm target name to filter returned comms

    Returns Promise<ICommInfoReplyMsg>

  • Send an execute_request message.

    Notes

    See Messaging in Jupyter.

    Future onReply is called with the execute_reply content when the shell reply is received and validated. The future will resolve when this message is received and the idle iopub status is received. The future will also be disposed at this point unless disposeOnDone is specified and false, in which case it is up to the caller to dispose of the future.

    See also: [[IExecuteReply]]

    Parameters

    • content: {
          allow_stdin?: boolean;
          code: string;
          silent?: boolean;
          stop_on_error?: boolean;
          store_history?: boolean;
          user_expressions?: JSONObject;
      }
      • Optional allow_stdin?: boolean

        Whether to allow stdin requests. The default is true.

      • code: string

        The code to execute.

      • Optional silent?: boolean

        Whether to execute the code as quietly as possible. The default is false.

      • Optional stop_on_error?: boolean

        Whether to the abort execution queue on an error. The default is false.

      • Optional store_history?: boolean

        Whether to store history of the execution. The default true if silent is False. It is forced to false if silent is true.

      • Optional user_expressions?: JSONObject

        A mapping of names to expressions to be evaluated in the kernel's interactive namespace.

    • Optional disposeOnDone: boolean
    • Optional metadata: JSONObject

    Returns IShellFuture<IExecuteRequestMsg, IExecuteReplyMsg>

  • Request a kernel restart.

    Notes

    Uses the Jupyter Notebook API and validates the response model.

    Any existing Future or Comm objects are cleared once the kernel has actually be restarted.

    The promise is fulfilled on a valid server response (after the kernel restarts) and rejected otherwise.

    It is assumed that the API call does not mutate the kernel id or name.

    The promise will be rejected if the request fails or the response is invalid.

    Returns Promise<void>

  • Send a control message to the kernel.

    Notes

    Send a message to the kernel's control channel, yielding a future object for accepting replies.

    If expectReply is given and true, the future is disposed when both a control reply and an idle status message are received. If expectReply is not given or is false, the future is resolved when an idle status message is received. If disposeOnDone is not given or is true, the Future is disposed at this point. If disposeOnDone is given and false, it is up to the caller to dispose of the Future.

    All replies are validated as valid kernel messages.

    If the kernel status is dead, this will throw an error.

    Type Parameters

    Parameters

    • msg: IControlMessage<T>
    • Optional expectReply: boolean
    • Optional disposeOnDone: boolean

    Returns IControlFuture<IControlMessage<T>, IControlMessage<ControlMessageType>>

  • Send a shell message to the kernel.

    Notes

    Send a message to the kernel's shell channel, yielding a future object for accepting replies.

    If expectReply is given and true, the future is disposed when both a shell reply and an idle status message are received. If expectReply is not given or is false, the future is resolved when an idle status message is received. If disposeOnDone is not given or is true, the Future is disposed at this point. If disposeOnDone is given and false, it is up to the caller to dispose of the Future.

    All replies are validated as valid kernel messages.

    If the kernel status is dead, this will throw an error.

    Type Parameters

    Parameters

    • msg: IShellMessage<T>
    • Optional expectReply: boolean
    • Optional disposeOnDone: boolean

    Returns IShellFuture<IShellMessage<T>, IShellMessage<ShellMessageType>>

  • Shutdown a kernel.

    Notes

    Uses the Jupyter Notebook API.

    The promise is fulfilled on a valid response and rejected otherwise.

    On a valid response, disposes this kernel connection.

    If the kernel is already dead, disposes this kernel connection without a server request.

    Returns Promise<void>

Generated using TypeDoc