|
| 1 | +# Interrupting Async Execution |
| 2 | + |
| 3 | +This document describes how we handle interrupting asynchronous execution of user input |
| 4 | +when the user hits `CTRL-C`. |
| 5 | + |
| 6 | +## Background |
| 7 | +The Node.js REPL only handles interrupting synchronous code execution. Once the execution |
| 8 | +becomes asynchronous however, e.g. when using promises or timeouts, the standard interrupt |
| 9 | +handling does not work anymore. |
| 10 | + |
| 11 | +The following is an example of synchronous code: |
| 12 | +```javascript |
| 13 | +while(true) {} |
| 14 | +``` |
| 15 | +Hitting `CTRL-C` while the infinite loop is running will immediately terminate execution. |
| 16 | + |
| 17 | +Taking a look at an example of asynchronous code using the Shell API: |
| 18 | +```javascript |
| 19 | +for (let i = 0; i < 10; i++) { |
| 20 | + db.coll.insert({ num: i }); |
| 21 | +} |
| 22 | +``` |
| 23 | +This would basically be transformed by the `async-rewriter` to something similar to: |
| 24 | +```javascript |
| 25 | +(async() => { |
| 26 | + for (let i = 0; i < 10; i++) { |
| 27 | + await db.coll.insert({ num: i }); |
| 28 | + } |
| 29 | +}); |
| 30 | +``` |
| 31 | +As such, once the first insertion of a new document would take place, the code execution becomes |
| 32 | +asynchronous. Hitting `CTRL-C` in the Node.js REPL would then not stop the code from running. |
| 33 | + |
| 34 | +## Problems to keep in mind |
| 35 | +There are a couple of things we need to keep in mind when interrupting user code execution: |
| 36 | + |
| 37 | +1. To force termination of any running operations on the server side, the connections opened |
| 38 | + by the driver have to be closed. This however only works for MongoDB >4.2. |
| 39 | +2. User code may contain `try-catch-finally` blocks so we need to make sure that the error thrown |
| 40 | + when terminating a connection is not just caught and execution silently continues. |
| 41 | +3. We need to take care of code that does not use the driver, e.g. `while (true) { print('hey'); sleep(500); }`. |
| 42 | + The goal is to also immediately interrupt this code and make sure it does not continue in the background. |
| 43 | + |
| 44 | +## Enforcing Interruption |
| 45 | +Before diving into how we enforce interruption of asynchronous code, we recommend reading the topic |
| 46 | +on [CLI code evaluation](./cli-code-evaluation.md) to get a rough understanding of control flow. |
| 47 | + |
| 48 | +The following image contains the main aspects of code evaluation control flow but is augmented with |
| 49 | +additional information on the interrupt handling. |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +### Code Evaluation |
| 54 | +As you see in the image, the original `REPLServer.eval` evaluation will finish with an exception as triggered |
| 55 | +by the _Interruptor_ described below. |
| 56 | +This exception is caught inside `MongoshNodeRepl.eval` which will detect the interrupt. As such, this method |
| 57 | +will just return an "empty" result to return this call chain. It will also emit the `mongosh:eval-interrupted` |
| 58 | +event. |
| 59 | +Note that at this point, printing the prompt is explicitly suppressed. |
| 60 | + |
| 61 | +To ensure that user code is indeed interrupted while asynchronous code is being executed, we leverage TypeScript |
| 62 | +decorators to wrap every Shell API function. |
| 63 | + |
| 64 | +The pseudo-code wrapping to include interrupt support for the `Collection.find` API function would be similar to: |
| 65 | +```javascript |
| 66 | +const interruptPromise = interruptor.checkInterrupt(); // will throw immediately if CTRL-C already happened |
| 67 | + // otherwise the contained promise is rejected on CTRL-C |
| 68 | + |
| 69 | +try { |
| 70 | + return result = Promise.race([ |
| 71 | + interruptPromise.promise(), // this is never resolved but only rejected on CTRL-C! |
| 72 | + Collection.find(args) // here we call the original function |
| 73 | + ]); |
| 74 | +} catch { |
| 75 | + ... // throw an appropriate error (see below for exception handling details) |
| 76 | +} finally { |
| 77 | + interruptPromise.destroy(); // we make sure to de-register ourselves to not leak memory |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +By having this race of promises, we ensure that code calling API functions will always fail immediately when |
| 82 | +the interruptor is triggered. This will solve problem 3 outlined above. |
| 83 | + |
| 84 | +### `SIGINT` handling |
| 85 | +`MongoshNodeRepl.onAsyncSigint` is registered as a `SIGINT` listener while code is being executed. |
| 86 | +The `SIGINT` listener will be called _first_ as seen in the image above by number _11_. |
| 87 | + |
| 88 | +The control flow of the listener is outlined in the following image. |
| 89 | + |
| 90 | + |
| 91 | + |
| 92 | +Force-closing all `MongoClient` instances as seen in the image will cause operations running on the server |
| 93 | +to be immediately terminated and thus solve problem 1 outlined above. |
| 94 | + |
| 95 | +### Uncatchable Errors |
| 96 | +One of the aforementioned problems is that user code might include `try-catch` blocks which could interfere |
| 97 | +with errors thrown by our interrupt handling code, explicitly the error thrown by the `interruptPromise` |
| 98 | +which is an instance of [`MongoshInterruptedError`](../packages/shell-api/src/interruptor.ts). |
| 99 | + |
| 100 | +In order to prevent user code from catching the _Interrupted Error_ we make use of the `async-rewriter`. |
| 101 | +The `async-rewriter` will rewrite any `try-catch` blocks it finds to make sure a `MongoshInterruptedError` |
| 102 | +is immediately re-thrown (see [`uncatchable-exceptions.ts`](../packages/async-rewriter2/src/stages/uncatchable-exceptions.ts)). |
| 103 | + |
| 104 | +For example let us look at the following user code: |
| 105 | +```javascript |
| 106 | +try { |
| 107 | + return await db.coll.count(); |
| 108 | +} catch (e) { |
| 109 | + return -1; |
| 110 | +} finally { |
| 111 | + print('completed'); |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +This code would be translated (roughly) to the following: |
| 116 | +```javascript |
| 117 | +let isCatchable; |
| 118 | +try { |
| 119 | + return await db.coll.count(); |
| 120 | +} catch (e) { |
| 121 | + isCatchable = isCatchableError(e); // basically make sure e != MongoshInterruptedError |
| 122 | + if (!isCatchable) { // we immediately re-throw our uncatchable error |
| 123 | + throw e; |
| 124 | + } |
| 125 | + return -1; |
| 126 | +} finally { |
| 127 | + if (isCatchable) { // make sure the user's finalizer only runs if the error was catchable |
| 128 | + print('completed'); |
| 129 | + } |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +This approach makes sure that problem 2 from above is properly dealt with. |
0 commit comments