From 779c1f66cc25cb04ee7ecb5a91124e52446d4d32 Mon Sep 17 00:00:00 2001
From: karishmas6 <carishmashukla28@gmail.com>
Date: Wed, 12 Jun 2024 20:09:18 +0530
Subject: [PATCH] docs: concurrency

---
 mx-interpreter/utils/concurrency.ts | 44 +++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/mx-interpreter/utils/concurrency.ts b/mx-interpreter/utils/concurrency.ts
index 78ebdf39..06ca8a64 100644
--- a/mx-interpreter/utils/concurrency.ts
+++ b/mx-interpreter/utils/concurrency.ts
@@ -1,23 +1,38 @@
-
+/**
+ * Concurrency class for running concurrent tasks while managing a limited amount of resources.
+ */
 export default class Concurrency {
-  
+    /**
+       * Maximum number of workers running in parallel. If set to `null`, there is no limit.
+       */
     maxConcurrency : number = 1;
   
-    
+    /**
+       * Number of currently active workers.
+       */
     activeWorkers : number = 0;
   
-    
+    /**
+       * Queue of jobs waiting to be completed.
+       */
     private jobQueue : Function[] = [];
   
-   
+    /**
+       * "Resolve" callbacks of the waitForCompletion() promises.
+       */
     private waiting : Function[] = [];
   
-  
+    /**
+       * Constructs a new instance of concurrency manager.
+       * @param {number} maxConcurrency Maximum number of workers running in parallel.
+       */
     constructor(maxConcurrency: number) {
       this.maxConcurrency = maxConcurrency;
     }
   
-   
+    /**
+       * Takes a waiting job out of the queue and runs it.
+       */
     private runNextJob() : void {
       const job = this.jobQueue.pop();
   
@@ -37,7 +52,13 @@ export default class Concurrency {
       }
     }
   
-   
+    /**
+       * Pass a job (a time-demanding async function) to the concurrency manager. \
+       * The time of the job's execution depends on the concurrency manager itself
+       * (given a generous enough `maxConcurrency` value, it might be immediate,
+       * but this is not guaranteed).
+       * @param worker Async function to be executed (job to be processed).
+       */
     addJob(job: () => Promise<any>) : void {
       // console.debug("Adding a worker!");
       this.jobQueue.push(job);
@@ -50,7 +71,12 @@ export default class Concurrency {
       }
     }
   
-   
+    /**
+       * Waits until there is no running nor waiting job. \
+       * If the concurrency manager is idle at the time of calling this function,
+       * it waits until at least one job is compeleted (can be "presubscribed").
+       * @returns Promise, resolved after there is no running/waiting worker.
+       */
     waitForCompletion() : Promise<void> {
       return new Promise((res) => {
         this.waiting.push(res);