mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-06 03:34:40 +00:00
google-labs-jules[bot]
074e73b0fd
This change adds JSDoc-style comments to several functions and classes across the codebase to improve readability and maintainability. Comments were added to: - `src/SEQTA.ts`: Explained the `init()` function. - `src/seqta/utils/waitForElm.ts`: Detailed the `waitForElm()` function, its parameters, and behavior. - `src/seqta/utils/stringToHTML.ts`: Clarified the `stringToHTML()` function, including its sanitization and styling features. - `src/seqta/utils/delay.ts`: Added a brief explanation for the `delay()` utility. - `src/seqta/utils/mutex.ts`: Documented the `Mutex` class and its `acquire` method (renamed from `lock`), explaining its asynchronous locking mechanism and the role of the returned unlock function.
52 lines
1.7 KiB
TypeScript
52 lines
1.7 KiB
TypeScript
/**
|
|
* @callback UnlockFunction
|
|
* @description A function that must be called to release the mutex.
|
|
* @returns {void}
|
|
*/
|
|
|
|
/**
|
|
* A simple mutex implementation for managing asynchronous operations.
|
|
* It ensures that only one operation can hold the lock at a time.
|
|
* Operations queue up and are granted access sequentially.
|
|
*/
|
|
export class Mutex {
|
|
private mutex = Promise.resolve();
|
|
|
|
/**
|
|
* Acquires the mutex.
|
|
*
|
|
* This method returns a Promise that resolves with an {@link UnlockFunction}.
|
|
* The calling code *must* call this {@link UnlockFunction} to release the mutex
|
|
* once the critical section of code has completed.
|
|
*
|
|
* If the mutex is already locked, this method will wait until it is released
|
|
* before resolving the Promise.
|
|
*
|
|
* @returns {Promise<UnlockFunction>} A Promise that resolves with the function to call to release the lock.
|
|
*/
|
|
acquire(): Promise<() => void> {
|
|
let begin: (unlock: () => void) => void = () => {}; // Initialize with a no-op
|
|
|
|
const newPromise = new Promise<void>((resolve) => {
|
|
begin = resolve;
|
|
});
|
|
|
|
const chainedPromise = this.mutex.then(() => {
|
|
return new Promise<() => void>((resolveOuter) => {
|
|
// The 'begin' function, when called, will resolve the newPromise,
|
|
// effectively passing control to the next then() in the chain.
|
|
// We pass 'begin' itself as the unlock function.
|
|
// So, when the user calls unlock (which is 'begin'), newPromise resolves.
|
|
resolveOuter(begin);
|
|
});
|
|
});
|
|
|
|
this.mutex = newPromise;
|
|
|
|
return chainedPromise;
|
|
}
|
|
|
|
// Note: There isn't a separate `release()` method in this pattern.
|
|
// The lock is released by calling the function returned by `acquire()`.
|
|
}
|