1 | /**
|
2 | * @private For internal Amplify use.
|
3 | *
|
4 | * Creates a new scope for promises, observables, and other types of work or
|
5 | * processes that may be running in the background. This manager provides
|
6 | * an singular entrypoint to request termination and await completion.
|
7 | *
|
8 | * As work completes on its own prior to close, the manager removes them
|
9 | * from the registry to avoid holding references to completed jobs.
|
10 | */
|
11 | export declare class BackgroundProcessManager {
|
12 | /**
|
13 | * A string indicating whether the manager is accepting new work ("Open"),
|
14 | * waiting for work to complete ("Closing"), or fully done with all
|
15 | * submitted work and *not* accepting new jobs ("Closed").
|
16 | */
|
17 | private _state;
|
18 | private _closingPromise;
|
19 | /**
|
20 | * The list of outstanding jobs we'll need to wait for upon `close()`
|
21 | */
|
22 | private jobs;
|
23 | /**
|
24 | * Creates a new manager for promises, observables, and other types
|
25 | * of work that may be running in the background. This manager provides
|
26 | * a centralized mechanism to request termination and await completion.
|
27 | */
|
28 | constructor();
|
29 | /**
|
30 | * Executes an async `job` function, passing the return value through to
|
31 | * the caller, registering it as a running job in the manager. When the
|
32 | * manager *closes*, it will `await` the job.
|
33 | *
|
34 | * @param job The function to execute.
|
35 | * @param description Optional description to help identify pending jobs.
|
36 | * @returns The return value from the given function.
|
37 | */
|
38 | add<T>(job: () => Promise<T>, description?: string): Promise<T>;
|
39 | /**
|
40 | * Executes an async `job` function, passing the return value through to
|
41 | * the caller, registering it as a running job in the manager. When the
|
42 | * manager *closes*, it will request termination by resolving the
|
43 | * provided `onTerminate` promise. It will then `await` the job, so it is
|
44 | * important that the job still `resolve()` or `reject()` when responding
|
45 | * to a termination request.
|
46 | *
|
47 | * @param job The function to execute.
|
48 | * @param description Optional description to help identify pending jobs.
|
49 | * @returns The return value from the given function.
|
50 | */
|
51 | add<T>(job: (onTerminate: Promise<void>) => Promise<T>, description?: string): Promise<T>;
|
52 | /**
|
53 | * Create a no-op job, registers it with the manager, and returns hooks
|
54 | * to the caller to signal the job's completion and respond to termination
|
55 | * requests.
|
56 | *
|
57 | * When the manager closes, the no-op job will be `await`-ed, so its
|
58 | * important to always `resolve()` or `reject()` when done responding to an
|
59 | * `onTerminate` signal.
|
60 | * @param description Optional description to help identify pending jobs.
|
61 | * @returns Job promise hooks + onTerminate signaling promise
|
62 | */
|
63 | add(description?: string): {
|
64 | resolve: (value?: unknown) => void;
|
65 | reject: (reason?: any) => void;
|
66 | onTerminate: Promise<void>;
|
67 | };
|
68 | /**
|
69 | * Adds another job manager to await on at the time of closing. the inner
|
70 | * manager's termination is signaled when this manager's `close()` is
|
71 | * called for.
|
72 | *
|
73 | * @param job The inner job manager to await.
|
74 | * @param description Optional description to help identify pending jobs.
|
75 | */
|
76 | add(job: BackgroundProcessManager, description?: string): any;
|
77 | /**
|
78 | * Adds a **cleaner** function that doesn't immediately get executed.
|
79 | * Instead, the caller gets a **terminate** function back. The *cleaner* is
|
80 | * invoked only once the mananger *closes* or the returned **terminate**
|
81 | * function is called.
|
82 | *
|
83 | * @param clean The cleanup function.
|
84 | * @param description Optional description to help identify pending jobs.
|
85 | * @returns A terminate function.
|
86 | */
|
87 | addCleaner<T>(clean: () => Promise<T>, description?: string): () => Promise<void>;
|
88 | private addFunction;
|
89 | private addManager;
|
90 | /**
|
91 | * Creates and registers a fabricated job for processes that need to operate
|
92 | * with callbacks/hooks. The returned `resolve` and `reject`
|
93 | * functions can be used to signal the job is done successfully or not.
|
94 | * The returned `onTerminate` is a promise that will resolve when the
|
95 | * manager is requesting the termination of the job.
|
96 | *
|
97 | * @param description Optional description to help identify pending jobs.
|
98 | * @returns `{ resolve, reject, onTerminate }`
|
99 | */
|
100 | private addHook;
|
101 | /**
|
102 | * Adds a Promise based job to the list of jobs for monitoring and listens
|
103 | * for either a success or failure, upon which the job is considered "done"
|
104 | * and removed from the registry.
|
105 | *
|
106 | * @param promise A promise that is on its way to being returned to a
|
107 | * caller, which needs to be tracked as a background job.
|
108 | * @param terminate The termination function to register, which can be
|
109 | * invoked to request the job stop.
|
110 | * @param description Optional description to help identify pending jobs.
|
111 | */
|
112 | private registerPromise;
|
113 | /**
|
114 | * The number of jobs being waited on.
|
115 | *
|
116 | * We don't use this for anything. It's just informational for the caller,
|
117 | * and can be used in logging and testing.
|
118 | *
|
119 | * @returns the number of jobs.
|
120 | */
|
121 | get length(): number;
|
122 | /**
|
123 | * The execution state of the manager. One of:
|
124 | *
|
125 | * 1. "Open" -> Accepting new jobs
|
126 | * 1. "Closing" -> Not accepting new work. Waiting for jobs to complete.
|
127 | * 1. "Closed" -> Not accepting new work. All submitted jobs are complete.
|
128 | */
|
129 | get state(): BackgroundProcessManagerState;
|
130 | /**
|
131 | * The registered `description` of all still-pending jobs.
|
132 | *
|
133 | * @returns descriptions as an array.
|
134 | */
|
135 | get pending(): string[];
|
136 | /**
|
137 | * Whether the manager is accepting new jobs.
|
138 | */
|
139 | get isOpen(): boolean;
|
140 | /**
|
141 | * Whether the manager is rejecting new work, but still waiting for
|
142 | * submitted work to complete.
|
143 | */
|
144 | get isClosing(): boolean;
|
145 | /**
|
146 | * Whether the manager is rejecting work and done waiting for submitted
|
147 | * work to complete.
|
148 | */
|
149 | get isClosed(): boolean;
|
150 | private closedFailure;
|
151 | /**
|
152 | * Signals jobs to stop (for those that accept interruptions) and waits
|
153 | * for confirmation that jobs have stopped.
|
154 | *
|
155 | * This immediately puts the manager into a closing state and just begins
|
156 | * to reject new work. After all work in the manager is complete, the
|
157 | * manager goes into a `Completed` state and `close()` returns.
|
158 | *
|
159 | * This call is idempotent.
|
160 | *
|
161 | * If the manager is already closing or closed, `finalCleaup` is not executed.
|
162 | *
|
163 | * @param onClosed
|
164 | * @returns The settled results of each still-running job's promise. If the
|
165 | * manager is already closed, this will contain the results as of when the
|
166 | * manager's `close()` was called in an `Open` state.
|
167 | */
|
168 | close(): Promise<any>;
|
169 | /**
|
170 | * Signals the manager to start accepting work (again) and returns once
|
171 | * the manager is ready to do so.
|
172 | *
|
173 | * If the state is already `Open`, this call is a no-op.
|
174 | *
|
175 | * If the state is `Closed`, this call simply updates state and returns.
|
176 | *
|
177 | * If the state is `Closing`, this call waits for completion before it
|
178 | * updates the state and returns.
|
179 | */
|
180 | open(): Promise<void>;
|
181 | }
|
182 | /**
|
183 | *
|
184 | */
|
185 | export declare class BackgroundManagerNotOpenError extends Error {
|
186 | constructor(message: string);
|
187 | }
|
188 | /**
|
189 | * All possible states a `BackgroundProcessManager` instance can be in.
|
190 | */
|
191 | export declare enum BackgroundProcessManagerState {
|
192 | /**
|
193 | * Accepting new jobs.
|
194 | */
|
195 | Open = "Open",
|
196 | /**
|
197 | * Not accepting new jobs. Waiting for submitted jobs to complete.
|
198 | */
|
199 | Closing = "Closing",
|
200 | /**
|
201 | * Not accepting new jobs. All submitted jobs are complete.
|
202 | */
|
203 | Closed = "Closed"
|
204 | }
|