fix: New resources now unblock waiting jobs immediately (#1004)

When a new resource is added via createResourceWithLabel() or
addResource(), waiting jobs now automatically pick it up instead
of remaining blocked.

Changes:
- Invalidate cachedCandidates and process waiting pipeline contexts
  when adding new resources (inside synchronized block for atomicity)
- Call scheduleQueueMaintenance() to notify freestyle jobs
- Add refreshQueue() public method for users who modify labels on
  existing resources (label changes don't auto-trigger re-evaluation)
- Add documentation explaining dynamic resource behavior and limitations

Fixes #892
See also: JENKINS-46744

Author: mPokornyETM

README.md

@@ -274,6 +274,26 @@ More examples are [here](src/doc/examples/readme.md).
 
 ----
 
+## Dynamic resource behavior
+
+When new resources are added to the system, waiting jobs can automatically pick them up:
+
+- **Pipeline jobs** waiting in the lock step queue are re-evaluated immediately
+- **Freestyle jobs** waiting in the Jenkins build queue are re-evaluated via queue maintenance
+
+This allows you to dynamically add resources to your resource pool without requiring waiting jobs to be restarted.
+
+### Example
+
+If a job is waiting for a resource with label `printer` and all existing printer resources are locked, adding a new resource with the label `printer` will allow the waiting job to acquire it immediately.
+
+### Limitations
+
+- **Modifying labels on existing resources does NOT trigger re-evaluation.** Only adding new resources triggers waiting jobs to re-evaluate. If you change labels on an existing resource, you can manually call `LockableResourcesManager.get().refreshQueue()` via Script Console to notify waiting jobs.
+- **Removing resources** does not affect waiting jobs (they continue waiting for other resources with matching criteria).
+
+----
+
 ## Node mirroring
 
 Lockable resources plugin allow to mirror nodes (agents) into lockable resources. This eliminate effort by re-creating resources on every node change.

src/doc/examples/dynamic-resource-pool-expansion.md

@@ -0,0 +1,75 @@
+# Dynamic Resource Pool Expansion
+
+This example demonstrates how waiting jobs can automatically acquire newly added resources.
+
+## Use Case
+
+You have a pool of resources (e.g., test devices) labeled `test-device`. All devices are currently in use by running jobs. A new job starts and waits for a `test-device`. When you add a new device to the pool, the waiting job should automatically acquire it without needing to be restarted.
+
+## Pipeline Example
+
+### Job waiting for a resource
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Acquire Device') {
+            steps {
+                lock(label: 'test-device', quantity: 1, variable: 'DEVICE') {
+                    echo "Acquired device: ${env.DEVICE}"
+                    // Use the device
+                    sh 'run-tests.sh'
+                }
+            }
+        }
+    }
+}
+```
+
+### Adding a new resource via pipeline step
+
+While the job is waiting, you can add a new resource via a management job or the Script Console using the `updateLock` step:
+
+```groovy
+// In a pipeline job
+updateLock(resource: 'new-test-device-5', addLabels: 'test-device')
+```
+
+Or via Script Console:
+
+```groovy
+import org.jenkins.plugins.lockableresources.LockableResourcesManager
+
+def manager = LockableResourcesManager.get()
+manager.createResourceWithLabel('new-test-device-5', 'test-device')
+```
+
+The waiting job will automatically acquire `new-test-device-5` once it is added.
+
+## Freestyle Job Example
+
+For freestyle jobs configured with **Required Resources** (label: `test-device`), the same behavior applies. When a new resource with the matching label is added, the Jenkins queue is notified and the waiting freestyle job will be dispatched.
+
+## Limitations
+
+> **Important:** Modifying labels on existing resources does NOT trigger re-evaluation.
+
+Only **adding new resources** triggers waiting jobs to re-evaluate their resource requirements. If you:
+- Change labels on an existing resource (e.g., add `test-device` label to an existing resource)
+- The waiting jobs will **not** be notified
+
+To work around this limitation, you can manually trigger queue refresh via Script Console:
+
+```groovy
+import org.jenkins.plugins.lockableresources.LockableResourcesManager
+
+LockableResourcesManager.get().refreshQueue()
+```
+
+This will invalidate the cached candidates and notify both pipeline and freestyle jobs to re-evaluate available resources.
+
+## Related
+
+- [JENKINS-46744](https://issues.jenkins.io/browse/JENKINS-46744) - Original issue requesting this behavior
+- [GitHub #892](https://github.com/jenkinsci/lockable-resources-plugin/issues/892) - Implementation tracking issue

src/doc/examples/readme.md

@@ -9,3 +9,4 @@ If you have a question, please open a [GitHub issue](https://github.com/jenkinsc
 - [Locking multiple stages in declarative pipeline](locking-multiple-stages-in-declarative-pipeline.md)
 - [Locking a random free resource](locking-random-free-resource.md)
 - [Scripted vs declarative pipeline](scripted-vs-declarative-pipeline.md)
+- [Dynamic resource pool expansion](dynamic-resource-pool-expansion.md)

src/main/java/org/jenkins/plugins/lockableresources/LockableResourcesManager.java

@@ -972,10 +972,19 @@ public boolean addResource(@Nullable final LockableResource resource, final bool
             }
             this.resources.add(resource);
             LOGGER.fine("Resource added : " + resource);
+
+            // Invalidate cache and process waiting pipeline jobs while still holding the lock
+            cachedCandidates.invalidateAll();
+            while (proceedNextContext()) {
+                // process as many contexts as possible
+            }
+
             if (doSave) {
                 this.save();
             }
         }
+        // Notify Jenkins queue for freestyle jobs (must be outside synchronized block)
+        scheduleQueueMaintenance();
         return true;
     }
 
@@ -1158,6 +1167,7 @@ public void removeResources(List<LockableResource> toBeRemoved) {
         synchronized (syncResources) {
             this.resources.removeAll(toBeRemoved);
         }
+        scheduleQueueMaintenance();
     }
 
     // ---------------------------------------------------------------------------
@@ -1467,6 +1477,35 @@ public static void scheduleQueueMaintenance() {
         }
     }
 
+    // ---------------------------------------------------------------------------
+    /**
+     * Refresh the queue to allow waiting jobs to re-evaluate available resources.
+     * <p>
+     * This method should be called after modifying labels on existing resources,
+     * as label changes do not automatically trigger queue re-evaluation.
+     * <p>
+     * It performs the following actions:
+     * <ol>
+     *   <li>Invalidates the cached resource candidates</li>
+     *   <li>Processes waiting pipeline job contexts</li>
+     *   <li>Triggers Jenkins queue maintenance for freestyle jobs</li>
+     * </ol>
+     */
+    public void refreshQueue() {
+        // Invalidate cached candidates so waiting jobs re-evaluate with current labels
+        cachedCandidates.invalidateAll();
+
+        // Process waiting pipeline jobs
+        synchronized (syncResources) {
+            while (proceedNextContext()) {
+                // process as many contexts as possible
+            }
+        }
+
+        // Notify Jenkins queue for freestyle jobs
+        scheduleQueueMaintenance();
+    }
+
     // ---------------------------------------------------------------------------
     private AtomicBoolean getSavePending() {
         AtomicBoolean sp = savePending;

src/test/java/org/jenkins/plugins/lockableresources/NewResourceUnblocksWaitingJobTest.java

@@ -0,0 +1,130 @@
+/*
+ * The MIT License
+ *
+ * See the "LICENSE.txt" file for full copyright and license information.
+ */
+package org.jenkins.plugins.lockableresources;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import hudson.model.FreeStyleBuild;
+import hudson.model.FreeStyleProject;
+import org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition;
+import org.jenkinsci.plugins.workflow.job.WorkflowJob;
+import org.jenkinsci.plugins.workflow.job.WorkflowRun;
+import org.jenkinsci.plugins.workflow.test.steps.SemaphoreStep;
+import org.junit.jupiter.api.Test;
+import org.jvnet.hudson.test.Issue;
+import org.jvnet.hudson.test.JenkinsRule;
+import org.jvnet.hudson.test.junit.jupiter.WithJenkins;
+
+/**
+ * Test that jobs waiting for resources can pick up newly added resources.
+ * See JENKINS-46744 / issue #892.
+ *
+ * <p>Note: The lock step validates that at least one resource with the given
+ * label exists. If no resource has the label, it fails. Therefore we need
+ * an existing resource (locked by job1) before job2 can wait for a resource
+ * with that label.</p>
+ */
+@WithJenkins
+class NewResourceUnblocksWaitingJobTest extends LockStepTestBase {
+
+    /**
+     * Test that a pipeline job waiting for a resource by label can acquire
+     * a newly added resource that has the matching label. (JENKINS-46744)
+     *
+     * Scenario:
+     * 1. Job1 locks r1 (the only resource with label "test-label")
+     * 2. Job2 tries to lock a resource with "test-label" - it waits
+     * 3. A new resource "r2" with label "test-label" is added
+     * 4. Job2 should acquire "r2" without waiting for Job1 to finish
+     */
+    @Issue("JENKINS-46744")
+    @Test
+    void newResourceWithLabelUnblocksWaitingPipelineJob(JenkinsRule j) throws Exception {
+        // Create resource r1 that will be locked by job1
+        LockableResourcesManager lrm = LockableResourcesManager.get();
+        assertTrue(lrm.createResourceWithLabel("r1", "test-label"));
+
+        // Job1: locks r1 and holds it via semaphore
+        WorkflowJob job1 = j.jenkins.createProject(WorkflowJob.class, "job1");
+        job1.setDefinition(new CpsFlowDefinition("""
+            lock(label: 'test-label', quantity: 1, variable: 'LOCKED') {
+                echo("Job1 locked: ${env.LOCKED}")
+                semaphore('hold-lock')
+            }
+            """, true));
+
+        // Job2: tries to lock a resource with test-label
+        WorkflowJob job2 = j.jenkins.createProject(WorkflowJob.class, "job2");
+        job2.setDefinition(new CpsFlowDefinition("""
+            timeout(time: 60, unit: 'SECONDS') {
+                lock(label: 'test-label', quantity: 1, variable: 'LOCKED') {
+                    echo("Job2 locked: ${env.LOCKED}")
+                }
+            }
+            """, true));
+
+        // Start job1 - it will lock r1 and wait at semaphore
+        WorkflowRun run1 = job1.scheduleBuild2(0).waitForStart();
+        j.waitForMessage("Job1 locked: r1", run1);
+
+        // Start job2 - it should wait because r1 (the only resource) is locked
+        WorkflowRun run2 = job2.scheduleBuild2(0).waitForStart();
+        j.waitForMessage("is not free, waiting for execution", run2);
+
+        // Now add a new resource with the same label
+        // This should automatically trigger proceedNextContext() (JENKINS-46744)
+        assertTrue(lrm.createResourceWithLabel("r2", "test-label"));
+
+        // The job should now proceed and acquire r2
+        j.waitForMessage("Job2 locked: r2", run2);
+        j.assertBuildStatusSuccess(j.waitForCompletion(run2));
+
+        // Now let job1 finish
+        SemaphoreStep.success("hold-lock/1", null);
+        j.assertBuildStatusSuccess(j.waitForCompletion(run1));
+    }
+
+    /**
+     * Test that a freestyle job waiting for a resource by label can acquire
+     * a newly added resource. (JENKINS-46744)
+     */
+    @Issue("JENKINS-46744")
+    @Test
+    void newResourceUnblocksWaitingFreestyleJob(JenkinsRule j) throws Exception {
+        LockableResourcesManager lrm = LockableResourcesManager.get();
+        // Create resource r1 that will be locked by job1
+        assertTrue(lrm.createResourceWithLabel("r1", "test-label"));
+
+        // Job1: locks r1 and sleeps (holds the lock)
+        FreeStyleProject job1 = j.createFreeStyleProject("freestyle-job1");
+        job1.addProperty(new RequiredResourcesProperty(null, null, "1", "test-label", null));
+        job1.getBuildersList().add(new org.jvnet.hudson.test.SleepBuilder(10000));
+
+        // Job2: wants test-label
+        FreeStyleProject job2 = j.createFreeStyleProject("freestyle-job2");
+        job2.addProperty(new RequiredResourcesProperty(null, null, "1", "test-label", null));
+
+        // Start job1 - it will lock r1 and sleep
+        FreeStyleBuild build1 = job1.scheduleBuild2(0).waitForStart();
+        j.waitForMessage("acquired lock on [r1]", build1);
+
+        // Start job2 - it should wait in queue because r1 is locked
+        var future2 = job2.scheduleBuild2(0);
+        Thread.sleep(1000); // Give time for job2 to enter queue
+
+        // Now add a new resource with the same label
+        // This should trigger scheduleQueueMaintenance() (JENKINS-46744)
+        assertTrue(lrm.createResourceWithLabel("r2", "test-label"));
+
+        // Job2 should now get dispatched and acquire r2
+        FreeStyleBuild build2 = future2.waitForStart();
+        j.waitForMessage("acquired lock on [r2]", build2);
+        j.waitForCompletion(build2);
+
+        // Job1 will finish on its own after sleeping
+        j.waitForCompletion(build1);
+    }
+}