Class LockableResourcesManager

    • Field Detail

      • syncResources

        public static final transient Object syncResources
        Object to synchronized operations over LRM
    • Constructor Detail

      • LockableResourcesManager

        public LockableResourcesManager()
        C-tor
    • 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 - 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.
      • 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.
      • 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).
      • 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 class GlobalConfiguration
      • 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.
      • 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)
      • getFirst

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