/
kernel.ts
1103 lines (1002 loc) · 32.5 KB
/
kernel.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License.
import { IIterator } from '@phosphor/algorithm';
import { JSONObject, JSONValue } from '@phosphor/coreutils';
import { IDisposable } from '@phosphor/disposable';
import { ISignal } from '@phosphor/signaling';
import { ServerConnection } from '..';
import { DefaultKernel } from './default';
import { KernelMessage } from './messages';
/**
* A namespace for kernel types, interfaces, and type checker functions.
*/
export namespace Kernel {
/**
* Interface of a Kernel connection that is managed by a session.
*
* #### Notes
* The Kernel object is tied to the lifetime of the Kernel id, which is a
* unique id for the Kernel session on the server. The Kernel object manages
* a websocket connection internally, and will auto-restart if the websocket
* temporarily loses connection. Restarting creates a new Kernel process on
* the server, but preserves the Kernel id.
*/
export interface IKernelConnection extends IDisposable {
/**
* The id of the server-side kernel.
*/
readonly id: string;
/**
* The name of the server-side kernel.
*/
readonly name: string;
/**
* The model associated with the kernel.
*/
readonly model: Kernel.IModel;
/**
* The client username.
*/
readonly username: string;
/**
* The client unique id.
*
* #### Notes
* This should be unique for a particular kernel connection object.
*/
readonly clientId: string;
/**
* The current status of the kernel.
*/
readonly status: Kernel.Status;
/**
* The cached kernel info.
*
* #### Notes
* This value will be null until the kernel is ready.
*/
readonly info: KernelMessage.IInfoReply | null;
/**
* Test whether the kernel is ready.
*
* #### Notes
* A kernel is ready when the communication channel is active and we have
* cached the kernel info.
*/
readonly isReady: boolean;
/**
* A promise that resolves when the kernel is initially ready after a start
* or restart.
*
* #### Notes
* A kernel is ready when the communication channel is active and we have
* cached the kernel info.
*/
readonly ready: Promise<void>;
/**
* Whether the kernel connection handles 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
*/
handleComms: boolean;
/**
* Get the kernel spec.
*
* @returns A promise that resolves with the kernel spec for this kernel.
*/
getSpec(): Promise<Kernel.ISpecModel>;
/**
* Send a shell message to the kernel.
*
* @param msg - The fully-formed shell message to send.
*
* @param expectReply - Whether to expect a shell reply message.
*
* @param disposeOnDone - Whether to dispose of the future when done.
*
* #### 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 done when both a
* shell reply and an idle status message are received with the appropriate
* parent header, in which case the `.done` promise resolves to the reply.
* If `expectReply` is not given or is `false`, the future is done when an
* idle status message with the appropriate parent header is received, in
* which case the `.done` promise resolves to `undefined`.
*
* If `disposeOnDone` is given and `false`, the future will not be disposed
* of when the future is done, instead relying on the caller to dispose of
* it. This allows for the handling of out-of-order output from ill-behaved
* kernels.
*
* All replies are validated as valid kernel messages.
*
* If the kernel status is `'dead'`, this will throw an error.
*/
sendShellMessage<T extends KernelMessage.ShellMessageType>(
msg: KernelMessage.IShellMessage<T>,
expectReply?: boolean,
disposeOnDone?: boolean
): Kernel.IShellFuture<KernelMessage.IShellMessage<T>>;
sendControlMessage<T extends KernelMessage.ControlMessageType>(
msg: KernelMessage.IControlMessage<T>,
expectReply?: boolean,
disposeOnDone?: boolean
): Kernel.IControlFuture<KernelMessage.IControlMessage<T>>;
/**
* Reconnect to a disconnected kernel.
*
* @returns A promise that resolves when the kernel has reconnected.
*
* #### Notes
* This just refreshes the connection to an existing kernel, and does not
* perform an HTTP request to the server or restart the kernel.
*/
reconnect(): Promise<void>;
/**
* Interrupt a kernel.
*
* @returns A promise that resolves when the kernel has interrupted.
*
* #### Notes
* Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels).
*
* 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.
*/
interrupt(): Promise<void>;
/**
* Restart a kernel.
*
* @returns A promise that resolves when the kernel has restarted.
*
* #### Notes
* 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.
*
* Any existing Future or Comm objects are cleared.
*
* 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.
*/
restart(): Promise<void>;
/**
* Send a `kernel_info_request` message.
*
* @param content - The content of the request.
*
* @returns A promise that resolves with the response message.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-info).
*
* Fulfills with the `kernel_info_response` content when the shell reply is
* received and validated.
*/
requestKernelInfo(): Promise<KernelMessage.IInfoReplyMsg>;
/**
* Send a `complete_request` message.
*
* @param content - The content of the request.
*
* @returns A promise that resolves with the response message.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#completion).
*
* Fulfills with the `complete_reply` content when the shell reply is
* received and validated.
*/
requestComplete(
content: KernelMessage.ICompleteRequestMsg['content']
): Promise<KernelMessage.ICompleteReplyMsg>;
/**
* Send an `inspect_request` message.
*
* @param content - The content of the request.
*
* @returns A promise that resolves with the response message.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#introspection).
*
* Fulfills with the `inspect_reply` content when the shell reply is
* received and validated.
*/
requestInspect(
content: KernelMessage.IInspectRequestMsg['content']
): Promise<KernelMessage.IInspectReplyMsg>;
/**
* Send a `history_request` message.
*
* @param content - The content of the request.
*
* @returns A promise that resolves with the response message.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#history).
*
* Fulfills with the `history_reply` content when the shell reply is
* received and validated.
*/
requestHistory(
content: KernelMessage.IHistoryRequestMsg['content']
): Promise<KernelMessage.IHistoryReplyMsg>;
/**
* Send an `execute_request` message.
*
* @param content - The content of the request.
*
* @param disposeOnDone - Whether to dispose of the future when done.
*
* @returns A kernel future.
*
* #### Notes
* See [Messaging in
* Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute).
*
* This method returns a kernel future, rather than a promise, since execution may
* have many response messages (for example, many iopub display messages).
*
* Future `onReply` is called with the `execute_reply` content when the
* shell reply is received and validated.
*
* **See also:** [[IExecuteReply]]
*/
requestExecute(
content: KernelMessage.IExecuteRequestMsg['content'],
disposeOnDone?: boolean,
metadata?: JSONObject
): Kernel.IShellFuture<
KernelMessage.IExecuteRequestMsg,
KernelMessage.IExecuteReplyMsg
>;
/**
* Send an experimental `debug_request` message.
*
* @hidden
*
* @param content - The content of the request.
*
* @param disposeOnDone - Whether to dispose of the future when done.
*
* @returns A kernel future.
*
* #### Notes
* Debug messages are experimental messages that are not in the official
* kernel message specification. As such, this function is *NOT* considered
* part of the public API, and may change without notice.
*/
requestDebug(
content: KernelMessage.IDebugRequestMsg['content'],
disposeOnDone?: boolean
): Kernel.IControlFuture<
KernelMessage.IDebugRequestMsg,
KernelMessage.IDebugReplyMsg
>;
/**
* Send an `is_complete_request` message.
*
* @param content - The content of the request.
*
* @returns A promise that resolves with the response message.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#code-completeness).
*
* Fulfills with the `is_complete_response` content when the shell reply is
* received and validated.
*/
requestIsComplete(
content: KernelMessage.IIsCompleteRequestMsg['content']
): Promise<KernelMessage.IIsCompleteReplyMsg>;
/**
* Send a `comm_info_request` message.
*
* @param content - The content of the request.
*
* @returns A promise that resolves with the response message.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#comm_info).
*
* Fulfills with the `comm_info_reply` content when the shell reply is
* received and validated.
*/
requestCommInfo(
content: KernelMessage.ICommInfoRequestMsg['content']
): Promise<KernelMessage.ICommInfoReplyMsg>;
/**
* Send an `input_reply` message.
*
* @param content - The content of the reply.
*
* #### Notes
* See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#messages-on-the-stdin-router-dealer-sockets).
*/
sendInputReply(content: KernelMessage.IInputReplyMsg['content']): void;
/**
* Connect to a comm, or create a new one.
*
* @param targetName - The name of the comm target.
*
* @param id - The comm id.
*
* @returns A comm instance.
*/
connectToComm(targetName: string, commId?: string): Kernel.IComm;
/**
* Register a comm target handler.
*
* @param targetName - The name of the comm target.
*
* @param callback - The callback invoked for a comm open message.
*
* #### 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.
*/
registerCommTarget(
targetName: string,
callback: (
comm: Kernel.IComm,
msg: KernelMessage.ICommOpenMsg
) => void | PromiseLike<void>
): void;
/**
* Remove a comm target handler.
*
* @param targetName - The name of the comm target to remove.
*
* @param callback - The callback to remove.
*
* #### Notes
* The comm target is only removed if it matches the callback argument.
*/
removeCommTarget(
targetName: string,
callback: (
comm: Kernel.IComm,
msg: KernelMessage.ICommOpenMsg
) => void | PromiseLike<void>
): void;
/**
* Register an IOPub message hook.
*
* @param msg_id - The parent_header message id in messages the hook should
* intercept.
*
* @param hook - The callback invoked for the message.
*
* #### Notes
* The IOPub hook system allows you to preempt the handlers for IOPub
* messages with a given parent_header message id. The most recently
* registered hook is run first. If a hook return value resolves to false,
* any later hooks and the future's onIOPub handler will not run. 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 disposed during the hook processing,
* it will be deactivated immediately.
*
* See also [[IFuture.registerMessageHook]].
*/
registerMessageHook(
msgId: string,
hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
): void;
/**
* Remove an IOPub message hook.
*
* @param msg_id - The parent_header message id the hook intercepted.
*
* @param hook - The callback invoked for the message.
*
*/
removeMessageHook(
msgId: string,
hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
): void;
}
/**
* The full interface of a kernel.
*/
export interface IKernel extends IKernelConnection {
/**
* A signal emitted when the kernel is shut down.
*/
terminated: ISignal<this, void>;
/**
* A signal emitted when the kernel status changes.
*/
statusChanged: ISignal<this, Kernel.Status>;
/**
* A signal emitted after an iopub kernel message is handled.
*/
iopubMessage: ISignal<this, KernelMessage.IIOPubMessage>;
/**
* A signal emitted for unhandled non-iopub kernel messages that claimed to
* be responses for messages we sent using this kernel object.
*/
unhandledMessage: ISignal<this, KernelMessage.IMessage>;
/**
* A signal emitted when any kernel message is sent or received.
*
* #### Notes
* This signal is emitted before any message handling has happened. The
* message should be treated as read-only.
*/
anyMessage: ISignal<this, IAnyMessageArgs>;
/**
* The server settings for the kernel.
*/
readonly serverSettings: ServerConnection.ISettings;
/**
* Shutdown a kernel.
*
* @returns A promise that resolves when the kernel has shut down.
*
* #### Notes
* Uses the [Jupyter Notebook
* API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels).
*
* On a valid response, closes the websocket, emits the [[terminated]]
* signal, disposes of the kernel object, and fulfills the promise.
*
* The promise will be rejected if the kernel status is `'dead'`, the
* request fails, or the response is invalid.
*/
shutdown(): Promise<void>;
}
/**
* Find a kernel by id.
*
* @param id - The id of the kernel of interest.
*
* @param settings - The optional server settings.
*
* @returns A promise that resolves with the model for the kernel.
*
* #### Notes
* If the kernel was already started via `startNewKernel`, we return its
* `Kernel.IModel`. Otherwise, we attempt to find the existing kernel. The
* promise is fulfilled when the kernel is found, otherwise the promise is
* rejected.
*/
export function findById(
id: string,
settings?: ServerConnection.ISettings
): Promise<IModel> {
return DefaultKernel.findById(id, settings);
}
/**
* Fetch all of the kernel specs.
*
* @param settings - The optional server settings.
*
* @returns A promise that resolves with the kernel specs.
*
* #### Notes
* Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernelspecs).
*/
export function getSpecs(
settings?: ServerConnection.ISettings
): Promise<Kernel.ISpecModels> {
return DefaultKernel.getSpecs(settings);
}
/**
* Fetch the running kernels.
*
* @param settings - The optional server settings.
*
* @returns A promise that resolves with the list of running kernels.
*
* #### Notes
* 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.
*
* The promise is fulfilled on a valid response and rejected otherwise.
*/
export function listRunning(
settings?: ServerConnection.ISettings
): Promise<Kernel.IModel[]> {
return DefaultKernel.listRunning(settings);
}
/**
* Start a new kernel.
*
* @param options - The options used to create the kernel.
*
* @returns A promise that resolves with a kernel object.
*
* #### Notes
* 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.
*
* If no options are given or the kernel name is not given, the
* default kernel will by started by the server.
*
* Wraps the result in a Kernel object. The promise is fulfilled
* when the kernel is started by the server, otherwise the promise is rejected.
*/
export function startNew(options: Kernel.IOptions = {}): Promise<IKernel> {
return DefaultKernel.startNew(options);
}
/**
* Connect to a running kernel.
*
* @param model - The model of the running kernel.
*
* @param settings - The server settings for the request.
*
* @returns The kernel object.
*
* #### Notes
* If the kernel was already started via `startNewKernel`, the existing
* Kernel object info is used to create another instance.
*/
export function connectTo(
model: Kernel.IModel,
settings?: ServerConnection.ISettings
): IKernel {
return DefaultKernel.connectTo(model, settings);
}
/**
* Shut down a kernel by id.
*
* @param id - The id of the running kernel.
*
* @param settings - The server settings for the request.
*
* @returns A promise that resolves when the kernel is shut down.
*/
export function shutdown(
id: string,
settings?: ServerConnection.ISettings
): Promise<void> {
return DefaultKernel.shutdown(id, settings);
}
/**
* Shut down all kernels.
*
* @returns A promise that resolves when all of the kernels are shut down.
*/
export function shutdownAll(
settings?: ServerConnection.ISettings
): Promise<void> {
return DefaultKernel.shutdownAll(settings);
}
/**
* The options object used to initialize a kernel.
*/
export interface IOptions {
/**
* The kernel type (e.g. python3).
*/
name?: string;
/**
* The server settings for the kernel.
*/
serverSettings?: ServerConnection.ISettings;
/**
* The username of the kernel client.
*/
username?: string;
/**
* Whether the kernel connection should 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
*/
handleComms?: boolean;
/**
* The unique identifier for the kernel client.
*/
clientId?: string;
}
/**
* Object which manages kernel instances for a given base url.
*
* #### Notes
* The manager is responsible for maintaining the state of running
* kernels and the initial fetch of kernel specs.
*/
export interface IManager extends IDisposable {
/**
* A signal emitted when the kernel specs change.
*/
specsChanged: ISignal<IManager, ISpecModels>;
/**
* A signal emitted when the running kernels change.
*/
runningChanged: ISignal<IManager, IModel[]>;
/**
* A signal emitted when there is a connection failure.
*/
connectionFailure: ISignal<IManager, ServerConnection.NetworkError>;
/**
* The server settings for the manager.
*/
serverSettings?: ServerConnection.ISettings;
/**
* The kernel spec models.
*
* #### Notes
* The value will be null until the manager is ready.
*/
readonly specs: Kernel.ISpecModels | null;
/**
* Whether the manager is ready.
*/
readonly isReady: boolean;
/**
* A promise that resolves when the manager is initially ready.
*/
readonly ready: Promise<void>;
/**
* Create an iterator over the known running kernels.
*
* @returns A new iterator over the running kernels.
*/
running(): IIterator<IModel>;
/**
* Force a refresh of the specs from the server.
*
* @returns A promise that resolves when the specs are fetched.
*
* #### Notes
* This is intended to be called only in response to a user action,
* since the manager maintains its internal state.
*/
refreshSpecs(): Promise<void>;
/**
* Force a refresh of the running kernels.
*
* @returns A promise that resolves when the models are refreshed.
*
* #### Notes
* This is intended to be called only in response to a user action,
* since the manager maintains its internal state.
*/
refreshRunning(): Promise<void>;
/**
* Start a new kernel.
*
* @param options - The kernel options to use.
*
* @returns A promise that resolves with the kernel instance.
*
* #### Notes
* The manager `serverSettings` will be always be used.
*/
startNew(options?: IOptions): Promise<IKernel>;
/**
* Find a kernel by id.
*
* @param id - The id of the target kernel.
*
* @returns A promise that resolves with the kernel's model.
*/
findById(id: string): Promise<IModel>;
/**
* Connect to an existing kernel.
*
* @param model - The model of the target kernel.
*
* @returns A promise that resolves with the new kernel instance.
*/
connectTo(model: Kernel.IModel): IKernel;
/**
* Shut down a kernel by id.
*
* @param id - The id of the target kernel.
*
* @returns A promise that resolves when the operation is complete.
*/
shutdown(id: string): Promise<void>;
/**
* Shut down all kernels.
*
* @returns A promise that resolves when all of the kernels are shut down.
*/
shutdownAll(): Promise<void>;
}
/**
* A Future interface for responses from the kernel.
*
* When a message is sent to a kernel, a Future is created to handle any
* responses that may come from the kernel.
*/
export interface IFuture<
REQUEST extends KernelMessage.IShellControlMessage,
REPLY extends KernelMessage.IShellControlMessage
> extends IDisposable {
/**
* The original outgoing message.
*/
readonly msg: REQUEST;
/**
* A promise that resolves when the future is done.
*
* #### Notes
* The future is done when there are no more responses expected from the
* kernel.
*
* The `done` promise resolves to the reply message if there is one,
* otherwise it resolves to `undefined`.
*/
readonly done: Promise<REPLY | undefined>;
/**
* The reply handler for the kernel future.
*
* #### Notes
* If the handler returns a promise, all kernel message processing pauses
* until the promise is resolved. If there is a reply message, the future
* `done` promise also resolves to the reply message after this handler has
* been called.
*/
onReply: (msg: REPLY) => void | PromiseLike<void>;
/**
* The iopub handler for the kernel future.
*
* #### Notes
* If the handler returns a promise, all kernel message processing pauses
* until the promise is resolved.
*/
onIOPub: (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>;
/**
* The stdin handler for the kernel future.
*
* #### Notes
* If the handler returns a promise, all kernel message processing pauses
* until the promise is resolved.
*/
onStdin: (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>;
/**
* Register hook for IOPub messages.
*
* @param hook - The callback invoked for an IOPub message.
*
* #### Notes
* The IOPub hook system allows you to preempt the handlers for IOPub
* messages handled by the future.
*
* 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.
*/
registerMessageHook(
hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
): void;
/**
* Remove a hook for IOPub messages.
*
* @param hook - The hook to remove.
*
* #### Notes
* If a hook is removed during the hook processing, it will be deactivated immediately.
*/
removeMessageHook(
hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
): void;
/**
* Send an `input_reply` message.
*/
sendInputReply(content: KernelMessage.IInputReplyMsg['content']): void;
}
export interface IShellFuture<
REQUEST extends KernelMessage.IShellMessage = KernelMessage.IShellMessage,
REPLY extends KernelMessage.IShellMessage = KernelMessage.IShellMessage
> extends IFuture<REQUEST, REPLY> {}
export interface IControlFuture<
REQUEST extends KernelMessage.IControlMessage = KernelMessage.IControlMessage,
REPLY extends KernelMessage.IControlMessage = KernelMessage.IControlMessage
> extends IFuture<REQUEST, REPLY> {}
/**
* A client side Comm interface.
*/
export interface IComm extends IDisposable {
/**
* The unique id for the comm channel.
*/
readonly commId: string;
/**
* The target name for the comm channel.
*/
readonly targetName: string;
/**
* Callback for a comm close event.
*
* #### Notes
* This is called when the comm is closed from either the server or client.
* If this is called in response to a kernel message and the handler returns
* a promise, all kernel message processing pauses until the promise is
* resolved.
*/
onClose: (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void>;
/**
* Callback for a comm message received event.
*
* #### Notes
* If the handler returns a promise, all kernel message processing pauses
* until the promise is resolved.
*/
onMsg: (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void>;
/**
* Open a comm with optional data and metadata.
*
* @param data - The data to send to the server on opening.
*
* @param metadata - Additional metatada for the message.
*
* @returns A future for the generated message.
*
* #### Notes
* This sends a `comm_open` message to the server.
*/
open(
data?: JSONValue,
metadata?: JSONObject,
buffers?: (ArrayBuffer | ArrayBufferView)[]
): IShellFuture;
/**
* Send a `comm_msg` message to the kernel.
*
* @param data - The data to send to the server on opening.
*
* @param metadata - Additional metatada for the message.
*
* @param buffers - Optional buffer data.
*
* @param disposeOnDone - Whether to dispose of the future when done.
*
* @returns A future for the generated message.
*
* #### Notes
* This is a no-op if the comm has been closed.
*/
send(
data: JSONValue,
metadata?: JSONObject,
buffers?: (ArrayBuffer | ArrayBufferView)[],
disposeOnDone?: boolean
): IShellFuture;
/**
* Close the comm.
*
* @param data - The data to send to the server on opening.
*
* @param metadata - Additional metatada for the message.
*
* @returns A future for the generated message.
*
* #### Notes
* This will send a `comm_close` message to the kernel, and call the
* `onClose` callback if set.
*
* This is a no-op if the comm is already closed.
*/
close(
data?: JSONValue,
metadata?: JSONObject,
buffers?: (ArrayBuffer | ArrayBufferView)[]
): IShellFuture;
}
/**
* The valid Kernel status states.
*/
export type Status =
| 'unknown'