@crawlee/core 4.0.0-beta.87 → 4.0.0-beta.89

package/autoscaling/autoscaled_pool.d.ts

@@ -1,12 +1,11 @@
+import type { ConcurrencyConsumer, IConcurrencySystem } from './concurrency_system.js';
 import type { CrawleeLogger } from '../log.js';
-import type { SnapshotterOptions } from './snapshotter.js';
-import type { SystemStatusOptions } from './system_status.js';
-export interface AutoscaledPoolOptions {
-    /**
-     * A function that performs an asynchronous resource-intensive task.
-     * The function must either be labeled `async` or return a promise.
-     */
-    runTaskFunction?: () => Promise<unknown>;
+/**
+ * The task-readiness predicates a consumer may supply to steer an {@link AutoscaledPool}'s run loop — the parts of
+ * the loop a higher-level driver (e.g. a crawler) legitimately overrides, as opposed to the crawler-owned
+ * `runTaskFunction`.
+ */
+export interface AutoscaledPoolPredicateOptions {
     /**
      * A function that indicates whether `runTaskFunction` should be called.
      * This function is called every time there is free capacity for a new task and it should
@@ -22,104 +21,55 @@ export interface AutoscaledPoolOptions {
      * To abort a run, use the {@link AutoscaledPool.abort} method.
      */
     isFinishedFunction?: () => Promise<boolean>;
+}
+export interface AutoscaledPoolOptions extends AutoscaledPoolPredicateOptions {
     /**
-     * The minimum number of tasks running in parallel.
+     * The governor that decides whether there is free compute for one more task. Typically a
+     * {@link ConcurrencySystem}, but any {@link IConcurrencySystem} works. Share a single instance across
+     * multiple pools (and therefore multiple crawlers) to cap their *combined* concurrency against one budget.
      *
-     * *WARNING:* If you set this value too high with respect to the available system memory and CPU, your code might run extremely slow or crash.
-     * If you're not sure, just keep the default value and the concurrency will scale up automatically.
-     * @default 1
-     */
-    minConcurrency?: number;
-    /**
-     * The maximum number of tasks running in parallel.
-     * @default 200
+     * All concurrency/scaling/snapshotter configuration lives on the governor — the pool only owns the task loop and
+     * its cadence.
      */
-    maxConcurrency?: number;
+    concurrencySystem: IConcurrencySystem;
     /**
-     * The desired number of tasks that should be running parallel on the start of the pool,
-     * if there is a large enough supply of them.
-     * By default, it is `minConcurrency`.
+     * Who this pool is, presented to the governor on every capacity query and booking so that a shared one can tell
+     * several pools apart. Worth naming meaningfully — a governor that allocates per consumer reports this `id`.
      */
-    desiredConcurrency?: number;
+    consumer: ConcurrencyConsumer;
     /**
-     * Minimum level of desired concurrency to reach before more scaling up is allowed.
-     * @default 0.90
-     */
-    desiredConcurrencyRatio?: number;
-    /**
-     * Defines the fractional amount of desired concurrency to be added with each scaling up.
-     * The minimum scaling step is one.
-     * @default 0.05
-     */
-    scaleUpStepRatio?: number;
-    /**
-     * Defines the amount of desired concurrency to be subtracted with each scaling down.
-     * The minimum scaling step is one.
-     * @default 0.05
+     * A function that performs an asynchronous resource-intensive task.
+     * The function must either be labeled `async` or return a promise.
      */
-    scaleDownStepRatio?: number;
+    runTaskFunction?: () => Promise<unknown>;
     /**
      * Indicates how often the pool should call the `runTaskFunction()` to start a new task, in seconds.
      * This has no effect on starting new tasks immediately after a task completes.
      * @default 0.5
      */
     maybeRunIntervalSecs?: number;
-    /**
-     * Specifies a period in which the instance logs its state, in seconds.
-     * Set to `null` to disable periodic logging.
-     * @default 60
-     */
-    loggingIntervalSecs?: number | null;
-    /**
-     * Defines in seconds how often the pool should attempt to adjust the desired concurrency
-     * based on the latest system status. Setting it lower than 1 might have a severe impact on performance.
-     * We suggest using a value from 5 to 20.
-     * @default 10
-     */
-    autoscaleIntervalSecs?: number;
     /**
      * Timeout in which the `runTaskFunction` needs to finish, given in seconds.
      * @default 0
      */
     taskTimeoutSecs?: number;
-    /**
-     * Options to be passed down to the {@link Snapshotter} constructor. This is useful for fine-tuning
-     * the snapshot intervals and history.
-     */
-    snapshotterOptions?: SnapshotterOptions;
-    /**
-     * Options to be passed down to the {@link SystemStatus} constructor. This is useful for fine-tuning
-     * the system status reports. If a custom snapshotter is set in the options, it will be used
-     * by the pool.
-     */
-    systemStatusOptions?: SystemStatusOptions;
-    /**
-     * The maximum number of tasks per minute the pool can run.
-     * By default, this is set to `Infinity`, but you can pass any positive, non-zero integer.
-     */
-    maxTasksPerMinute?: number;
     log?: CrawleeLogger;
 }
 /**
  * Manages a pool of asynchronous resource-intensive tasks that are executed in parallel.
- * The pool only starts new tasks if there is enough free CPU and memory available
- * and the Javascript event loop is not blocked.
- *
- * The information about the CPU and memory usage is obtained by the {@link Snapshotter} class,
- * which makes regular snapshots of system resources that may be either local
- * or from the Apify cloud infrastructure in case the process is running on the Apify platform.
- * Meaningful data gathered from these snapshots is provided to `AutoscaledPool` by the {@link SystemStatus} class.
+ * The pool only starts new tasks while its {@link IConcurrencySystem|concurrency system} reports free capacity —
+ * that governor is what monitors CPU, memory and event loop load and autoscales the concurrency budget.
  *
  * Before running the pool, you need to implement the following three functions:
- * {@link AutoscaledPoolOptions.runTaskFunction},
- * {@link AutoscaledPoolOptions.isTaskReadyFunction} and
- * {@link AutoscaledPoolOptions.isFinishedFunction}.
+ * {@link AutoscaledPoolOptions.runTaskFunction|`runTaskFunction`},
+ * {@link AutoscaledPoolPredicateOptions.isTaskReadyFunction|`isTaskReadyFunction`} and
+ * {@link AutoscaledPoolPredicateOptions.isFinishedFunction|`isFinishedFunction`}.
  *
  * The auto-scaled pool is started by calling the {@link AutoscaledPool.run} function.
- * The pool periodically queries the {@link AutoscaledPoolOptions.isTaskReadyFunction} function
- * for more tasks, managing optimal concurrency, until the function resolves to `false`. The pool then queries
- * the {@link AutoscaledPoolOptions.isFinishedFunction}. If it resolves to `true`, the run finishes after all running tasks complete.
- * If it resolves to `false`, it assumes there will be more tasks available later and keeps periodically querying for tasks.
+ * The pool periodically queries `isTaskReadyFunction` for more tasks, managing optimal concurrency, until the function
+ * resolves to `false`. The pool then queries `isFinishedFunction`. If it resolves to `true`, the run finishes after all
+ * running tasks complete. If it resolves to `false`, it assumes there will be more tasks available later and keeps
+ * periodically querying for tasks.
  * If any of the tasks throws then the {@link AutoscaledPool.run} function rejects the promise with an error.
  *
  * The pool evaluates whether it should start a new task every time one of the tasks finishes
@@ -128,8 +78,12 @@ export interface AutoscaledPoolOptions {
  * **Example usage:**
  *
  * ```javascript
+ * const concurrencySystem = new ConcurrencySystem({ maxConcurrency: 50 });
+ * await concurrencySystem.start();
+ *
  * const pool = new AutoscaledPool({
- *     maxConcurrency: 50,
+ *     concurrencySystem,
+ *     consumer: { id: 'my-pool' },
  *     runTaskFunction: async () => {
  *         // Run some resource-intensive asynchronous operation here.
  *     },
@@ -144,78 +98,56 @@ export interface AutoscaledPoolOptions {
  *     }
  * });
  *
- * await pool.run();
+ * try {
+ *     await pool.run();
+ * } finally {
+ *     await concurrencySystem.stop();
+ * }
  * ```
  * @category Scaling
  */
 export declare class AutoscaledPool {
     private readonly log;
-    private readonly desiredConcurrencyRatio;
-    private readonly scaleUpStepRatio;
-    private readonly scaleDownStepRatio;
     private readonly maybeRunIntervalMillis;
-    private readonly loggingIntervalMillis;
-    private readonly autoscaleIntervalMillis;
     private readonly taskTimeoutMillis;
     private readonly runTaskFunction;
     private readonly isFinishedFunction;
     private readonly isTaskReadyFunction;
-    private readonly maxTasksPerMinute;
-    private _minConcurrency;
-    private _maxConcurrency;
-    private _desiredConcurrency;
-    private _currentConcurrency;
+    private readonly concurrencySystem;
+    private readonly consumer;
     private isStopped;
-    private lastLoggingTime?;
     private resolve;
     private reject;
-    private snapshotter;
-    /** Additional SystemStatus loadSignals - tracked here for initialization and cleanup */
-    private loadSignals;
-    private systemStatus;
-    private autoscaleInterval;
     private maybeRunInterval;
     private queryingIsTaskReady;
     private queryingIsFinished;
-    private tasksDonePerSecondInterval?;
-    private _tasksPerMinute;
-    constructor(options: AutoscaledPoolOptions);
     /**
-     * Gets the minimum number of tasks running in parallel.
+     * This pool's *own* in-flight task count, as opposed to {@link AutoscaledPool.currentConcurrency}, which is the
+     * (possibly shared) governor's total. `pause()` and `maybeFinish()` care only about this pool draining.
      */
-    get minConcurrency(): number;
+    private ownConcurrency;
+    constructor(options: AutoscaledPoolOptions);
     /**
-     * Sets the minimum number of tasks running in parallel.
+     * The governor backing this pool, as supplied to the constructor — exposed as the read-only
+     * {@link IConcurrencySystem} contract.
      *
-     * *WARNING:* If you set this value too high with respect to the available system memory and CPU, your code might run extremely slow or crash.
-     * If you're not sure, just keep the default value and the concurrency will scale up automatically.
-     */
-    set minConcurrency(value: number);
-    /**
-     * Gets the maximum number of tasks running in parallel.
-     */
-    get maxConcurrency(): number;
-    /**
-     * Sets the maximum number of tasks running in parallel.
-     */
-    set maxConcurrency(value: number);
-    /**
-     * Gets the desired concurrency for the pool,
-     * which is an estimated number of parallel tasks that the system can currently support.
+     * This and the two getters below are telemetry only: concurrency is configured and tuned on the concrete
+     * {@link ConcurrencySystem} its owner holds, never through the pool.
      */
+    get system(): IConcurrencySystem;
+    /** The estimated number of parallel tasks the governor can currently support. */
     get desiredConcurrency(): number;
     /**
-     * Sets the desired concurrency for the pool, i.e. the number of tasks that should be running
-     * in parallel if there's large enough supply of tasks.
-     */
-    set desiredConcurrency(value: number);
-    /**
-     * Gets the number of parallel tasks currently running in the pool.
+     * The number of parallel tasks currently booked against the governor. When it is shared, this counts every
+     * borrowing pool's tasks, not just this one's.
      */
     get currentConcurrency(): number;
     /**
      * Runs the auto-scaled pool. Returns a promise that gets resolved or rejected once
      * all the tasks are finished or one of them fails.
+     *
+     * Throws if the {@link IConcurrencySystem|concurrency system} it borrows was never started — the pool assumes
+     * a running governor and cannot start one it does not own.
      */
     run(): Promise<void>;
     /**
@@ -240,6 +172,10 @@ export declare class AutoscaledPool {
      *
      * The promise returned from the {@link AutoscaledPool.run} function will not resolve
      * when `.pause()` is invoked (unlike abort, which resolves it).
+     *
+     * > *NOTE:* Pausing the pool does not suspend the (possibly shared) {@link ConcurrencySystem} — its
+     * autoscaling and resource monitoring keep running, since other pools borrowing it may still be active. To silence
+     * it during a long pause, its owner can `stop()` and `start()` it again.
      */
     pause(timeoutSecs?: number): Promise<void>;
     /**
@@ -263,26 +199,6 @@ export declare class AutoscaledPool {
      * It doesn't allow multiple concurrent runs of this method.
      */
     private maybeRunTask;
-    /**
-     * Gets called every autoScaleIntervalSecs and evaluates the current system status.
-     * If the system IS NOT overloaded and the settings allow it, it scales up.
-     * If the system IS overloaded and the settings allow it, it scales down.
-     */
-    private autoscale;
-    /**
-     * Scales the pool up by increasing
-     * the desired concurrency by the scaleUpStepRatio.
-     *
-     * @param systemStatus for logging
-     */
-    private scaleUp;
-    /**
-     * Scales the pool down by decreasing
-     * the desired concurrency by the scaleDownStepRatio.
-     *
-     * @param systemStatus for logging
-     */
-    private scaleDown;
     /**
      * If there are no running tasks and this.isFinishedFunction() returns true then closes
      * the pool and resolves the pool's promise returned by the run() method.
@@ -294,6 +210,4 @@ export declare class AutoscaledPool {
      * Cleans up resources.
      */
     private destroy;
-    private incrementTasksDonePerSecond;
-    private get isOverMaxRequestLimit();
 }