1 | import { IIterator } from '@lumino/algorithm';
|
2 | import { JSONObject, JSONValue } from '@lumino/coreutils';
|
3 | import { IDisposable, IObservableDisposable } from '@lumino/disposable';
|
4 | import { ISignal } from '@lumino/signaling';
|
5 | import { ServerConnection } from '..';
|
6 | import * as KernelMessage from './messages';
|
7 | import { KernelSpec } from '../kernelspec';
|
8 | import { IManager as IBaseManager } from '../basemanager';
|
9 | import { IKernelOptions, IModel } from './restapi';
|
10 | export { Status } from './messages';
|
11 | export { IModel, IKernelOptions };
|
12 | /**
|
13 | * Interface of a Kernel connection that is managed by a session.
|
14 | *
|
15 | * #### Notes
|
16 | * The Kernel object is tied to the lifetime of the Kernel id, which is a
|
17 | * unique id for the Kernel session on the server. The Kernel object manages
|
18 | * a websocket connection internally, and will auto-restart if the websocket
|
19 | * temporarily loses connection. Restarting creates a new Kernel process on
|
20 | * the server, but preserves the Kernel id.
|
21 | *
|
22 | * The IKernelConnection is notably missing the full IKernel signals. This
|
23 | * interface is for situations where a kernel may change, but we want a user
|
24 | * to not have to worry about disconnecting and reconnecting signals when a
|
25 | * kernel is swapped. The object that maintains an IKernel, but only provides
|
26 | * a user with an IKernelConnection should proxy the appropriate IKernel
|
27 | * signals for the user with its own signals. The advantage is that when the
|
28 | * kernel is changed, the object itself can take care of disconnecting and
|
29 | * reconnecting listeners.
|
30 | */
|
31 | export interface IKernelConnection extends IObservableDisposable {
|
32 | /**
|
33 | * The id of the server-side kernel.
|
34 | */
|
35 | readonly id: string;
|
36 | /**
|
37 | * The name of the server-side kernel.
|
38 | */
|
39 | readonly name: string;
|
40 | /**
|
41 | * The kernel model, for convenience.
|
42 | */
|
43 | readonly model: IModel;
|
44 | /**
|
45 | * The client username.
|
46 | */
|
47 | readonly username: string;
|
48 | /**
|
49 | * The client unique id.
|
50 | *
|
51 | * #### Notes
|
52 | * This should be unique for a particular kernel connection object.
|
53 | */
|
54 | readonly clientId: string;
|
55 | /**
|
56 | * The current status of the kernel.
|
57 | */
|
58 | readonly status: KernelMessage.Status;
|
59 | /**
|
60 | * The current connection status of the kernel.
|
61 | */
|
62 | readonly connectionStatus: ConnectionStatus;
|
63 | /**
|
64 | * The kernel info
|
65 | *
|
66 | * #### Notes
|
67 | * This promise only resolves at startup, and is not refreshed on every
|
68 | * restart.
|
69 | */
|
70 | readonly info: Promise<KernelMessage.IInfoReply>;
|
71 | /**
|
72 | * Get the kernel spec.
|
73 | *
|
74 | * @returns A promise that resolves with the kernel spec for this kernel.
|
75 | *
|
76 | * #### Notes
|
77 | * This may make a server request to retrieve the spec.
|
78 | */
|
79 | readonly spec: Promise<KernelSpec.ISpecModel | undefined>;
|
80 | /**
|
81 | * Whether the kernel connection handles comm messages.
|
82 | *
|
83 | * #### Notes
|
84 | * The comm message protocol currently has implicit assumptions that only
|
85 | * one kernel connection is handling comm messages. This option allows a
|
86 | * kernel connection to opt out of handling comms.
|
87 | *
|
88 | * See https://github.com/jupyter/jupyter_client/issues/263
|
89 | */
|
90 | handleComms: boolean;
|
91 | /**
|
92 | * Whether the kernel connection has pending input.
|
93 | *
|
94 | * #### Notes
|
95 | * This is a guard to avoid deadlock is the user asks input
|
96 | * as second time before submitting his first input
|
97 | */
|
98 | hasPendingInput: boolean;
|
99 | /**
|
100 | * Send a shell message to the kernel.
|
101 | *
|
102 | * @param msg - The fully-formed shell message to send.
|
103 | *
|
104 | * @param expectReply - Whether to expect a shell reply message.
|
105 | *
|
106 | * @param disposeOnDone - Whether to dispose of the future when done.
|
107 | *
|
108 | * #### Notes
|
109 | * Send a message to the kernel's shell channel, yielding a future object
|
110 | * for accepting replies.
|
111 | *
|
112 | * If `expectReply` is given and `true`, the future is done when both a
|
113 | * shell reply and an idle status message are received with the appropriate
|
114 | * parent header, in which case the `.done` promise resolves to the reply.
|
115 | * If `expectReply` is not given or is `false`, the future is done when an
|
116 | * idle status message with the appropriate parent header is received, in
|
117 | * which case the `.done` promise resolves to `undefined`.
|
118 | *
|
119 | * If `disposeOnDone` is given and `false`, the future will not be disposed
|
120 | * of when the future is done, instead relying on the caller to dispose of
|
121 | * it. This allows for the handling of out-of-order output from ill-behaved
|
122 | * kernels.
|
123 | *
|
124 | * All replies are validated as valid kernel messages.
|
125 | *
|
126 | * If the kernel status is `'dead'`, this will throw an error.
|
127 | */
|
128 | sendShellMessage<T extends KernelMessage.ShellMessageType>(msg: KernelMessage.IShellMessage<T>, expectReply?: boolean, disposeOnDone?: boolean): IShellFuture<KernelMessage.IShellMessage<T>>;
|
129 | sendControlMessage<T extends KernelMessage.ControlMessageType>(msg: KernelMessage.IControlMessage<T>, expectReply?: boolean, disposeOnDone?: boolean): IControlFuture<KernelMessage.IControlMessage<T>>;
|
130 | /**
|
131 | * Reconnect to a disconnected kernel.
|
132 | *
|
133 | * @returns A promise that resolves when the kernel has reconnected.
|
134 | *
|
135 | * #### Notes
|
136 | * This just refreshes the connection to an existing kernel, and does not
|
137 | * perform an HTTP request to the server or restart the kernel.
|
138 | */
|
139 | reconnect(): Promise<void>;
|
140 | /**
|
141 | * Interrupt a kernel.
|
142 | *
|
143 | * @returns A promise that resolves when the kernel has interrupted.
|
144 | *
|
145 | * #### Notes
|
146 | * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels).
|
147 | *
|
148 | * The promise is fulfilled on a valid response and rejected otherwise.
|
149 | *
|
150 | * It is assumed that the API call does not mutate the kernel id or name.
|
151 | *
|
152 | * The promise will be rejected if the kernel status is `'dead'` or if the
|
153 | * request fails or the response is invalid.
|
154 | */
|
155 | interrupt(): Promise<void>;
|
156 | /**
|
157 | * Restart a kernel.
|
158 | *
|
159 | * @returns A promise that resolves when the kernel has restarted.
|
160 | *
|
161 | * #### Notes
|
162 | * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
|
163 | *
|
164 | * Any existing Future or Comm objects are cleared.
|
165 | *
|
166 | * It is assumed that the API call does not mutate the kernel id or name.
|
167 | *
|
168 | * The promise will be rejected if the kernel status is `'dead'` or if the
|
169 | * request fails or the response is invalid.
|
170 | */
|
171 | restart(): Promise<void>;
|
172 | /**
|
173 | * Send a `kernel_info_request` message.
|
174 | *
|
175 | * @param content - The content of the request.
|
176 | *
|
177 | * @returns A promise that resolves with the response message.
|
178 | *
|
179 | * #### Notes
|
180 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-info).
|
181 | *
|
182 | * Fulfills with the `kernel_info_response` content when the shell reply is
|
183 | * received and validated.
|
184 | */
|
185 | requestKernelInfo(): Promise<KernelMessage.IInfoReplyMsg | undefined>;
|
186 | /**
|
187 | * Send a `complete_request` message.
|
188 | *
|
189 | * @param content - The content of the request.
|
190 | *
|
191 | * @returns A promise that resolves with the response message.
|
192 | *
|
193 | * #### Notes
|
194 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#completion).
|
195 | *
|
196 | * Fulfills with the `complete_reply` content when the shell reply is
|
197 | * received and validated.
|
198 | */
|
199 | requestComplete(content: KernelMessage.ICompleteRequestMsg['content']): Promise<KernelMessage.ICompleteReplyMsg>;
|
200 | /**
|
201 | * Send an `inspect_request` message.
|
202 | *
|
203 | * @param content - The content of the request.
|
204 | *
|
205 | * @returns A promise that resolves with the response message.
|
206 | *
|
207 | * #### Notes
|
208 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#introspection).
|
209 | *
|
210 | * Fulfills with the `inspect_reply` content when the shell reply is
|
211 | * received and validated.
|
212 | */
|
213 | requestInspect(content: KernelMessage.IInspectRequestMsg['content']): Promise<KernelMessage.IInspectReplyMsg>;
|
214 | /**
|
215 | * Send a `history_request` message.
|
216 | *
|
217 | * @param content - The content of the request.
|
218 | *
|
219 | * @returns A promise that resolves with the response message.
|
220 | *
|
221 | * #### Notes
|
222 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#history).
|
223 | *
|
224 | * Fulfills with the `history_reply` content when the shell reply is
|
225 | * received and validated.
|
226 | */
|
227 | requestHistory(content: KernelMessage.IHistoryRequestMsg['content']): Promise<KernelMessage.IHistoryReplyMsg>;
|
228 | /**
|
229 | * Send an `execute_request` message.
|
230 | *
|
231 | * @param content - The content of the request.
|
232 | *
|
233 | * @param disposeOnDone - Whether to dispose of the future when done.
|
234 | *
|
235 | * @returns A kernel future.
|
236 | *
|
237 | * #### Notes
|
238 | * See [Messaging in
|
239 | * Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute).
|
240 | *
|
241 | * This method returns a kernel future, rather than a promise, since execution may
|
242 | * have many response messages (for example, many iopub display messages).
|
243 | *
|
244 | * Future `onReply` is called with the `execute_reply` content when the
|
245 | * shell reply is received and validated.
|
246 | *
|
247 | * **See also:** [[IExecuteReply]]
|
248 | */
|
249 | requestExecute(content: KernelMessage.IExecuteRequestMsg['content'], disposeOnDone?: boolean, metadata?: JSONObject): IShellFuture<KernelMessage.IExecuteRequestMsg, KernelMessage.IExecuteReplyMsg>;
|
250 | /**
|
251 | * Send an experimental `debug_request` message.
|
252 | *
|
253 | * @hidden
|
254 | *
|
255 | * @param content - The content of the request.
|
256 | *
|
257 | * @param disposeOnDone - Whether to dispose of the future when done.
|
258 | *
|
259 | * @returns A kernel future.
|
260 | *
|
261 | * #### Notes
|
262 | * Debug messages are experimental messages that are not in the official
|
263 | * kernel message specification. As such, this function is *NOT* considered
|
264 | * part of the public API, and may change without notice.
|
265 | */
|
266 | requestDebug(content: KernelMessage.IDebugRequestMsg['content'], disposeOnDone?: boolean): IControlFuture<KernelMessage.IDebugRequestMsg, KernelMessage.IDebugReplyMsg>;
|
267 | /**
|
268 | * Send an `is_complete_request` message.
|
269 | *
|
270 | * @param content - The content of the request.
|
271 | *
|
272 | * @returns A promise that resolves with the response message.
|
273 | *
|
274 | * #### Notes
|
275 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#code-completeness).
|
276 | *
|
277 | * Fulfills with the `is_complete_response` content when the shell reply is
|
278 | * received and validated.
|
279 | */
|
280 | requestIsComplete(content: KernelMessage.IIsCompleteRequestMsg['content']): Promise<KernelMessage.IIsCompleteReplyMsg>;
|
281 | /**
|
282 | * Send a `comm_info_request` message.
|
283 | *
|
284 | * @param content - The content of the request.
|
285 | *
|
286 | * @returns A promise that resolves with the response message.
|
287 | *
|
288 | * #### Notes
|
289 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#comm_info).
|
290 | *
|
291 | * Fulfills with the `comm_info_reply` content when the shell reply is
|
292 | * received and validated.
|
293 | */
|
294 | requestCommInfo(content: KernelMessage.ICommInfoRequestMsg['content']): Promise<KernelMessage.ICommInfoReplyMsg>;
|
295 | /**
|
296 | * Send an `input_reply` message.
|
297 | *
|
298 | * @param content - The content of the reply.
|
299 | * @param parent_header - The parent message header.
|
300 | *
|
301 | * #### Notes
|
302 | * See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#messages-on-the-stdin-router-dealer-sockets).
|
303 | * In v7.0.0, the `parent_header` argument will become mandatory.
|
304 | */
|
305 | sendInputReply(content: KernelMessage.IInputReplyMsg['content'], parent_header?: KernelMessage.IInputReplyMsg['parent_header']): void;
|
306 | /**
|
307 | * Create a new comm.
|
308 | *
|
309 | * @param targetName - The name of the comm target.
|
310 | *
|
311 | * @param id - The comm id.
|
312 | *
|
313 | * @returns A comm instance.
|
314 | */
|
315 | createComm(targetName: string, commId?: string): IComm;
|
316 | /**
|
317 | * Check if a comm exists.
|
318 | */
|
319 | hasComm(commId: string): boolean;
|
320 | /**
|
321 | * Register a comm target handler.
|
322 | *
|
323 | * @param targetName - The name of the comm target.
|
324 | *
|
325 | * @param callback - The callback invoked for a comm open message.
|
326 | *
|
327 | * #### Notes
|
328 | * Only one comm target can be registered to a target name at a time, an
|
329 | * existing callback for the same target name will be overridden. A registered
|
330 | * comm target handler will take precedence over a comm which specifies a
|
331 | * `target_module`.
|
332 | *
|
333 | * If the callback returns a promise, kernel message processing will pause
|
334 | * until the returned promise is fulfilled.
|
335 | */
|
336 | registerCommTarget(targetName: string, callback: (comm: IComm, msg: KernelMessage.ICommOpenMsg) => void | PromiseLike<void>): void;
|
337 | /**
|
338 | * Remove a comm target handler.
|
339 | *
|
340 | * @param targetName - The name of the comm target to remove.
|
341 | *
|
342 | * @param callback - The callback to remove.
|
343 | *
|
344 | * #### Notes
|
345 | * The comm target is only removed if it matches the callback argument.
|
346 | */
|
347 | removeCommTarget(targetName: string, callback: (comm: IComm, msg: KernelMessage.ICommOpenMsg) => void | PromiseLike<void>): void;
|
348 | /**
|
349 | * Register an IOPub message hook.
|
350 | *
|
351 | * @param msg_id - The parent_header message id in messages the hook should
|
352 | * intercept.
|
353 | *
|
354 | * @param hook - The callback invoked for the message.
|
355 | *
|
356 | * #### Notes
|
357 | * The IOPub hook system allows you to preempt the handlers for IOPub
|
358 | * messages with a given parent_header message id. The most recently
|
359 | * registered hook is run first. If a hook return value resolves to false,
|
360 | * any later hooks and the future's onIOPub handler will not run. If a hook
|
361 | * throws an error, the error is logged to the console and the next hook is
|
362 | * run. If a hook is registered during the hook processing, it will not run
|
363 | * until the next message. If a hook is disposed during the hook processing,
|
364 | * it will be deactivated immediately.
|
365 | *
|
366 | * See also [[IFuture.registerMessageHook]].
|
367 | */
|
368 | registerMessageHook(msgId: string, hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void;
|
369 | /**
|
370 | * Remove an IOPub message hook.
|
371 | *
|
372 | * @param msg_id - The parent_header message id the hook intercepted.
|
373 | *
|
374 | * @param hook - The callback invoked for the message.
|
375 | *
|
376 | */
|
377 | removeMessageHook(msgId: string, hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void;
|
378 | /**
|
379 | * Remove the input guard, if any.
|
380 | */
|
381 | removeInputGuard(): void;
|
382 | /**
|
383 | * A signal emitted when the kernel status changes.
|
384 | */
|
385 | statusChanged: ISignal<this, KernelMessage.Status>;
|
386 | /**
|
387 | * A signal emitted when the kernel connection status changes.
|
388 | */
|
389 | connectionStatusChanged: ISignal<this, ConnectionStatus>;
|
390 | /**
|
391 | * A signal emitted after an iopub kernel message is handled.
|
392 | */
|
393 | iopubMessage: ISignal<this, KernelMessage.IIOPubMessage>;
|
394 | /**
|
395 | * A signal emitted for unhandled non-iopub kernel messages that claimed to
|
396 | * be responses for messages we sent using this kernel object.
|
397 | */
|
398 | unhandledMessage: ISignal<this, KernelMessage.IMessage>;
|
399 | /**
|
400 | * A signal emitted when any kernel message is sent or received.
|
401 | *
|
402 | * #### Notes
|
403 | * This signal is emitted before any message handling has happened. The
|
404 | * message should be treated as read-only.
|
405 | */
|
406 | anyMessage: ISignal<this, IAnyMessageArgs>;
|
407 | /**
|
408 | * A signal emitted when a kernel has pending inputs from the user.
|
409 | */
|
410 | pendingInput: ISignal<this, boolean>;
|
411 | /**
|
412 | * The server settings for the kernel.
|
413 | */
|
414 | readonly serverSettings: ServerConnection.ISettings;
|
415 | /**
|
416 | * Shutdown a kernel.
|
417 | *
|
418 | * @returns A promise that resolves when the kernel has shut down.
|
419 | *
|
420 | * #### Notes
|
421 | * Uses the [Jupyter Notebook
|
422 | * API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels).
|
423 | *
|
424 | * On a valid response, closes the websocket, disposes of the kernel
|
425 | * object, and fulfills the promise.
|
426 | *
|
427 | * The promise will be rejected if the kernel status is `'dead'`, the
|
428 | * request fails, or the response is invalid.
|
429 | */
|
430 | shutdown(): Promise<void>;
|
431 | /**
|
432 | * Clone the current kernel with a new clientId.
|
433 | */
|
434 | clone(options?: Pick<IKernelConnection.IOptions, 'clientId' | 'username' | 'handleComms'>): IKernelConnection;
|
435 | }
|
436 | /**
|
437 | * The namespace for `IKernelConnection` statics.
|
438 | */
|
439 | export declare namespace IKernelConnection {
|
440 | /**
|
441 | * The options object used to initialize a kernel.
|
442 | */
|
443 | interface IOptions {
|
444 | /**
|
445 | * The kernel model.
|
446 | */
|
447 | model: IModel;
|
448 | /**
|
449 | * The server settings for the kernel.
|
450 | */
|
451 | serverSettings?: ServerConnection.ISettings;
|
452 | /**
|
453 | * The username of the kernel client.
|
454 | */
|
455 | username?: string;
|
456 | /**
|
457 | * Whether the kernel connection should handle comm messages
|
458 | *
|
459 | * #### Notes
|
460 | * The comm message protocol currently has implicit assumptions that only
|
461 | * one kernel connection is handling comm messages. This option allows a
|
462 | * kernel connection to opt out of handling comms.
|
463 | *
|
464 | * See https://github.com/jupyter/jupyter_client/issues/263
|
465 | */
|
466 | handleComms?: boolean;
|
467 | /**
|
468 | * The unique identifier for the kernel client.
|
469 | */
|
470 | clientId?: string;
|
471 | }
|
472 | }
|
473 | /**
|
474 | * Object which manages kernel instances for a given base url.
|
475 | *
|
476 | * #### Notes
|
477 | * The manager is responsible for maintaining the state of running kernels
|
478 | * through polling the server. Use a manager if you want to be notified of
|
479 | * changes to kernels.
|
480 | */
|
481 | export interface IManager extends IBaseManager {
|
482 | /**
|
483 | * A signal emitted when the running kernels change.
|
484 | */
|
485 | runningChanged: ISignal<IManager, IModel[]>;
|
486 | /**
|
487 | * A signal emitted when there is a server API connection failure.
|
488 | */
|
489 | connectionFailure: ISignal<IManager, ServerConnection.NetworkError>;
|
490 | /**
|
491 | * Whether the manager is ready.
|
492 | */
|
493 | readonly isReady: boolean;
|
494 | /**
|
495 | * A promise that resolves when the manager is initially ready.
|
496 | */
|
497 | readonly ready: Promise<void>;
|
498 | /**
|
499 | * Create an iterator over the known running kernels.
|
500 | *
|
501 | * @returns A new iterator over the running kernels.
|
502 | */
|
503 | running(): IIterator<IModel>;
|
504 | /**
|
505 | * Force a refresh of the running kernels.
|
506 | *
|
507 | * @returns A promise that resolves when the models are refreshed.
|
508 | *
|
509 | * #### Notes
|
510 | * This is intended to be called only in response to a user action,
|
511 | * since the manager maintains its internal state.
|
512 | */
|
513 | refreshRunning(): Promise<void>;
|
514 | /**
|
515 | * Start a new kernel.
|
516 | *
|
517 | * @param createOptions - The kernel creation options
|
518 | *
|
519 | * @param connectOptions - The kernel connection options
|
520 | *
|
521 | * @returns A promise that resolves with the kernel connection.
|
522 | *
|
523 | * #### Notes
|
524 | * The manager `serverSettings` will be always be used.
|
525 | */
|
526 | startNew(createOptions?: IKernelOptions, connectOptions?: Omit<IKernelConnection.IOptions, 'model' | 'serverSettings'>): Promise<IKernelConnection>;
|
527 | /**
|
528 | * Find a kernel by id.
|
529 | *
|
530 | * @param id - The id of the target kernel.
|
531 | *
|
532 | * @returns A promise that resolves with the kernel's model, or undefined if not found.
|
533 | */
|
534 | findById(id: string): Promise<IModel | undefined>;
|
535 | /**
|
536 | * Connect to an existing kernel.
|
537 | *
|
538 | * @param model - The model of the target kernel.
|
539 | *
|
540 | * @returns A promise that resolves with the new kernel instance.
|
541 | */
|
542 | connectTo(options: IKernelConnection.IOptions): IKernelConnection;
|
543 | /**
|
544 | * Shut down a kernel by id.
|
545 | *
|
546 | * @param id - The id of the target kernel.
|
547 | *
|
548 | * @returns A promise that resolves when the operation is complete.
|
549 | */
|
550 | shutdown(id: string): Promise<void>;
|
551 | /**
|
552 | * Shut down all kernels.
|
553 | *
|
554 | * @returns A promise that resolves when all of the kernels are shut down.
|
555 | */
|
556 | shutdownAll(): Promise<void>;
|
557 | }
|
558 | /**
|
559 | * A Future interface for responses from the kernel.
|
560 | *
|
561 | * When a message is sent to a kernel, a Future is created to handle any
|
562 | * responses that may come from the kernel.
|
563 | */
|
564 | export interface IFuture<REQUEST extends KernelMessage.IShellControlMessage, REPLY extends KernelMessage.IShellControlMessage> extends IDisposable {
|
565 | /**
|
566 | * The original outgoing message.
|
567 | */
|
568 | readonly msg: REQUEST;
|
569 | /**
|
570 | * A promise that resolves when the future is done.
|
571 | *
|
572 | * #### Notes
|
573 | * The future is done when there are no more responses expected from the
|
574 | * kernel.
|
575 | *
|
576 | * The `done` promise resolves to the reply message.
|
577 | */
|
578 | readonly done: Promise<REPLY>;
|
579 | /**
|
580 | * The reply handler for the kernel future.
|
581 | *
|
582 | * #### Notes
|
583 | * If the handler returns a promise, all kernel message processing pauses
|
584 | * until the promise is resolved. If there is a reply message, the future
|
585 | * `done` promise also resolves to the reply message after this handler has
|
586 | * been called.
|
587 | */
|
588 | onReply: (msg: REPLY) => void | PromiseLike<void>;
|
589 | /**
|
590 | * The iopub handler for the kernel future.
|
591 | *
|
592 | * #### Notes
|
593 | * If the handler returns a promise, all kernel message processing pauses
|
594 | * until the promise is resolved.
|
595 | */
|
596 | onIOPub: (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>;
|
597 | /**
|
598 | * The stdin handler for the kernel future.
|
599 | *
|
600 | * #### Notes
|
601 | * If the handler returns a promise, all kernel message processing pauses
|
602 | * until the promise is resolved.
|
603 | */
|
604 | onStdin: (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>;
|
605 | /**
|
606 | * Register hook for IOPub messages.
|
607 | *
|
608 | * @param hook - The callback invoked for an IOPub message.
|
609 | *
|
610 | * #### Notes
|
611 | * The IOPub hook system allows you to preempt the handlers for IOPub
|
612 | * messages handled by the future.
|
613 | *
|
614 | * The most recently registered hook is run first. A hook can return a
|
615 | * boolean or a promise to a boolean, in which case all kernel message
|
616 | * processing pauses until the promise is fulfilled. If a hook return value
|
617 | * resolves to false, any later hooks will not run and the function will
|
618 | * return a promise resolving to false. If a hook throws an error, the error
|
619 | * is logged to the console and the next hook is run. If a hook is
|
620 | * registered during the hook processing, it will not run until the next
|
621 | * message. If a hook is removed during the hook processing, it will be
|
622 | * deactivated immediately.
|
623 | */
|
624 | registerMessageHook(hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void;
|
625 | /**
|
626 | * Remove a hook for IOPub messages.
|
627 | *
|
628 | * @param hook - The hook to remove.
|
629 | *
|
630 | * #### Notes
|
631 | * If a hook is removed during the hook processing, it will be deactivated immediately.
|
632 | */
|
633 | removeMessageHook(hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void;
|
634 | /**
|
635 | * Send an `input_reply` message.
|
636 | */
|
637 | sendInputReply(content: KernelMessage.IInputReplyMsg['content'], parent_header?: KernelMessage.IInputReplyMsg['parent_header']): void;
|
638 | }
|
639 | export interface IShellFuture<REQUEST extends KernelMessage.IShellMessage = KernelMessage.IShellMessage, REPLY extends KernelMessage.IShellMessage = KernelMessage.IShellMessage> extends IFuture<REQUEST, REPLY> {
|
640 | }
|
641 | export interface IControlFuture<REQUEST extends KernelMessage.IControlMessage = KernelMessage.IControlMessage, REPLY extends KernelMessage.IControlMessage = KernelMessage.IControlMessage> extends IFuture<REQUEST, REPLY> {
|
642 | }
|
643 | /**
|
644 | * A client side Comm interface.
|
645 | */
|
646 | export interface IComm extends IDisposable {
|
647 | /**
|
648 | * The unique id for the comm channel.
|
649 | */
|
650 | readonly commId: string;
|
651 | /**
|
652 | * The target name for the comm channel.
|
653 | */
|
654 | readonly targetName: string;
|
655 | /**
|
656 | * Callback for a comm close event.
|
657 | *
|
658 | * #### Notes
|
659 | * This is called when the comm is closed from either the server or client.
|
660 | * If this is called in response to a kernel message and the handler returns
|
661 | * a promise, all kernel message processing pauses until the promise is
|
662 | * resolved.
|
663 | */
|
664 | onClose: (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void>;
|
665 | /**
|
666 | * Callback for a comm message received event.
|
667 | *
|
668 | * #### Notes
|
669 | * If the handler returns a promise, all kernel message processing pauses
|
670 | * until the promise is resolved.
|
671 | */
|
672 | onMsg: (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void>;
|
673 | /**
|
674 | * Open a comm with optional data and metadata.
|
675 | *
|
676 | * @param data - The data to send to the server on opening.
|
677 | *
|
678 | * @param metadata - Additional metadata for the message.
|
679 | *
|
680 | * @returns A future for the generated message.
|
681 | *
|
682 | * #### Notes
|
683 | * This sends a `comm_open` message to the server.
|
684 | */
|
685 | open(data?: JSONValue, metadata?: JSONObject, buffers?: (ArrayBuffer | ArrayBufferView)[]): IShellFuture;
|
686 | /**
|
687 | * Send a `comm_msg` message to the kernel.
|
688 | *
|
689 | * @param data - The data to send to the server on opening.
|
690 | *
|
691 | * @param metadata - Additional metadata for the message.
|
692 | *
|
693 | * @param buffers - Optional buffer data.
|
694 | *
|
695 | * @param disposeOnDone - Whether to dispose of the future when done.
|
696 | *
|
697 | * @returns A future for the generated message.
|
698 | *
|
699 | * #### Notes
|
700 | * This is a no-op if the comm has been closed.
|
701 | */
|
702 | send(data: JSONValue, metadata?: JSONObject, buffers?: (ArrayBuffer | ArrayBufferView)[], disposeOnDone?: boolean): IShellFuture;
|
703 | /**
|
704 | * Close the comm.
|
705 | *
|
706 | * @param data - The data to send to the server on opening.
|
707 | *
|
708 | * @param metadata - Additional metadata for the message.
|
709 | *
|
710 | * @returns A future for the generated message.
|
711 | *
|
712 | * #### Notes
|
713 | * This will send a `comm_close` message to the kernel, and call the
|
714 | * `onClose` callback if set.
|
715 | *
|
716 | * This is a no-op if the comm is already closed.
|
717 | */
|
718 | close(data?: JSONValue, metadata?: JSONObject, buffers?: (ArrayBuffer | ArrayBufferView)[]): IShellFuture;
|
719 | }
|
720 | /**
|
721 | * The valid kernel connection states.
|
722 | *
|
723 | * #### Notes
|
724 | * The status states are:
|
725 | * * `connected`: The kernel connection is live.
|
726 | * * `connecting`: The kernel connection is not live, but we are attempting
|
727 | * to reconnect to the kernel.
|
728 | * * `disconnected`: The kernel connection is permanently down, we will not
|
729 | * try to reconnect.
|
730 | *
|
731 | * When a kernel connection is `connected`, the kernel status should be
|
732 | * valid. When a kernel connection is either `connecting` or `disconnected`,
|
733 | * the kernel status will be `unknown` unless the kernel status was `dead`,
|
734 | * in which case it stays `dead`.
|
735 | */
|
736 | export declare type ConnectionStatus = 'connected' | 'connecting' | 'disconnected';
|
737 | /**
|
738 | * Arguments interface for the anyMessage signal.
|
739 | */
|
740 | export interface IAnyMessageArgs {
|
741 | /**
|
742 | * The message that is being signaled.
|
743 | */
|
744 | msg: Readonly<KernelMessage.IMessage>;
|
745 | /**
|
746 | * The direction of the message.
|
747 | */
|
748 | direction: 'send' | 'recv';
|
749 | }
|