WIP Make kernel message handling async and in order

packages/services/src/kernel/comm.ts

@@ -51,39 +51,44 @@ class CommHandler extends DisposableDelegate implements Kernel.IComm {
    * Get the callback for a comm close event.
    *
    * #### Notes
-   * This is called when the comm is closed from either the server or
-   * client.
+   * This is called when the comm is closed from either the server or client.
    *
    * **See also:** [[ICommClose]], [[close]]
    */
-  get onClose(): (msg: KernelMessage.ICommCloseMsg) => void {
+  get onClose(): (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void> {
     return this._onClose;
   }
 
   /**
    * Set the callback for a comm close event.
    *
    * #### Notes
-   * This is called when the comm is closed from either the server or
-   * client.
+   * This is called when the comm is closed from either the server or client. If
+   * the function returns a promise, and the kernel was closed from the server,
+   * kernel message processing will pause until the returned promise is
+   * fulfilled.
    *
    * **See also:** [[close]]
    */
-  set onClose(cb: (msg: KernelMessage.ICommCloseMsg) => void) {
+  set onClose(cb: (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void>) {
     this._onClose = cb;
   }
 
   /**
    * Get the callback for a comm message received event.
    */
-  get onMsg(): (msg: KernelMessage.ICommMsgMsg) => void {
+  get onMsg(): (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void> {
     return this._onMsg;
   }
 
   /**
    * Set the callback for a comm message received event.
+   *
+   * #### Notes
+   * This is called when a comm message is received. If the function returns a
+   * promise, kernel message processing will pause until it is fulfilled.
    */
-  set onMsg(cb: (msg: KernelMessage.ICommMsgMsg) => void) {
+  set onMsg(cb: (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void>) {
     this._onMsg = cb;
   }
 
@@ -171,6 +176,8 @@ class CommHandler extends DisposableDelegate implements Kernel.IComm {
     let onClose = this._onClose;
     if (onClose) {
       let ioMsg = KernelMessage.createMessage(options, content, metadata, buffers);
+      // In the future, we may want to communicate back to the user the possible
+      // promise returned from onClose.
       onClose(ioMsg as KernelMessage.ICommCloseMsg);
     }
     this.dispose();
@@ -180,6 +187,6 @@ class CommHandler extends DisposableDelegate implements Kernel.IComm {
   private _target = '';
   private _id = '';
   private _kernel: Kernel.IKernel;
-  private _onClose: (msg: KernelMessage.ICommCloseMsg) => void;
-  private _onMsg: (msg: KernelMessage.ICommMsgMsg) => void;
+  private _onClose: (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void>;
+  private _onMsg: (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void>;
 }