<commit_before>"Support for promises. If an operation cannot return a value 
 immediately without blocking, it may instead return a 
 _promise_ of the value. A promise is an object that 
 represents the return value or the thrown exception that 
 the operation eventually produces. Such an operation is
 sometimes called a _long-running operation_.
 
 This module provides following abstractions:
 
 - The [[Completable]] interface abstracts objects which
   promise one or more values, accommodating the possibility
   of failure.
 - The [[Completion]] interface abstracts `Completable`s that may
   be combined to form a compound promise that produces 
   multiple values.
 - The [[Promise]] class, a `Completable` that produces a 
   single value, or fails.
 - The [[Deferred]] class, providing support for operations
   which return instances of the `Promise` interface.
 - The [[ExecutionContext]] class abstracts the concurrency of the runtime
   running the promises. The JVM runtime uses a threadpool, 
   the JavaScript runtime uses the `setTimeout` function. The
   [[defineGlobalExecutionContext]] can be use to change the default context
 
 ## Promises
 
 A [[Promise]] exists in one of three states:
 
 - In the _promised_ state, the operation has not yet 
   terminated.
 - In the _fulfilled_ state, the operation has produced
   a value.
 - In the _rejected_ state, the operation has terminated 
   without producing a value. This situation is represented
   as an [[exception|Throwable]].
 
 The method [[Promise.completed]] allows interested 
 parties to be notified when the promise makes a 
 transition from the _promised_ state to the _fulfilled_ or 
 the _rejected_ state:
 
     Promise<Document> promise = queryDocumentById(id);
     promise.onComplete {
         (d) => print(\"Got the document: \" + d.title);
         (e) => print(\"Document was not received: \" + e.message);
     };
 
 The first function is called the `onFulfilled` callback and 
 the second function is called the `onRejected` callback. 
 The `onRejected` function is always optional. 
 
 ## Returning promises
 
 A [[Deferred]] object is a factory that provides an 
 instance of the `Promise` class and manages its lifecycle,
 providing operations to force its transition to a 
 _fulfilled_ or _rejected_ state.
 
 The instance of `Deferred` should remain private to the 
 long-running operation, only the `Promise` should be
 exposed to the caller.

 The `Promise` of a deferred can be retrieved from its 
 [[promise|Deferred.promise]] field:
 
     value deferred = Deferred<String>();
     return deferred.promise;
 
 The `Deferred` object implements the [[Completable]] interface 
 which provides two methods for controlling the state of the 
 promise:
 
 - [[fulfill()|Completable.fulfill]] fulfills the promise with 
   a _value_, and
 - [[reject()|Completable.reject]] rejects the promise with a
   _reason_ of type [[Throwable]].
 
 For example:
 
     value deferred = Deferred<String>();
     void doOperation() {
         try {
             String val = getValue();
             deferred.fulfill(val);
         }
         catch (Throwable e) {
             deferred.reject(e);
         }
     }
 
 ## Chaining promises
 
 When composition is needed the method [[Completion.map]]
 should be used instead of the [[Completion.completed]]
 method. 
 
 When invoking the [[Completion.map]] method the 
 `onFulfilled` and `onRejected` callbacks can return a value. 
 The `compose()` method returns a new promise that will be 
 fulfilled with the value of the callback. This promise will 
 be rejected if the callback invocation fails.
 
 For example:
 
     Promise<Integer> promiseOfInteger = promiseOfInteger();
     Promise<String> promiseOfString = promiseOfInteger.compose((i) => i.string);
     promiseOfString.compose((s) => print(\"Completed with \" + s));
 
 Or, more concisely:
 
     promiseOfInteger()
         .compose((i) => i.string)
         .compose((s) => print(\"Completed with \" + s));
 
 ## Composing promises
 
 Promises can be composed into a single promise that is 
 fulfilled when every one of the individual composed 
 promises is fulfilled. If one of the promise is rejected 
 then the composed promise is rejected.
 
     Promise<String> promiseOfInteger = promiseOfString();
     Promise<Integer> promiseOfString = promiseOfInteger();
     (promiseOfInteger and promiseOfString).onCompletion {
         (i, s) => print(\"All fulfilled\");
         (e) => print(\"One failed\");
     };
 
 Notice that:
 
 - The order of the parameters in the callback is in reverse 
   order in which the corresponding promises are chained.
 - The return type of combined promise is not [[Promise]] 
   but [[Completable]].
 
 ## The `always()` method
 
 The [[onComplete()|Promise.onComplete]] method of a promise 
 allows a single callback to be notified when the promise is 
 fulfilled or rejected.
 
     Promise<Document> promise = queryDocumentById(id);
     promise.always {
         void (Document|Throwable result) {
             switch (result)
             case (Document) { print(\"Fulfilled\"); }
             case (Throwable) { print(\"Rejected\"); }
         };
      };
 
 [[Promise.onComplete]] is most useful for implementing a finally clause <commit_msg>align docs with current api<commit_after>"Support for promises. If an operation cannot return a value 
 immediately without blocking, it may instead return a 
 _promise_ of the value. A promise is an object that 
 represents the return value or the thrown exception that 
 the operation eventually produces. Such an operation is
 sometimes called a _long-running operation_.
 
 This module provides following abstractions:
 
 - The [[Completable]] interface abstracts objects which
   promise one or more values, accommodating the possibility
   of failure.
 - The [[Completion]] interface abstracts `Completable`s that may
   be combined to form a compound promise that produces 
   multiple values.
 - The [[Promise]] class, a `Completable` that produces a 
   single value, or fails.
 - The [[Deferred]] class, providing support for operations
   which return instances of the `Promise` interface.
 - The [[ExecutionContext]] class abstracts the concurrency of the runtime
   running the promises. The JVM runtime uses a threadpool, 
   the JavaScript runtime uses the `setTimeout` function. The
   [[defineGlobalExecutionContext]] can be use to change the default context
 
 ## Promises
 
 A [[Promise]] exists in one of three states:
 
 - In the _promised_ state, the operation has not yet 
   terminated.
 - In the _fulfilled_ state, the operation has produced
   a value.
 - In the _rejected_ state, the operation has terminated 
   without producing a value. This situation is represented
   as an [[exception|Throwable]].
 
 The method [[Promise.completed]] allows interested 
 parties to be notified when the promise makes a 
 transition from the _promised_ state to the _fulfilled_ or 
 the _rejected_ state:
 
     Promise<Document> promise = queryDocumentById(id);
     promise.onComplete {
         (d) => print(\"Got the document: \" + d.title);
         (e) => print(\"Document was not received: \" + e.message);
     };
 
 The first function is called the `onFulfilled` callback and 
 the second function is called the `onRejected` callback. 
 The `onRejected` function is always optional. 
 
 ## Returning promises
 
 A [[Deferred]] object is a factory that provides an 
 instance of the `Promise` class and manages its lifecycle,
 providing operations to force its transition to a 
 _fulfilled_ or _rejected_ state.
 
 The instance of `Deferred` should remain private to the 
 long-running operation, only the `Promise` should be
 exposed to the caller.

 The `Promise` of a deferred can be retrieved from its 
 [[promise|Deferred.promise]] field:
 
     value deferred = Deferred<String>();
     return deferred.promise;
 
 The `Deferred` object implements the [[Completable]] interface 
 which provides two methods for controlling the state of the 
 promise:
 
 - [[fulfill()|Completable.fulfill]] fulfills the promise with 
   a _value_, and
 - [[reject()|Completable.reject]] rejects the promise with a
   _reason_ of type [[Throwable]].
 
 For example:
 
     value deferred = Deferred<String>();
     void doOperation() {
         try {
             String val = getValue();
             deferred.fulfill(val);
         }
         catch (Throwable e) {
             deferred.reject(e);
         }
     }
 
 ## Chaining promises
 
 When composition is needed the method [[Completion.map]]
 should be used instead of the [[Completion.completed]]
 method. 
 
 When invoking the [[Completion.map]] method the 
 `onFulfilled` and `onRejected` callbacks can return a value. 
 The `compose()` method returns a new promise that will be 
 fulfilled with the value of the callback. This promise will 
 be rejected if the callback invocation fails.
 
 For example:
 
     Promise<Integer> promiseOfInteger = promiseOfInteger();
     Promise<String> promiseOfString = promiseOfInteger.compose((i) => i.string);
     promiseOfString.compose((s) => print(\"Completed with \" + s));
 
 Or, more concisely:
 
     promiseOfInteger()
         .compose((i) => i.string)
         .compose((s) => print(\"Completed with \" + s));
 
 ## Composing promises
 
 Promises can be composed into a single promise that is 
 fulfilled when every one of the individual composed 
 promises is fulfilled. If one of the promise is rejected 
 then the composed promise is rejected.
 
     Promise<String> promiseOfInteger = promiseOfString();
     Promise<Integer> promiseOfString = promiseOfInteger();
     (promiseOfInteger.and(promiseOfString)).completed {
         (i, s) => print(\"All fulfilled\");
         (e) => print(\"One failed\");
     };
 
 Notice that:
 
 - The order of the parameters in the callback is in reverse 
   order in which the corresponding promises are chained.
 - The return type of combined promise is not [[Promise]] 
   but [[Completable]].
 
 ## The `onComplete()` method
 
 The [[onComplete()|Promise.onComplete]] method of a promise 
 allows a single callback to be notified when the promise is 
 fulfilled or rejected.
 
     Promise<Document> promise = queryDocumentById(id);
     promise.onComplete {
         void (Document|Throwable result) {
             switch (result)
             case (is Document) { print(\"Fulfilled\"); }
             case (is Throwable) { print(\"Rejected\"); }
         };
      };
 
 [[Promise.onComplete]] is most useful for implementing a finally clause 
{'fraction_non_alphanumeric': 0.08234295415959253, 'fraction_numerical': 0.0, 'mean_word_length': 3.2961912479740683, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5882234', 'n_tokens_mistral': 2832, 'n_tokens_neox': 2593, 'n_words': 1196}