Class LockableResourcesManager
- java.lang.Object
-
- hudson.model.Descriptor<GlobalConfiguration>
-
- jenkins.model.GlobalConfiguration
-
- org.jenkins.plugins.lockableresources.LockableResourcesManager
-
- All Implemented Interfaces:
ExtensionPoint
,Describable<GlobalConfiguration>
,Saveable
,Loadable
,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 Modifier and Type Field Description static Object
syncResources
Object to synchronized operations over LRM-
Fields inherited from class hudson.model.Descriptor
clazz
-
-
Constructor Summary
Constructors Constructor Description LockableResourcesManager()
C-tor
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
addResource(LockableResource resource)
boolean
addResource(LockableResource resource, boolean doSave)
void
changeQueueOrder(String queueId, int newPosition)
Change the order (position) of the given item in the queueboolean
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)
boolean
createResourceWithLabelAndProperties(String name, String label, Map<String,String> properties)
LockableResource
fromName(String resourceName)
Returns resource matched by name.List<LockableResource>
fromNames(List<String> names)
List<LockableResource>
fromNames(List<String> names, boolean createResource)
static LockableResourcesManager
get()
Set<String>
getAllLabels()
Returns all configured labels.List<String>
getAllResourcesNames()
Returns names (IDs) off all existing resources (inclusive ephemeral)List<LockableResource>
getAvailableResources(List<LockableResourcesStruct> requiredResourcesList)
List<LockableResource>
getAvailableResources(List<LockableResourcesStruct> requiredResourcesList, PrintStream logger, ResourceSelectStrategy selectStrategy)
Checks if there are enough resources available to satisfy the requirements specified within requiredResources and returns the necessary available resources.List<LockableResource>
getAvailableResources(QueuedContextStruct entry)
List<QueuedContextStruct>
getCurrentQueuedContext()
Returns current queueList<LockableResource>
getDeclaredResources()
Get declared resources, means only defined in config file (xml or JCaC yaml).String
getDisplayName()
LockableResource
getFirst()
For testing purpose.int
getFreeResourceAmount(String label)
Deprecated.List<LockableResource>
getReadOnlyResources()
Get all resources - read only The same as getResources() but unmodifiable list.List<LockableResource>
getResources()
Get all resources Includes declared, ephemeral and node resourcesList<LockableResource>
getResourcesFromBuild(Run<?,?> build)
Get all resources used by build.List<LockableResource>
getResourcesFromProject(String fullName)
Get all resources used by project.List<LockableResource>
getResourcesMatchingScript(org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript script, Map<String,Object> params)
Returns a list of resources matching by given *script*.static List<String>
getResourcesNames(List<LockableResource> resources)
Returns names (IDs) of given *resources*.List<LockableResource>
getResourcesWithLabel(String label)
Returns resources matching by given *label*.List<LockableResource>
getResourcesWithLabel(String label, Map<String,Object> params)
Deprecated.Use getResourcesWithLabel(String label) Note: The param *params* is not used (has no effect)Boolean
isValidLabel(String label)
Check if the label is valid.boolean
lock(List<LockableResource> resources, Run<?,?> build)
Try to lock the resource and return true if locked.boolean
lock(List<LockableResource> resources, Run<?,?> build, org.jenkinsci.plugins.workflow.steps.StepContext context)
Deprecated.boolean
lock(List<LockableResource> resources, Run<?,?> build, org.jenkinsci.plugins.workflow.steps.StepContext context, String logmessage, String variable, boolean inversePrecedence)
Deprecated.static void
printLogs(String msg, Level level, Logger L, PrintStream logger)
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)
void
queueContext(org.jenkinsci.plugins.workflow.steps.StepContext context, List<LockableResourcesStruct> requiredResources, String resourceDescription, String variableName, boolean inversePrecedence, int priority)
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.void
removeResources(List<LockableResource> toBeRemoved)
Function removes all given resourcesboolean
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)
boolean
resourceExist(String resourceName)
Checks if given resource exist.void
save()
void
setDeclaredResources(List<LockableResource> declaredResources)
Set all declared resources (do not includes ephemeral and node resources).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)
Deprecated.void
unlock(List<LockableResource> resourcesToUnLock, Run<?,?> build, boolean inversePrecedence)
Deprecated.void
unlockNames(List<String> resourceNamesToUnLock, Run<?,?> build)
void
unlockNames(List<String> resourceNamesToUnLock, Run<?,?> build, boolean inversePrecedence)
Deprecated.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
-
-
-
-
Field Detail
-
syncResources
public static final transient Object syncResources
Object to synchronized operations over LRM
-
-
Method Detail
-
getResources
public List<LockableResource> getResources()
Get all resources Includes declared, ephemeral and node resources
-
getReadOnlyResources
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getReadOnlyResources()
Get all resources - read only The same as getResources() but unmodifiable list. The getResources() is unsafe to use because of possible concurrent modification exception.
-
getDeclaredResources
public List<LockableResource> getDeclaredResources()
Get declared resources, means only defined in config file (xml or JCaC yaml).
-
setDeclaredResources
@DataBoundSetter public void setDeclaredResources(List<LockableResource> declaredResources)
Set all declared resources (do not includes ephemeral and node resources).
-
getResourcesFromProject
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesFromProject(String fullName)
Get all resources used by project.
-
getResourcesFromBuild
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesFromBuild(Run<?,?> build)
Get all resources used by build.
-
isValidLabel
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Boolean isValidLabel(@Nullable String label)
Check if the label is valid. Valid in this context means, if is configured on someone resource.
-
getAllLabels
@NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Set<String> getAllLabels()
Returns all configured labels.
-
getFreeResourceAmount
@NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @Deprecated public int getFreeResourceAmount(String label)
Deprecated.Get amount of free resources contained given *label* This method is deprecated (no where used) and is not tested.
-
getResourcesWithLabel
@Deprecated @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesWithLabel(String label, Map<String,Object> params)
Deprecated.Use getResourcesWithLabel(String label) Note: The param *params* is not used (has no effect)
-
getResourcesWithLabel
@NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesWithLabel(String label)
Returns resources matching by given *label*.
-
getResourcesMatchingScript
@NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> getResourcesMatchingScript(@NonNull org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript script, @CheckForNull Map<String,Object> params) throws ExecutionException
Returns a list of resources matching by given *script*.- Parameters:
script
- Scriptparams
- 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
@CheckForNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public LockableResource fromName(@CheckForNull String resourceName)
Returns resource matched by name. Returns null in case, the resource does not exists.
-
fromNames
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> fromNames(@Nullable List<String> names)
-
fromNames
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> fromNames(List<String> names, boolean createResource)
-
resourceExist
@NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean resourceExist(@CheckForNull String resourceName)
Checks if given resource exist.
-
queue
public boolean queue(List<LockableResource> resources, long queueItemId, String queueProjectName)
-
queue
@Deprecated @CheckForNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<LockableResource> queue(LockableResourcesStruct requiredResources, long queueItemId, String queueItemProject, int number, Map<String,Object> params, Logger log)
-
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 @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) 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
@Deprecated public boolean lock(List<LockableResource> resources, Run<?,?> build, @Nullable org.jenkinsci.plugins.workflow.steps.StepContext context)
Deprecated.
-
lock
@Deprecated public boolean lock(List<LockableResource> resources, Run<?,?> build, @Nullable org.jenkinsci.plugins.workflow.steps.StepContext context, @Nullable String logmessage, String variable, boolean inversePrecedence)
Deprecated.
-
lock
public boolean lock(List<LockableResource> resources, Run<?,?> build)
Try to lock the resource and return true if locked.
-
unlock
@Deprecated public void unlock(List<LockableResource> resourcesToUnLock, @Nullable Run<?,?> build)
Deprecated.
-
unlock
@Deprecated public void unlock(@Nullable List<LockableResource> resourcesToUnLock, @Nullable Run<?,?> build, boolean inversePrecedence)
Deprecated.
-
unlockNames
@Deprecated public void unlockNames(@Nullable List<String> resourceNamesToUnLock, @Nullable Run<?,?> build, boolean inversePrecedence)
Deprecated.
-
unlockNames
public void unlockNames(@Nullable List<String> resourceNamesToUnLock, @Nullable Run<?,?> build)
-
getResourcesNames
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public static List<String> getResourcesNames(List<LockableResource> resources)
Returns names (IDs) of given *resources*.
-
getAllResourcesNames
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<String> getAllResourcesNames()
Returns names (IDs) off all existing resources (inclusive ephemeral)
-
getCurrentQueuedContext
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<QueuedContextStruct> getCurrentQueuedContext()
Returns current queue
-
createResource
public boolean createResource(@CheckForNull String name)
Creates the resource if it does not exist.
-
createResourceWithLabel
public boolean createResourceWithLabel(@CheckForNull String name, @CheckForNull String label)
-
createResourceWithLabelAndProperties
public boolean createResourceWithLabelAndProperties(@CheckForNull String name, @CheckForNull String label, Map<String,String> properties)
-
addResource
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean addResource(@Nullable LockableResource resource)
-
addResource
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean addResource(@Nullable LockableResource resource, boolean doSave)
-
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 classDescriptor<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.
-
changeQueueOrder
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void changeQueueOrder(String queueId, int newPosition) throws IOException
Change the order (position) of the given item in the queue- Throws:
IOException
-
configure
public boolean configure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject json)
- Overrides:
configure
in classGlobalConfiguration
-
getAvailableResources
public List<LockableResource> getAvailableResources(List<LockableResourcesStruct> requiredResourcesList)
-
getAvailableResources
public List<LockableResource> getAvailableResources(QueuedContextStruct entry)
-
removeResources
public void removeResources(List<LockableResource> toBeRemoved)
Function removes all given resources
-
getAvailableResources
public List<LockableResource> getAvailableResources(List<LockableResourcesStruct> requiredResourcesList, @Nullable PrintStream logger, @Nullable 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.
-
printLogs
public static void printLogs(String msg, Level level, Logger L, @Nullable PrintStream logger)
-
queueContext
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void queueContext(org.jenkinsci.plugins.workflow.steps.StepContext context, List<LockableResourcesStruct> requiredResources, String resourceDescription, String variableName, boolean inversePrecedence, int priority)
-
unqueueContext
public boolean unqueueContext(org.jenkinsci.plugins.workflow.steps.StepContext context)
-
get
public static LockableResourcesManager get()
-
save
public void save()
- Specified by:
save
in interfaceSaveable
- Overrides:
save
in classDescriptor<GlobalConfiguration>
-
getFirst
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public LockableResource getFirst()
For testing purpose.
-
-