Add true support for locking multiple named resources

[ceztko]

It's clear that lockable resources plugin was initially created with very specific use case in mind (hardware sharing). With the addition of ephemeral lockable resources it turned into a facility that basically model the concept of a named mutex/semaphore (whatever they are hardware resources or anything else) but it still suffers from initial design limitations. The following syntax should definitely be allowed: 

pipeline {
    agent any
    options {
         // Syntax1: pipeline scoped multiple resource lock
        lock(["RESOURCE1", "RESOURCE2"])
    }
    stages {
        stage('Build') {
            steps {
                 // Syntax2: stage scoped multiple resource lock
                lock(["RESOURCE3", "RESOURCE4"])
                {
                    // ...
                }
            }
        }
    }
}

Syntax2 can be easily simulated but Syntax1 can't since only one lock statement is permitted in the options . Something as easy as Syntax1 and Syntax2 should be supported, because people just want it (but fails to produce a sane Pull-Request) or confuse the current capabilities of the plugin and struggle to find workarounds.

Interesting enough, the freestyle project UI falsely advertises the plugin can lock multiple resources at once, but if one write RESOURCE1,RESOURCE2 in the "Resources" (note the plural) field the plugin will lock the resource with name "RESOURCE1,RESOURCE2", not two separate resources "RESOURCE1", "RESOURCE2", which is definetely not the same thing.

[TobiX]

The following syntax works in scripted pipeline (generated by the snippet generator):

lock(extra: [[resource: 'b'], [resource: 'c']], resource: 'a') {
    // some block
}

The same can be used in declarative:

options {
    lock(extra: [[resource: 'b'], [resource: 'c']], resource: 'a')
}

or (nearer to your proposed syntax):

options {
    lock(extra: [[resource: 'a'], [resource: 'b'], [resource: 'c']])
}

So it seems people don't find the snippet generator or the step reference, so the documentation in the readme needs to be fixed (or pointers to the existing documentation added).

The only way to lock multiple resources in freestyle it through a label currently. I'm not sure if that is a bug or a feature - will investigate.

[ceztko]

Thank you. You can add +1 of people confused by actual capabilities of the plugin: indeed I searched a lot, but I missed the extra argument, which at least feels like it was added later and it's not easy to find examples using it. I will answer some questions around pointing to this syntax/issue. Yes, the UI support in the freestyle project could be misleading or bugged.

[jimklimov]

I suppose this issue is resolved by now, both in practice and in documentation.

FWIW, nested calls to lock() { lock() { ... } } (in scripted pipeline at least) are also known to work, although at a cost of blocking the outer resource dedicated to this job even if the inner resource is not available yet. My understanding is that the extra argument avoids that issue by only committing each resource to a particular job when everything needed is available at once.