Could you please add some more information? Some pictures would be useful.

In our project we have several network printers of different types and brands. A job needs ONE printer of a certain type. Would this be possible with your plugin? Pick one of a pool?

The plugin is very similar to existing "Throttle Concurrent Builds", "Lock and Latches" and "Exclusion".

Some info is definitely required. Probably it makes sense to merge new features to one of existing plugins

Actually, this plugin does something that, as far as I can tell, no other plugin does: Create a pool (or pools) of resources that are not attached to specific slave nodes.

One feature this plugin is missing: I need to be able to attach metadata to resources (like in the https://wiki.jenkins-ci.org/display/JENKINS/External+Resource+Dispatcher plugin) so I can expose the metadata back to the test script as environment variables.

Kudos!

This plugin solved an existing issue in our project. Thanks!

Request/Suggestion:

As of now, a resource can only be released after a build is finished. Is it possible to release/unlock a resource in the middle of the build? Something like another build step that can be added (ex. additional option in "Add build step" menu).

In our build jobs, the resource is only used at the start and then the build will continue for about 10-20 minutes.

Other jobs will still have to wait for 10-20 minutes even though in reality the resource is already "free".

More documentation definitely needed.

This allows the admin to define several resources.  Then, in the job configuration, one specifies a pool (list of resources) and then indicates how many of those resources are needed to run. The job queues until sufficient resources are available. When sufficient resources become available, the job allocates those resources and proceeds, then frees the resources.

There is a nifty little page that shows what is currently locked (allocated) and what is free. It also allows a resource to be reserved and therefore unavailable. If locked or reserved, it shows what job or individual, respectively, holds the resource.

I think only one pool is available per job. But each job specification has it's own description of what constitutes the pool for that job. So, yes, I think it will do what was needed in the comment by Daniel Schneider.

There does not appear to be any notion of a resource tree. (Unfortunately, this is what I need, so I'm not using it.)

I'd have to agree with an above comment that this plugin "does something that, as far as I can tell, no other plugin does: Create a pool (or pools) of resources that are not attached to specific slave nodes"  Our group faced some problems in an early project a couple months ago with hardware routers that we dealt with but were looking to create something during down time that would address our needs.  Apparently we were a day late and a dollar short .. 

Hi,

I am testing this plugin. Is there a way to retrieve the name of the locked resource? Is there a global variable containing this value?

Example I have two resources "resA" & "resB" both having the label "res". I lock the resources using the label. Now I want to know which one it is that I have locked.

Is there a way to find this out?

Best regards,

Baubak

Hi

It would be good if you could create a profile to be shared by many resources. For example in the Config you define:

1. 2 lockable resources R1 and R2 using the label R.
2. You define a standard profile P that states that we use label R and only 1 resource in a variable RESOURCE

In your jobs you only reference the profile P.

Best regards,

Baubak

The plugin works just fine for us but seems a little limited to me.  Some suggestions for improvements I really would like to have (and consider adding them myself, in case I find the time):

• Resources should have a quantizer.
  Currently I'm creating things like 32 resources of which each represents 1GB of ram (because I have 32GB of ram available to distribute among virtual machines).  Each task which needs to create such a virtual machine requires, depending on its needs, 4, 6 or more of these resources.  So several machines using 6 resources each (6GB) can run in parallel, or one using 20 resources and three using 4 etc.
  But to create 32 resources with the same label is a PITA; it never looks good, neither in the configuration nor on the overview of required resources etc.  If I could create one quantized resource RAM_IN_GB which has a quantization of 32, that would of course be much more convenient.
• Jobs should be able to require more than one resource kind.
  I would like to have a project require, e. g. 16GB of ram and additionally a VM (a different kind of resource), and maybe a share of the CPU as well.
  Currently I only can achieve this by nesting projects (project A requires 16GB of ram, executes project B, and waits for its finishing; project B requires a VM and really does the job).  But this of course bloats up my project list and has so many other disadvantages I do not even want to start listing them here (job dependencies, build pipelines, …).
• It would be nice to have more control over the acquirement of the resources.
  Currently, starting a build puts the build to sleep until all required resources are available, then it acquires the resources, then the build runs, and no matter how the build stops, then all resources are released at once and unconditionally.
  This is inconvenient in several cases. For example If a build running on a VM fails, often the VM is actually still running (because a pull-down-step didn't happen and shouldn't happen to ease debugging), so releasing the resource creates a schism (the model of the resource is freed, but the actual resource isn't free to be used by the next project).  I then run into instantaneous errors because the next project gets this resource, tries to use it and fails (because it isn't really available).
  1. It would be nice to be able to state on a project-config basis that a resource is not to be freed automatically when the build terminates.
  2. It would be nice to be able to acquire resources during the run of project (with a timeout, to be able to special-handle this situation).
• How resources are distributed should be configurable.
  Currently, always the "topmost" available resource will be used. This means that if I have, e. g. three printers, one will have much more work than the other two.  It would be nice the be able to configure, e. g. a round-robin or a random method to achieve an equal load on all resources.

Using it to run certification jobs that use pools of external resources and to maintain these resources using ElasticAxis. Require certain modifications to plugin, however. Here's an explanation how to manage the pools and do certification testing: PDF on github

This is a fantastic plugin which really does have something many others don't.  This plugin allows you to manage pools of resources (For me, this is pricey systems which must be a part of our test cycle) and allocate them to jobs as they run.  If none are available, it will block the job until one frees up.  If someone were to continue development on this, or extend it in another plugin, I'd be very happy.   Ideally, I'd love:

• Some sort of API allowing me within my own test code to request/release systems, so that people running tasks outside of jenkins can make use of the same pool.   Maybe this can be part of the jenkins REST api, or maybe it already is, and it simply isn't documented.
• Ability to use more resources if they are available.  For example, my test must always run on 1 system.  However, if I can programatically know that 3 are available, I can take 2 systems instead, leaving one for the queue, and still enable my job to run faster/run more tests.

Really well done to the author and I hope you will continue development of this plugin. 

Is it possible to send lockable resource name as a parameter to job? Assume that valid resource is sent as parameter.

Thanks,

Yogesh

Being able to use a build variable from a build parameter for the label would be very useful as well.

Is it possible to allocate different kinds of resources in one build (resources with different label)?

When using this in a pipeiline, if a resource is locked, is there an easy way to find out which running job has that lock?

Great plugin - so simple and effective.

Could you make the Lockable Resources Manager on the Configure System page collapsible. We have dozens of resources and this makes the config page very large!

Does the current version work as expected when used in a free-flow job?

I set up a small test scenario to play with, and it seems like waiting for resources works, but not waiting for Labels.

Edit: Added to Jenkins JIRA as JENKINS-44388. 

Edit 2. Closed as "not an error". The documentation in the plugin has been updated, although the description on this page still needs some cleanup.

My tests below:

I used a resource named TEST, with two labels TEST_1 and TEST_2.
Looking at the available resources, it's reported that I have the "TEST" resource, and one instance of the two labels - as expected.

In a free-flow job, I enable This build requires lockable resources, and the tested the following four setups:

Trial 1
Resources = TEST
Number of resources to request = 0

Expectation: The resource TEST and all labels consumed during the test.

On execution:
The test project does not wait for anything.
None of the resources nor labels are reported used.
Note: This might be correct behaviour - provided 0 is used literal, unlike documented in the plugin: "empty value or 0 means all "

Trial 2
Resources = "TEST"
Number of resources to request = 1

Expectation: All labels on the TEST resource will be consumed.

On execution:
The test project does wait for the TEST resource and does consume all Labels.

Tested on Plugin release 2.0 @ Jenkins 2.57

I wrote this question on StackOverflow (direct link), but for completeness I'm also including it here.

Edit: Added to Jenkins JIRA as JENKINS-44389

Edit 2: Closed as fixed. It's now possible to use Groovy from freestyle jobs, and get the expected result.

tl;dr,  More documentation for this plugin is certainly needed. This comment may shed some light on how some things are working - but it also showcases some things that are apparently not working!

I'm was initially attempting to get the Lockable Resources Plugin to lock on a specific resource while also evaluation the value of a system environment variable.
Evaluation the system environment variable is working perfectly, however, I can't seem to get a lock on the correct resource.

This question focused on the specific locking problem!

I have created a three resources called A_TEST, B_TEST and C_TEST. None of them have any Labels. They are all visible from my Jenkins_URL/lockable-resources/ where they can be taken and released without problems.

In my Jenkins Job configuration, I have selected the This build requires lockable resources option, which allows me to specify a Resource, Label or Groovy Expression (and Additional classpath). It additionally allows me to specify Reserved resources variable name and Number of resources to request.

According to the documentation, the Groovy script must return a boolean value, so I determined to try it out:

Test 1

The first test I did was to verify the basic functionality, by setting the following:

• Resource = B_TEST
• Groovy Expression = Not checked
• Number of resources to request = 1

This results in the job executing with a lock on the B_TEST resource. The console output reads:

[lockable-resources] acquired lock on [B_TEST]

Test 2

In this test I set the following:

• Resource = B_TEST
• Groovy Expression = Checked
• Groovy Script = return false
• Number of resources to request = 1

When attempting to execute the job, this wrongly waits forever with the text: (pending--Waiting for the resourced [B_TEST])

Test 3

In this test I set the following:

• Resource = B_TEST
• Groovy Expression = Checked
• Groovy Script = return true
• Number of resources to request = 1

This results in the wrong resource A_TEST to be locked. The console output reads:

[lockable-resources] acquired lock on [A_TEST]

Test 4

After rereading the help for each option in the plugin, I discovered that the plugin apparently only allows me to specify either a Resource, Label or Groovy Expression So in this test I set the following:

• Groovy Expression = Checked
• Groovy Script = return false
• Reserved resources variable name = MyResourceName

This results in the job executing wrongly without a lock on any resource. The console output reads:

[lockable-resources] acquired lock on []

Test 5

So in this test I set the following:

• Groovy Expression = Checked
• Groovy Script = return true
• Reserved resources variable name = MyResourceName

This results in the job wrongly locking on all resource. The console output reads:

[lockable-resources] acquired lock on [A_TEST, B_TEST, C_TEST]

Test 6

According to the documentation of the plugin, in Jenkins-Pipelines this plugin can be used as this:

echo 'Starting'
lock('my-resource-name') { 
   echo 'Do something here that requires unique access to the resource'
   // any other build will wait until the one locking the resource leaves this block 
} 
echo 'Finish'

so I started experimenting with the Groovy Script containing variations of the lock('B_TEST') call, but this mostly lead to more confusion and errors while the job attempted to start, such as this:

No signature of method: Script1.lock() is applicable for argument types: (java.util.LinkedHashMap) values: [[resource:B_TEST]] Possible solutions: each(groovy.lang.Closure), wait(), run(), run(), any(), find())

But I guess this all makes good sense, as the lock(){ } call seems suited to take and release the lock only during its capture.

The Question

The big question now is, how does all of this actually work? My guess is that somewhere there's a groovy command to specify the Resources/Labels you want to reserve, and the return value (true/false) determines to actually take the lock or not. I have attempted to dive into the source, but didn't have any luck.

Any answer is greatly appreciated.

Is it possible to pick and lock an available resource from the pool (any would do - so following the example in documentation, say I want some printer, don't care which one - but exclusively dedicated for this job run)?

If a job selects a resource by label, the console output has a message saying "acquiring lock on [resourcename]".

But if it selects a resource explicitly by name, the message is "acquiring lock on []", without the name. it would be helpful if it could include the name in this case too.

I have a job that only wants to lock under certain conditions. When I want to bypass the lock, I pass in a lockname of ''.

This works, but it prints this in the console :

Trying to acquire lock on [[no resource/label specified - probably a bug]]

This is fine, But, it would be nice if there were a way to explicitly disable the lock so that the console wouldn't have to report a non-bug.

I am thinking something like this:

LOCKDISABLED = true

if (condition) { LOCKDISABLED = true }

lock(resource 'myresource', disabled: LOCKDISABLED )
{
// stuff
}

I have a set of jobs which want to acquire lock on a resource "xyz". I want one of the job to have high priority while trying to acquiring the lock. How can I achieve this.
I noticed that some code was removed in 2015 that was adding a priority based lock precedence.

In my case default and inverse precedence do not help
Is it possible to edit the resource queue dynamically to move the high priority request to the front of queue?

Thank you very much for this plugin.It is a very useful plugin

Is there anyway to get the utilisation of resources?. Basically I need to plan for adding more resources based on the usage of a particular label.

Is it possible to require a resource with zero quantity?

Here is why this would be extremely useful: I want to use resource locking to prevent running jobs when some external services  are down. Mainly we do lock/unlock one resource with the name of the service, via a script or manually using Jenkins UI.

Now jobs should not run while the resource is locked but we do not want them to lock any resource as we want to allow them to run in parallel. This translates to a job which waits for a lock but does not reserve anything while running.

Does this work or not?

How to get locked resource(s) name(s) when using lock from a pipeline?

I need to start a process and pass reserved name as a parameter 

A try to lock a resource from a pipeline is never satisfied if resource is not available when pipeline starts. Is it a known issue?

Steps to reproduce:

1. reserve all resources with LABEL
2. Start a pipeline pointing to 1 resource with LABEL
3. release resource(s) with LABEL

Expected result:

     A resource is reserved and pipeline continues working

Actual behavior:

    Pipeline keeps waiting for a resource while it's available

Started by user Vadim Sluzky
[Pipeline] lock Trying to acquire lock on [Label: Win81, Quantity: 1]
Found 0 available resource(s). Waiting for correct amount: 1.
[Label: Win81, Quantity: 1] is locked, waiting...

Hi Developer,

Could you please update plugin-details / help / Examples, so that user gets to know about what is new in version 2.2 ?

I found a bug: Locked variable is assigned only to one of threads during parallel execution.

Below is a simple pipeline script that displays the problem.

It starts 3 threads in parallel each locking a resource by label. I specified a single available resource with this label.

The locked resource should be assigned to a variable, but it is assigned only once in the first executed thread.

Here is the script to reproduce the problem:

node('slave') {
    def execs = [:]
    execs[1] = {
        lock(label: 'Win81x64Pool', quantity: 1, variable: "MY_VAR") {
            println "LOCKED=" + env.MY_VAR
            sleep(3)
       }
    }
    execs[2] = {
        lock(label: 'Win81x64Pool', quantity: 1, variable: "MY_VAR") {
            println "LOCKED=" + env.MY_VAR
            sleep(3)
        }
    }
    execs[3] = {
        lock(label: 'Win81x64Pool', quantity: 1, variable: "YOUR_VAR") {
            println "LOCKED=" + env.YOUR_VAR
            sleep(3)
        }
    }
    parallel execs
}

and here is an exempt from console output. Please note that LOCKED=null for second and third threads

[1] Lock acquired on [Label: Win81x64Pool, Quantity: 1]
[Pipeline] [1] { [Pipeline] [2] lock [2] Trying to acquire lock on [Label: Win81x64Pool, Quantity: 1]
[2] Found 0 available resource(s). Waiting for correct amount: 1.
[2] [Label: Win81x64Pool, Quantity: 1] is locked, waiting...
[Pipeline] [3] lock [3] Trying to acquire lock on [Label: Win81x64Pool, Quantity: 1]
[3] Found 0 available resource(s). Waiting for correct amount: 1.
[3] [Label: Win81x64Pool, Quantity: 1] is locked, waiting...
[Pipeline] [1] echo [1] LOCKED=Win81x64
[Pipeline] [1] sleep [1] Sleeping for 3 sec
[2] Lock acquired on [Label: Win81x64Pool, Quantity: 1]
[Pipeline] [1] } [1] Lock released on resource [Label: Win81x64Pool, Quantity: 1]
[Pipeline] [2] { [Pipeline] [1] // lock [Pipeline] [1] } [Pipeline] [2] echo [2] LOCKED=null
[Pipeline] [2] sleep [2] Sleeping for 3 sec
[3] Lock acquired on [Label: Win81x64Pool, Quantity: 1]
[Pipeline] [2] } [2] Lock released on resource [Label: Win81x64Pool, Quantity: 1]
[Pipeline] [3] { [Pipeline] [2] // lock [Pipeline] [2] } [Pipeline] [3] echo [3] LOCKED=null
[Pipeline] [3] sleep [3] Sleeping for 3 sec
[Pipeline] [3] } [3] Lock released on resource [Label: Win81x64Pool, Quantity: 1]
[Pipeline] [3] // lock [Pipeline] [3] } [Pipeline] // parallel [Pipeline] } [Pipeline] // node [Pipeline] End of Pipeline Finished: SUCCESS

Hi, I have a question, I'm trying to use the plugin with Declarative pipeline and I lost one executor while the resource is freedom when I use lock into the pipeline block, when I use it out of the block the execution never is send to the queue(I know that this is not the right way). Could you explain me if is possible use the plugin without block an executor with Declarative pipeline? 

Can the lock be somehow used in a declarative pipeline across multiple stages? I couldn't get the pipeline to work with lock being at a higher level than under steps {...}.

That would still be okay if the lock step only performed the lock and it was up to me to put a "release" step elsewhere in the pipeline, but there doesn't seem to be a release step, and the lock step won't work without a body of its own 

I had some trouble creating resources via Jenkins DSL (groovy) code. In the end I managed to do it via some uberClassLoader technique, so thought I'd share the approach here:

  // create a lockable resource via Jenkins DSL code

 def lrm = Jenkins.instance.getPluginManager().uberClassLoader.loadClass("org.jenkins.plugins.lockableresources.LockableResourcesManager")

 lrm.get().createResource(resource_name)

Use Lockable Resource as a mutex, sharing a resource between multiple freestyle jobs. (Also, how to use parameters to set the lockable resource, and used node.) 

Scenario

We have multiple jobs that need to access the same hardware. Some of these jobs are split into sub-jobs, and a mutex like functionality are needed to avoid a mixup.

 Note: The lockable resource is implemented so that for each lockable resource it calls triggered jobs one at a time, and offers the resource. If the job accepts the resource, it becomes locked. Thereby no race-condition can occour in the mutex.

Pre-requvisits

• Lockable Resources Plugin: https://wiki.jenkins.io/display/JENKINS/Lockable+Resources+Plugin
• Groovy Label Assignment plugin: https://wiki.jenkins.io/display/JENKINS/Groovy+Label+Assignment+plugin
• Parameterized Trigger Plugin: https://wiki.jenkins.io/display/JENKINS/Parameterized+Trigger+Plugin
  
  

Implementation

The hardware (two in this explanation) are called HiL1 and HiL2.
In order to create the mutex, two lockable resources are needed, and for ease of use they get the same names: HiL1 and HiL2. Optionally, additional two lockable resources are needed to keep track of the execution: HiL1_sub and HiL2_sub.

The main jobs are the owners of the mutex, and they can pass on a mutex token to sub-jobs, which is used to lock on the actual nodes.

Each of the main jobs can be started specifying to get either a random lock on one of, or a specific lock on one of, the two lockable resources, by specifying either HiL, HiL1 or HiL2.

Main jobs

The main jobs are implemented as below. Example name is Jenkins_Test/Lockable_Resources_Job1_Test

// Beware, this executes before the console log is initialized, so the Groovy println output ends up in jenkins.out.log !!
this.binding.variables.each {k,v -> println "$k = $v"}
if ( (resourceName.startsWith(RESOURCE_FOR_THIS_JOB)) && (!resourceName.endsWith("_sub")) ) {
// println "Gotit"
   return true
}
return false

Sub-jobs

Each sub job should be implemented as below. Example name is: Jenkins_Test/Lockable_Resources_Test_Job1_Sub

// Set the node to execute on.
// Can be either HiL1 or HiL2
if (RESOURCE_CONSUMED_BY_TOP_JOB.startsWith("HiL")) {
   return RESOURCE_CONSUMED_BY_TOP_JOB
}

// Beware, this executes before the console log is initialized, so the Groovy println output ends up in jenkins.out.log !!

this.binding.variables.each {k,v -> println "$k = $v"}
if (resourceName == RESOURCE_CONSUMED_BY_TOP_JOB + "_sub") {
// println "Gotit"
return true
}
return false

@echo off
echo Show mutex token and assistent:
echo RESOURCE_CONSUMED_BY_TOP_JOB = "%RESOURCE_CONSUMED_BY_TOP_JOB%"
echo RESOURCE_CONSUMED_BY_THIS_JOB = "%RESOURCE_CONSUMED_BY_THIS_JOB%"

Now manually triggering a sub-job will not work. Only by starting one of the main jobs, the sub-jobs can be executed.

A simple pipeline script locking a single lock as follows:

lock('qp5_nonconcurrent_build') { 

    ...

}

Here's the log output:

  Trying to acquire lock on [qp5_nonconcurrent_build]
  Found 0 available resource(s). Waiting for correct amount: 1.
  [qp5_nonconcurrent_build] is locked, waiting...

And it waits forever.

Aborting and restarting (or rebuilding a prior build) at no avail - all hanging again.

However, the immediately prior run ended nicely:

  Lock released on resource [qp5_nonconcurrent_build]

We're pretty confident no one else inside Jenkins is using this name.

This came to happen all of a sudden.

Any clue?

Thanks,

Andre

I believe the documentation on this page is confusing resource with label and vice versa.  A resource is a single entity while a label can be applied over multiple resources to create a pool of resources.  Could the maintainer update the documentation/example to fix this?  Example of correct usage:

Resource: Printer1  Label: Printers

Resource: Printer2  Label: Printers

Then you can do:

lock(label: 'Printers', quantity: 1)

to acquire one of the printers.

Is it possible to show the jenkins jobs which are waiting for a locked resource ?

It would als be nice to be able to kill those jobs with an option 'purge waiting for resource jobs'