Package org.jenkins.plugins.lockableresources

Class LockableResourcesManager

java.lang.Object

hudson.model.Descriptor<GlobalConfiguration>

jenkins.model.GlobalConfiguration

org.jenkins.plugins.lockableresources.LockableResourcesManager

All Implemented Interfaces:

ExtensionPoint, Describable<GlobalConfiguration>, Saveable, OnMaster

@Extension
public class LockableResourcesManager
extends GlobalConfiguration

Nested Class Summary

Nested classes/interfaces inherited from class hudson.model.Descriptor

Descriptor.FormException, Descriptor.PropertyType, Descriptor.Self

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields inherited from class hudson.model.Descriptor

clazz

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Constructor	Description
LockableResourcesManager()

Method Summary

Modifier and Type	Method	Description
List<LockableResource>	checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList, PrintStream logger, List<String> lockedResourcesAboutToBeUnlocked)
List<LockableResource>	checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList, PrintStream logger, List<String> lockedResourcesAboutToBeUnlocked, boolean skipIfLocked)
List<LockableResource>	checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList, PrintStream logger, List<String> lockedResourcesAboutToBeUnlocked, boolean skipIfLocked, ResourceSelectStrategy selectStrategy)
List<LockableResource>	checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList, PrintStream logger, List<String> lockedResourcesAboutToBeUnlocked, List<String> reservedResourcesAboutToBeUnreserved)
List<LockableResource>	checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList, PrintStream logger, List<String> lockedResourcesAboutToBeUnlocked, List<String> reservedResourcesAboutToBeUnreserved, boolean skipIfLocked, ResourceSelectStrategy selectStrategy)	Checks if there are enough resources available to satisfy the requirements specified within requiredResources and returns the necessary available resources.
boolean	configure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject json)
boolean	createResource(String name)	Creates the resource if it does not exist.
boolean	createResourceWithLabel(String name, String label)
LockableResource	fromName(String resourceName)
static LockableResourcesManager	get()
Set<String>	getAllLabels()
List<QueuedContextStruct>	getCurrentQueuedContext()	Returns current queue
List<LockableResource>	getDeclaredResources()
String	getDisplayName()
int	getFreeResourceAmount(String label)
List<LockableResource>	getResources()
List<LockableResource>	getResourcesFromBuild(Run<?,?> build)
List<LockableResource>	getResourcesFromProject(String fullName)
List<LockableResource>	getResourcesMatchingScript(org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript script, Map<String,Object> params)	Get a list of resources matching the script.
static List<String>	getResourcesNames(List<LockableResource> resources)	Returns names (IDs) of given *resources*.
List<LockableResource>	getResourcesWithLabel(String label, Map<String,Object> params)
Boolean	isValidLabel(String label)
boolean	lock(List<LockableResource> resources, Run<?,?> build, org.jenkinsci.plugins.workflow.steps.StepContext context)
boolean	lock(List<LockableResource> resources, Run<?,?> build, org.jenkinsci.plugins.workflow.steps.StepContext context, String logmessage, String variable, boolean inversePrecedence)	Try to lock the resource and return true if locked.
boolean	queue(List<LockableResource> resources, long queueItemId, String queueProjectName)
List<LockableResource>	queue(LockableResourcesStruct requiredResources, long queueItemId, String queueItemProject, int number, Map<String,Object> params, Logger log)	Deprecated. USe tryQueue(org.jenkins.plugins.lockableresources.queue.LockableResourcesStruct, long, java.lang.String, int, java.util.Map, java.util.logging.Logger)
void	queueContext(org.jenkinsci.plugins.workflow.steps.StepContext context, List<LockableResourcesStruct> requiredResources, String resourceDescription, String variableName)
void	reassign(List<LockableResource> resources, String userName)	Reserves a resource that may be or not be reserved by some person already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).
void	recycle(List<LockableResource> resources)	Make the lockable resource re-usable and notify the queue(s), if any WARNING: Do not use this from inside the lock step closure which originally locked this resource, to avoid nasty surprises! Namely, this *might* let a second consumer use the resource quickly, but when the original closure ends and unlocks again that resource, a third consumer might then effectively hijack it from the second one.
boolean	reserve(List<LockableResource> resources, String userName)	Reserves an available resource for the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).
void	reset(List<LockableResource> resources)
void	save()
void	setDeclaredResources(List<LockableResource> declaredResources)
boolean	steal(List<LockableResource> resources, String userName)	Reserves a resource that may be or not be locked by some job (or reserved by some user) already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, later decides to release the resource).
List<LockableResource>	tryQueue(LockableResourcesStruct requiredResources, long queueItemId, String queueItemProject, int number, Map<String,Object> params, Logger log)	Try to acquire the resources required by the task.
boolean	uncacheIfFreeing(LockableResource candidate, boolean unlocking, boolean unreserving)	If the lockable resource availability was evaluated before and cached to avoid frequent re-evaluations under queued pressure when there are no resources to give, we should state that a resource is again instantly available for re-evaluation when we know it was busy and right now is being freed.
void	unlock(List<LockableResource> resourcesToUnLock, Run<?,?> build)
void	unlock(List<LockableResource> resourcesToUnLock, Run<?,?> build, boolean inversePrecedence)
void	unlockNames(List<String> resourceNamesToUnLock, Run<?,?> build, boolean inversePrecedence)
boolean	unqueueContext(org.jenkinsci.plugins.workflow.steps.StepContext context)
void	unreserve(List<LockableResource> resources)

