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, Loadable, OnMaster
@Extension public class LockableResourcesManager extends GlobalConfiguration

  • Field Details

    • syncResources

      public static final transient Object syncResources
      Object to synchronized operations over LRM

  • Constructor Details

    • LockableResourcesManager

      public LockableResourcesManager()
      C-tor

  • Method Details

    • 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

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) 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.

    • 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 - 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

      @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)
      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 @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> resourcesToLock, Run<?,?> build)
      Try to lock the resource and return true if locked.

    • unlockBuild

      public void unlockBuild(@Nullable Run<?,?> build)

    • unlockNames

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

    • unlockResources

      public void unlockResources(List<LockableResource> resourcesToUnLock)

    • unlockResources

      public void unlockResources(List<LockableResource> resourcesToUnLock, 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 class Descriptor<GlobalConfiguration>

    • reset

      public void reset(List<LockableResource> resources)

    • recycle

      public void recycle(List<LockableResource> resources)
      Make the lockable resource reusable 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 class GlobalConfiguration

    • 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 interface Saveable
      Overrides:
      save in class Descriptor<GlobalConfiguration>

    • getFirst

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public LockableResource getFirst()
      For testing purpose.