Class AgentUsageRegistry

java.lang.Object
org.jenkinsci.plugins.vsphere.AgentUsageRegistry

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @Extension public final class AgentUsageRegistry extends Object
Owns how many "limited builds" each vSphere agent has done, so that the agent can be recycled once it reaches its limit. All the agents of all the clouds share this one registry, which is keyed by the name of the agent (Jenkins keeps those unique).

An agent that is replaced when its configuration is saved keeps its usage; one that is deleted, or created anew with a name that was used before, starts from nothing. What a run is counted against is remembered per entry, not per name, so a run that was counted on an agent that has since been replaced by a different one of the same name does not recycle the new one.

The state is kept in memory under one lock, which is never held while Jenkins is called (to find out whether a run is still building, for instance), so it is safe to use from the threads of any build. Recycling an agent is up to the caller, outside of that lock.

  • Constructor Details

    • AgentUsageRegistry

      public AgentUsageRegistry()
      The registry of Jenkins, which saves the usage in the home of Jenkins.
  • Method Details

    • get

      public static AgentUsageRegistry get()
    • acquire

      public AgentUsageRegistry.Acquired acquire(String node, int limit, Run<?,?> run)
      Counts the run against the agent, unless the agent has no limit, the run is over, it is counted already or the agent is at its limit.
    • release

      public AgentUsageRegistry.Released release(Run<?,?> run)
      The run is over: it is not counted as using its agent any more, which keeps the use it was counted for.
    • release

      public AgentUsageRegistry.Released release(String runId)
      As release(Run), with the run known by its id.
    • isRetiring

      public boolean isRetiring(String node, int limit)
      The agent has used all its limit uses (none means never). Whether it is busy is another matter.
    • holdsCountedRuns

      public boolean holdsCountedRuns(String node)
      Some run counted on the agent has not ended.
    • tryBeginRecycle

      public AgentUsageRegistry.RecycleToken tryBeginRecycle(String node, int limit)
      Takes the recycling of the agent, if it is due: it has used all its limit uses, no run counted on it is still using it, and it is not being recycled already. Null if not. The caller has to end it with endRecycle(org.jenkinsci.plugins.vsphere.AgentUsageRegistry.RecycleToken, boolean).
    • countedRunIds

      public List<String> countedRunIds(String node)
      The ids of the runs counted on the agent that have not ended.
    • isCountedOn

      public boolean isCountedOn(String runId, String node)
      The run is counted on the agent as it is now, not on an earlier one of the same name.
    • projectedCount

      public int projectedCount(String node, Collection<String> busyRunIds)
      How many uses the agent will have once the work it was handed has started: what it has, and one for each run among the busyRunIds that is not counted anywhere yet. A null is work that is not known to be of any run, which has to be taken as a use of its own.
    • isRecycling

      public boolean isRecycling(String node)
    • isAwaitingDisconnect

      public boolean isAwaitingDisconnect(String node)
      The agent is being recycled and the disconnect has not said yet how it went.
    • completeRecycle

      public boolean completeRecycle(String node, AgentUsageRegistry.RecycleOutcome outcome)
      Says how the recycling of the agent went. Only the first to say it counts, so it may be said any number of times. The recycling goes on until endRecycle(org.jenkinsci.plugins.vsphere.AgentUsageRegistry.RecycleToken, boolean). Returns whether this was the first.
    • endRecycle

      public void endRecycle(AgentUsageRegistry.RecycleToken token, boolean reset)
      The recycling is over. If it reset, the agent starts from nothing again, unless it was replaced in the meantime by a different one of the same name.
    • nodeOf

      public String nodeOf(Run<?,?> run)
      The name of the agent the run is counted on, or null if it is not counted.
    • isCounted

      public boolean isCounted(Run<?,?> run)
    • isCounted

      public boolean isCounted(String runId)
    • count

      public int count(String node)
    • reset

      public void reset(String node)
      Starts the agent from nothing again, as if it were new. The runs counted on it keep counting on it.
    • forget

      public void forget(String node)
      The agent is gone, or a new one takes its name: forget it. The runs counted on it become stale.
    • rename

      public void rename(String from, String to)
      The agent was renamed: its usage and the runs counted on it go with it.
    • reconcile

      public void reconcile(String node, int limit)
      The limit of the agent may have changed. With no limit there is nothing to remember. An agent that is at or over its new limit keeps its count: it is recycled once nothing is using it.
    • snapshot

      public Map<String,Integer> snapshot()
      A copy of the usage of the agents that have any.
    • loadAtStartup

      @Initializer(after=SYSTEM_CONFIG_LOADED) public static void loadAtStartup()
      Takes the saved usage once the agents are known.
    • pruneAtStartup

      @Initializer(after=JOB_CONFIG_ADAPTED, before=COMPLETED) public static void pruneAtStartup()
      Once the builds are loaded, the runs that were saved as counted and are not building are forgotten. A Pipeline that has not been resumed yet is building, as far as its run is concerned, so it is kept.
    • pruneFinishedRuns

      public void pruneFinishedRuns()
      Forgets the counted runs that are not building any more, which did not get to say they were over.
    • saveAtShutdown

      @Terminator public static void saveAtShutdown()
      Saves what is pending before Jenkins stops.