Methods inherited from class jenkins.model.GlobalConfiguration

all, getDescriptor, getGlobalConfigPage

Methods inherited from class hudson.model.Descriptor

addHelpFileRedirect, bindJSON, calcAutoCompleteSettings, calcFillSettings, configure, doHelp, find, find, findByDescribableClassName, findById, getCategory, getCheckMethod, getCheckUrl, getConfigFile, getConfigPage, getCurrentDescriptorByNameUrl, getDescriptorFullUrl, getDescriptorUrl, getGlobalPropertyType, getHelpFile, getHelpFile, getHelpFile, getId, getJsonSafeClassName, getKlass, getPlugin, getPossibleViewNames, getPropertyType, getPropertyType, getPropertyTypeOrDie, getRequiredGlobalConfigPagePermission, getT, getViewPage, isInstance, isSubTypeOf, load, newInstance, newInstance, newInstancesFromHeteroList, newInstancesFromHeteroList, self, toArray, toList, toMap

Methods inherited from class java.lang.Object

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

Constructor Detail

LockableResourcesManager

public LockableResourcesManager()

Method Detail

getResources

public List<LockableResource> getResources()

getDeclaredResources

public List<LockableResource> getDeclaredResources()

setDeclaredResources

@DataBoundSetter
public void setDeclaredResources(List<LockableResource> declaredResources)

getResourcesFromProject

public List<LockableResource> getResourcesFromProject(String fullName)

getResourcesFromBuild

public List<LockableResource> getResourcesFromBuild(Run<?,?> build)

isValidLabel

public Boolean isValidLabel(String label)

getAllLabels

public Set<String> getAllLabels()

getFreeResourceAmount

public int getFreeResourceAmount(String label)

getResourcesWithLabel

public List<LockableResource> getResourcesWithLabel(String label,
                                                    Map<String,Object> params)

getResourcesMatchingScript

@NonNull
public List<LockableResource> getResourcesMatchingScript(@NonNull
                                                         org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript script,
                                                         @CheckForNull
                                                         Map<String,Object> params)
                                                  throws ExecutionException

Get a list of resources matching the script.

Parameters:

script - Script

params - Additional parameters

Returns:

List of the matching resources

Throws:

ExecutionException - Script execution failed for one of the resources. It is considered as a fatal failure since the requirement list may be incomplete

Since:

2.0

fromName

public LockableResource fromName(String resourceName)

queue

public boolean queue(List<LockableResource> resources,
                     long queueItemId,
                     String queueProjectName)

queue

@Deprecated
@CheckForNull
public List<LockableResource> queue(LockableResourcesStruct requiredResources,
                                    long queueItemId,
                                    String queueItemProject,
                                    int number,
                                    Map<String,Object> params,
                                    Logger log)

Deprecated.

USe tryQueue(org.jenkins.plugins.lockableresources.queue.LockableResourcesStruct, long, java.lang.String, int, java.util.Map, java.util.logging.Logger)

uncacheIfFreeing

public boolean uncacheIfFreeing(LockableResource candidate,
                                boolean unlocking,
                                boolean unreserving)

If the lockable resource availability was evaluated before and cached to avoid frequent re-evaluations under queued pressure when there are no resources to give, we should state that a resource is again instantly available for re-evaluation when we know it was busy and right now is being freed. Note that a resource may be (both or separately) locked by a build and/or reserved by a user (or stolen from build to user) so we only un-cache it here if it becomes completely available. Called as a helper from methods that unlock/unreserve/reset (or indirectly - recycle) stuff. NOTE for people using LR or LRM methods directly to add some abilities in their pipelines that are not provided by plugin: the `cachedCandidates` is an LRM concept, so if you tell a resource (LR instance) directly to unlock/unreserve, it has no idea to clean itself from this cache, and may be considered busy in queuing for some time afterwards.

tryQueue

@CheckForNull
public List<LockableResource> tryQueue(LockableResourcesStruct requiredResources,
                                       long queueItemId,
                                       String queueItemProject,
                                       int number,
                                       Map<String,Object> params,
                                       Logger log)
                                throws ExecutionException

Try to acquire the resources required by the task.

Parameters:

number - Number of resources to acquire. 0 means all

Returns:

List of the locked resources if the task has been accepted. null if the item is still waiting for the resources

Throws:

ExecutionException - Cannot queue the resource due to the execution failure. Carries info in the cause

Since:

2.0

lock

public boolean lock(List<LockableResource> resources,
                    Run<?,?> build,
                    @Nullable
                    org.jenkinsci.plugins.workflow.steps.StepContext context)

lock

