mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-06 11:44:40 +00:00
Add JSDoc comments to various utility functions and core files.
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.
This commit is contained in:
@@ -1,12 +1,51 @@
|
||||
// Simple mutex implementation
|
||||
/**
|
||||
* @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();
|
||||
|
||||
lock(): PromiseLike<() => void> {
|
||||
let begin: (unlock: () => void) => void;
|
||||
/**
|
||||
* 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
|
||||
|
||||
this.mutex = this.mutex.then(() => new Promise(begin));
|
||||
const newPromise = new Promise<void>((resolve) => {
|
||||
begin = resolve;
|
||||
});
|
||||
|
||||
return new Promise((res) => (begin = res));
|
||||
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()`.
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user