net.i2p.router

## Class JobQueue

- java.lang.Object
- - net.i2p.router.JobQueue

-     public class JobQueue
      extends Object

  Prioritizes and executes router jobs with preference for earlier scheduled tasks. Manages job queues, timing, and thread pool execution for router-internal operations only. For use by the router only. Not to be used by applications or plugins.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static String` | `PROP_MAX_RUNNERS` router.config parameter to override the max runners
    `(package private) static int` | `RUNNERS` How many when we go parallel

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JobQueue(RouterContext context)` Does not start the pumper.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addJob(Job job)` Enqueue the specified job for normal processing.
    `void` | `addJobToTop(Job job)` Enqueue the specified job to be processed at the top of the queue.
    `(package private) void` | `addRunners(int count)` Add additional job runners to the pool.
    `void` | `allowParallelOperation()` Enable parallel job execution and start additional queue runner threads.
    `(package private) int` | `getActiveRunnerCount()` Get the current number of active job runners.
    `long` | `getAvgLag()` Get the average lag time for jobs waiting in the queue.
    `double` | `getAvgLagDouble()` Get the average lag time with sub-millisecond precision.
    `int` | `getJobs(Collection<Job> readyJobs, Collection<Job> timedJobs, Collection<Job> activeJobs, Collection<Job> justFinishedJobs)` Collect statistics about jobs currently in the queue.
    `Collection<JobStats>` | `getJobStats()` Get all job statistics collected by the queue.
    `Job` | `getLastJob()` Get the last job that was executed.
    `long` | `getLastJobBegin()` Get the timestamp of when the last job began execution.
    `long` | `getLastJobEnd()` Get the timestamp of when the last job finished execution.
    `long` | `getMaxActiveJobDuration()` Get the maximum duration of currently running jobs.
    `long` | `getMaxLag()` Get the maximum lag time for jobs waiting in the queue.
    `double` | `getMaxLagDouble()` Get the maximum lag time with sub-millisecond precision.
    `int` | `getMaxRunnerCount()` Get the current maximum number of job runners allowed.
    `int` | `getMaxWaitingJobs()` Get the maximum number of waiting jobs before dropping.
    `(package private) Job` | `getNext()`
    `long` | `getPeakLag()` Get the peak lag observed from completed jobs in the last interval.
    `int` | `getReadyCount()` Get the number of jobs ready to be executed.
    `int` | `getTestJobCount()` Count the number of TestJob instances currently queued in the job queue.
    `(package private) boolean` | `isAlive()` Check if the job queue is currently alive and processing jobs.
    `(package private) int` | `removeIdleRunners(int maxToRemove)` Remove idle job runners from the pool.
    `void` | `removeJob(Job job)` Remove a job from the job queue.
    `(package private) void` | `removeRunner(int id)` Remove a queue runner from the registry.
    `void` | `runQueue(int numThreads)` Start the job queue with the specified number of runner threads.
    `(package private) void` | `shutdown()` Shutdown the job queue, stopping all runners and clearing all jobs.
    `void` | `startup()` Initialize and start the job queue pumper thread.
    `(package private) void` | `updateStats(Job job, double duration)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PROP_MAX_RUNNERS

          static final String PROP_MAX_RUNNERS

      router.config parameter to override the max runners
      See Also:
        Constant Field Values

    - #### RUNNERS

          static int RUNNERS

      How many when we go parallel

  - ### Constructor Detail

    - #### JobQueue

          public JobQueue(RouterContext context)

      Does not start the pumper. Caller MUST call startup.

  - ### Method Detail

    - #### addJob

          public void addJob(Job job)

      Enqueue the specified job for normal processing.
      Parameters:
        `job` - job to add to the queue

    - #### addJobToTop

          public void addJobToTop(Job job)

      Enqueue the specified job to be processed at the top of the queue. This is a high-priority job that will be run before any normal-priority jobs.
      Parameters:
        `job` - job to add to the front of the queue

    - #### addRunners

          void addRunners(int count)

      Add additional job runners to the pool. Package-private for use by JobQueueScaler.
      Parameters:
        `count` - the number of runners to add

    - #### allowParallelOperation

          public void allowParallelOperation()

      Enable parallel job execution and start additional queue runner threads. After calling this, multiple jobs may execute concurrently.

    - #### getActiveRunnerCount

          int getActiveRunnerCount()

      Get the current number of active job runners. Package-private for use by JobQueueScaler.
      Returns:
        the number of active runners

    - #### getAvgLag

          public long getAvgLag()

      Get the average lag time for jobs waiting in the queue. This is the average delay between when jobs were supposed to start and the current time across all ready jobs.
      Returns:
        average lag in milliseconds, or 0 if queue is empty

    - #### getAvgLagDouble

          public double getAvgLagDouble()

      Get the average lag time with sub-millisecond precision. This is the average delay between when jobs were supposed to start and the current time across all ready jobs.
      Returns:
        average lag in milliseconds as a double, or 0.0 if queue is empty

    - #### getJobs

          public int getJobs(Collection<Job> readyJobs,
                             Collection<Job> timedJobs,
                             Collection<Job> activeJobs,
                             Collection<Job> justFinishedJobs)

      Collect statistics about jobs currently in the queue. This includes jobs that are ready, timed, active, and just finished.
      Parameters:
        `readyJobs` - collection to populate with ready jobs
        `timedJobs` - collection to populate with timed/scheduled jobs
        `activeJobs` - collection to populate with currently running jobs
        `justFinishedJobs` - collection to populate with recently finished jobs
      Returns:
        the number of queue runners currently active

    - #### getJobStats

          public Collection<JobStats> getJobStats()

      Get all job statistics collected by the queue.
      Returns:
        unmodifiable collection of JobStats for all job types

    - #### getLastJob

          public Job getLastJob()

      Get the last job that was executed.
      Returns:
        the last Job that was executed, or null if no jobs have run

    - #### getLastJobBegin

          public long getLastJobBegin()

      Get the timestamp of when the last job began execution.
      Returns:
        timestamp in milliseconds when the last job started, or -1 if no jobs have run

    - #### getLastJobEnd

          public long getLastJobEnd()

      Get the timestamp of when the last job finished execution.
      Returns:
        timestamp in milliseconds when the last job ended, or -1 if no jobs have run

    - #### getMaxActiveJobDuration

          public long getMaxActiveJobDuration()

      Get the maximum duration of currently running jobs. This measures how long active jobs have been executing, which is important when all runners are busy but queue is empty.
      Returns:
        max duration in milliseconds of any currently running job, or 0 if no jobs running

    - #### getMaxLag

          public long getMaxLag()

      Get the maximum lag time for jobs waiting in the queue. This is the delay between when the earliest job was supposed to start and the current time.
      Returns:
        maximum lag in milliseconds, or 0 if queue is empty

    - #### getMaxLagDouble

          public double getMaxLagDouble()

      Get the maximum lag time with sub-millisecond precision. This is the delay between when the earliest job was supposed to start and the current time.
      Returns:
        maximum lag in milliseconds as a double, or 0.0 if queue is empty

    - #### getMaxRunnerCount

          public int getMaxRunnerCount()

      Get the current maximum number of job runners allowed. Returns the RAM-adjusted limit if scaler is active and RAM is constrained, otherwise returns the hard limit (2× configured).
      Returns:
        the current effective maximum runner limit

    - #### getMaxWaitingJobs

          public int getMaxWaitingJobs()

      Get the maximum number of waiting jobs before dropping. During attacks (low tunnel build success), increases queue capacity to handle more load. This does NOT increase lag - it just allows more jobs to queue before dropping.
      Returns:
        the max waiting jobs limit

    - #### getNext

          Job getNext()

    - #### getPeakLag

          public long getPeakLag()

      Get the peak lag observed from completed jobs in the last interval. This shows the maximum delay experienced by any job that finished, unlike getAvgLag() which only shows current queue state.
      Returns:
        peak lag in milliseconds from recently completed jobs

    - #### getReadyCount

          public int getReadyCount()

      Get the number of jobs ready to be executed.
      Returns:
        count of ready jobs in both normal and high priority queues

    - #### getTestJobCount

          public int getTestJobCount()

      Count the number of TestJob instances currently queued in the job queue. This includes both ready jobs and timed jobs waiting to be executed.
      Returns:
        the total number of TestJob instances in the queue

    - #### isAlive

          boolean isAlive()

      Check if the job queue is currently alive and processing jobs.
      Returns:
        true if the queue is alive and running

    - #### removeIdleRunners

          int removeIdleRunners(int maxToRemove)

      Remove idle job runners from the pool. Package-private for use by JobQueueScaler. Only removes runners that are not currently processing a job.
      Parameters:
        `maxToRemove` - the maximum number of runners to remove
      Returns:
        the number of runners actually removed

    - #### removeJob

          public void removeJob(Job job)

      Remove a job from the job queue.
      Parameters:
        `job` - the job to remove from the queue

    - #### removeRunner

          void removeRunner(int id)

      Remove a queue runner from the registry. Package-private for use by JobQueueRunner.
      Parameters:
        `id` - the runner ID to remove

    - #### runQueue

          public void runQueue(int numThreads)

      Start the job queue with the specified number of runner threads. Does nothing if parallel operation is not enabled and runners already exist.
      Parameters:
        `numThreads` - the number of runner threads to start

    - #### shutdown

          void shutdown()

      Shutdown the job queue, stopping all runners and clearing all jobs.

    - #### startup

          public void startup()

      Initialize and start the job queue pumper thread. Does not start the job runner threads.

    - #### updateStats

          void updateStats(Job job,
                           double duration)