Package org.opentcs.components.kernel

Interface Scheduler

All Superinterfaces:
Lifecycle
public interface Scheduler
extends Lifecycle
Manages resources used by clients (vehicles) to help prevent both collisions and deadlocks.

Every client usually interacts with the Scheduler according to the following workflow:

  1. Initially, the client calls allocateNow() when a vehicle pops up somewhere in the driving course. This usually happens either upon kernel startup or when a vehicle communicates its current position to the kernel for the first time.
  2. Once a transport order is assigned to a vehicle, the client calls claim() with the complete sequence of resource sets the vehicle needs to process the transport order - usually each containing a point and the path leading to it.
  3. As the vehicle processes the transport order, the client subsequently calls allocate() for resources needed next (for reaching the next point on the route). The Scheduler asynchronously calls back either Scheduler.Client.allocationSuccessful(java.util.Set) or Scheduler.Client.allocationFailed(java.util.Set), informing the client about the result. Upon allocating the resources for the client, it also implicitly removes them from the head of the client's claim sequence.
  4. As the vehicle passes points (and paths) on the route, the client calls free() for resources it does not need any more, allowing these resources to be allocated by other clients.

At the end of this process, the client's claim sequence is empty, and only the most recently allocated resources are still assigned to it, reflecting the vehicle's current position. (If the vehicle has disappeared from the driving course after processing the transport order, the client would call freeAll() to inform the Scheduler about this.)

  • Field Details

  • Method Details

    • claim

      void claim​(@Nonnull Scheduler.Client client, @Nonnull java.util.List<java.util.Set<TCSResource<?>>> resourceSequence)
      Sets/Updates the resource claim for a vehicle.

      Claimed resources are resources that a vehicle will eventually require for executing its movements in the future, but for which it does not request allocation, yet. Claiming resources provides information to the scheduler about future allocations and their intended order, allowing the scheduler to consider these information for its resource planning.

      Resources can be claimed by multiple vehicles at the same time. This is different from allocations: Only a single vehicle can allocate a resource at the same time.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client claiming the resources.
      resourceSequence - The sequence of resources claimed. May be empty to clear the client's claim.

    • updateProgressIndex

      @Deprecated @ScheduledApiChange(when="6.0", details="Will be removed.") default void updateProgressIndex​(@Nonnull Scheduler.Client client, int index) throws java.lang.IllegalArgumentException
      Deprecated.
      Stick to claim() and allocate(). They implicitly update both the set of claimed and the set of allocated resources.
      Notifies the scheduler that the given client has now reached the given index in its claimed resource sequence, and that the client does not need the resources preceding the index in the sequence, any more.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client.
      index - The new index in the client's claimed resource sequence.
      Throws:
      java.lang.IllegalArgumentException - If the client does not hold a claim, or if the new index is larger than a valid index in its claim's resource sequence, or if the new index is not larger than the current index.

    • unclaim

      @Deprecated @ScheduledApiChange(when="6.0", details="Will be removed.") default void unclaim​(@Nonnull Scheduler.Client client) throws java.lang.IllegalArgumentException
      Deprecated.
      Use claim(org.opentcs.components.kernel.Scheduler.Client, java.util.List) with an empty list, instead.
      Unclaims a set of resources claimed by a vehicle.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client unclaiming the resources.
      Throws:
      java.lang.IllegalArgumentException - If the given client does not hold a claim.

    • allocate

      void allocate​(@Nonnull Scheduler.Client client, @Nonnull java.util.Set<TCSResource<?>> resources) throws java.lang.IllegalArgumentException
      Requests allocation of the given resources. The client will be informed via a callback to Scheduler.Client.allocationSuccessful(java.util.Set) or Scheduler.Client.allocationFailed(java.util.Set) whether the allocation was successful or not.
      • Clients may only allocate resources in the order they have previously claim()ed them.
      • Upon allocation, the scheduler will implicitly remove the set of allocated resources from (the head of) the client's claim sequence.
      • As a result, a client may only allocate the set of resources at the head of its claim sequence.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client requesting the resources.
      resources - The resources to be allocated.
      Throws:
      java.lang.IllegalArgumentException - If the set of resources to be allocated is not equal to the next set in the sequence of currently claimed resources, or if the client has already requested resources that have not yet been granted.
      See Also:
      claim(org.opentcs.components.kernel.Scheduler.Client, java.util.List)

    • mayAllocateNow

      @ScheduledApiChange(when="6.0", details="Default implementation will be removed.") default boolean mayAllocateNow​(@Nonnull Scheduler.Client client, @Nonnull java.util.Set<TCSResource<?>> resources)
      Checks if the resulting system state is safe if the given set of resources would be allocated by the given client immediately.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client requesting the resources.
      resources - The requested resources.
      Returns:
      true if the given resources are safe to be allocated by the given client, otherwise false.

    • allocateNow

      void allocateNow​(@Nonnull Scheduler.Client client, @Nonnull java.util.Set<TCSResource<?>> resources) throws ResourceAllocationException
      Informs the scheduler that a set of resources are to be allocated for the given client immediately.

      Note the following:

      • This method should only be called in urgent/emergency cases, for instance if a vehicle has been moved to a different point manually, which has to be reflected by resource allocation in the scheduler.
      • Unlike allocate(), this method does not block, i.e. the operation happens synchronously.
      • This method does not implicitly deallocate or unclaim any other resources for the client.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client requesting the resources.
      resources - The resources requested.
      Throws:
      ResourceAllocationException - If it's impossible to allocate the given set of resources for the given client.

    • free

      void free​(@Nonnull Scheduler.Client client, @Nonnull java.util.Set<TCSResource<?>> resources)
      Releases a set of resources allocated by a client.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client releasing the resources.
      resources - The resources released. Any resources in the given set not allocated by the given client are ignored.

    • freeAll

      void freeAll​(@Nonnull Scheduler.Client client)
      Releases all resources allocated by the given client.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client.

    • clearPendingAllocations

      @ScheduledApiChange(when="6.0", details="Default implementation will be removed.") default void clearPendingAllocations​(@Nonnull Scheduler.Client client)
      Releases all pending resource allocations for the given client.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      client - The client.

    • reschedule

      @ScheduledApiChange(when="6.0", details="Default implementation will be removed.") default void reschedule()
      Explicitly triggers a rescheduling run during which the scheduler tries to allocate resources for all waiting clients.

      This method is supposed to be called only from the kernel executor thread.

    • getAllocations

      @Nonnull java.util.Map<java.lang.String,​java.util.Set<TCSResource<?>>> getAllocations()
      Returns all resource allocations as a map of client IDs to resources.

      This method is supposed to be called only from the kernel executor thread.

      Returns:
      All resource allocations as a map of client IDs to resources.

    • preparationSuccessful

      void preparationSuccessful​(@Nonnull Scheduler.Module module, @Nonnull Scheduler.Client client, @Nonnull java.util.Set<TCSResource<?>> resources)
      Informs the scheduler that a set of resources was successfully prepared in order of allocating them to a client.

      This method is supposed to be called only from the kernel executor thread.

      Parameters:
      module - The module a preparation was necessary for.
      client - The client that requested the preparation/allocation.
      resources - The resources that are now prepared for the client.