First question about this, asked on StackOverflow here

Then documented on the plugins Confluence page - probably with better formatting than this.

Also reported on Github

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.