Package org.opentcs.components.kernel

Schnittstelle Scheduler

Alle Superschnittstellen:
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.)

  • Felddetails

    • PROPKEY_BLOCK_ENTRY_DIRECTION

      static final String PROPKEY_BLOCK_ENTRY_DIRECTION
      The key of a path property defining the direction in which a vehicle is entering a block when it's taking the path.
      Siehe auch:

  • Methodendetails

    • claim

      void claim(@Nonnull Scheduler.Client client, @Nonnull List<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.

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

    • allocate

      void allocate(@Nonnull Scheduler.Client client, @Nonnull Set<TCSResource<?>> resources) throws 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.

      Parameter:
      client - The client requesting the resources.
      resources - The resources to be allocated.
      Löst aus:
      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.
      Siehe auch:

    • mayAllocateNow

      boolean mayAllocateNow(@Nonnull Scheduler.Client client, @Nonnull 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.

      Parameter:
      client - The client requesting the resources.
      resources - The requested resources.
      Gibt zurück:
      true if the given resources are safe to be allocated by the given client, otherwise false.

    • allocateNow

      void allocateNow(@Nonnull Scheduler.Client client, @Nonnull 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.

      Parameter:
      client - The client requesting the resources.
      resources - The resources requested.
      Löst aus:
      ResourceAllocationException - If it's impossible to allocate the given set of resources for the given client.

    • free

      void free(@Nonnull Scheduler.Client client, @Nonnull 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.

      Parameter:
      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.

      Parameter:
      client - The client.

    • clearPendingAllocations

      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.

      Parameter:
      client - The client.

    • reschedule

      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 Map<String,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.

      Gibt zurück:
      All resource allocations as a map of client IDs to resources.

    • preparationSuccessful

      void preparationSuccessful(@Nonnull Scheduler.Module module, @Nonnull Scheduler.Client client, @Nonnull 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.

      Parameter:
      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.