public boolean lock(List<LockableResource> resources,
                    Run<?,?> build,
                    @Nullable
                    org.jenkinsci.plugins.workflow.steps.StepContext context,
                    @Nullable
                    String logmessage,
                    String variable,
                    boolean inversePrecedence)

Try to lock the resource and return true if locked.

unlock

public void unlock(List<LockableResource> resourcesToUnLock,
                   @Nullable
                   Run<?,?> build)

unlock

public void unlock(@Nullable
                   List<LockableResource> resourcesToUnLock,
                   @Nullable
                   Run<?,?> build,
                   boolean inversePrecedence)

unlockNames

public void unlockNames(@Nullable
                        List<String> resourceNamesToUnLock,
                        @Nullable
                        Run<?,?> build,
                        boolean inversePrecedence)

getResourcesNames

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static List<String> getResourcesNames(List<LockableResource> resources)

Returns names (IDs) of given *resources*.

getCurrentQueuedContext

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public List<QueuedContextStruct> getCurrentQueuedContext()

Returns current queue

createResource

public boolean createResource(String name)

Creates the resource if it does not exist.

createResourceWithLabel

public boolean createResourceWithLabel(String name,
                                       String label)

reserve

public boolean reserve(List<LockableResource> resources,
                       String userName)

Reserves an available resource for the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).

steal

public boolean steal(List<LockableResource> resources,
                     String userName)

Reserves a resource that may be or not be locked by some job (or reserved by some user) already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, later decides to release the resource).

reassign

public void reassign(List<LockableResource> resources,
                     String userName)

Reserves a resource that may be or not be reserved by some person already, giving it away to the userName indefinitely (until that person, or some explicit scripted action, decides to release the resource).

unreserve

public void unreserve(List<LockableResource> resources)

getDisplayName

@NonNull
public String getDisplayName()

Overrides:

getDisplayName in class Descriptor<GlobalConfiguration>

reset

public void reset(List<LockableResource> resources)

recycle

public void recycle(List<LockableResource> resources)

Make the lockable resource re-usable and notify the queue(s), if any WARNING: Do not use this from inside the lock step closure which originally locked this resource, to avoid nasty surprises! Namely, this *might* let a second consumer use the resource quickly, but when the original closure ends and unlocks again that resource, a third consumer might then effectively hijack it from the second one.

configure

public boolean configure(org.kohsuke.stapler.StaplerRequest req,
                         net.sf.json.JSONObject json)

Overrides:

configure in class GlobalConfiguration

checkResourcesAvailability

public List<LockableResource> checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList,
                                                         @Nullable
                                                         PrintStream logger,
                                                         @Nullable
                                                         List<String> lockedResourcesAboutToBeUnlocked)

See Also:

checkResourcesAvailability(List, PrintStream, List, List, boolean, ResourceSelectStrategy)

checkResourcesAvailability

public List<LockableResource> checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList,
                                                         @Nullable
                                                         PrintStream logger,
                                                         @Nullable
                                                         List<String> lockedResourcesAboutToBeUnlocked,
                                                         boolean skipIfLocked)

See Also:

checkResourcesAvailability(List, PrintStream, List, List, boolean, ResourceSelectStrategy)

checkResourcesAvailability

public List<LockableResource> checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList,
                                                         @Nullable
                                                         PrintStream logger,
                                                         @Nullable
                                                         List<String> lockedResourcesAboutToBeUnlocked,
                                                         boolean skipIfLocked,
                                                         ResourceSelectStrategy selectStrategy)

See Also:

checkResourcesAvailability(List, PrintStream, List, List, boolean, ResourceSelectStrategy)

checkResourcesAvailability

public List<LockableResource> checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList,
                                                         @Nullable
                                                         PrintStream logger,
                                                         @Nullable
                                                         List<String> lockedResourcesAboutToBeUnlocked,
                                                         @Nullable
                                                         List<String> reservedResourcesAboutToBeUnreserved)

See Also:

checkResourcesAvailability(List, PrintStream, List, List, boolean, ResourceSelectStrategy)

checkResourcesAvailability

public List<LockableResource> checkResourcesAvailability(List<LockableResourcesStruct> requiredResourcesList,
                                                         @Nullable
                                                         PrintStream logger,
                                                         @Nullable
                                                         List<String> lockedResourcesAboutToBeUnlocked,
                                                         @Nullable
                                                         List<String> reservedResourcesAboutToBeUnreserved,
                                                         boolean skipIfLocked,
                                                         ResourceSelectStrategy selectStrategy)

Checks if there are enough resources available to satisfy the requirements specified within requiredResources and returns the necessary available resources. If not enough resources are available, returns null.

queueContext

public void queueContext(org.jenkinsci.plugins.workflow.steps.StepContext context,
                         List<LockableResourcesStruct> requiredResources,
                         String resourceDescription,
                         String variableName)

unqueueContext

public boolean unqueueContext(org.jenkinsci.plugins.workflow.steps.StepContext context)

get

public static LockableResourcesManager get()

save

public void save()

Specified by:

save in interface Saveable

Overrides:

save in class Descriptor<GlobalConfiguration>