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.)

- ## Nested Class Summary

  Nested Classes
  Modifier and Type | Interface | Description
  --- | --- | ---
  `static interface` | `Scheduler.Client` | Defines callback methods for clients of the resource scheduler.
  `static interface` | `Scheduler.Module` | A scheduler module.

- ## Field Summary

  Fields
  Modifier and Type | Field | Description
  --- | --- | ---
  `static java.lang.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.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `void` | `allocate​(Scheduler.Client client, java.util.Set<TCSResource<?>> resources)` | Requests allocation of the given resources.
  `void` | `allocateNow​(Scheduler.Client client, java.util.Set<TCSResource<?>> resources)` | Informs the scheduler that a set of resources are to be allocated for the given client immediately.
  `void` | `claim​(Scheduler.Client client, java.util.List<java.util.Set<TCSResource<?>>> resourceSequence)` | Sets/Updates the resource claim for a vehicle.
  `default void` | `clearPendingAllocations​(Scheduler.Client client)` | Releases all pending resource allocations for the given client.
  `void` | `free​(Scheduler.Client client, java.util.Set<TCSResource<?>> resources)` | Releases a set of resources allocated by a client.
  `void` | `freeAll​(Scheduler.Client client)` | Releases all resources allocated by the given client.
  `java.util.Map<java.lang.String,​java.util.Set<TCSResource<?>>>` | `getAllocations()` | Returns all resource allocations as a map of client IDs to resources.
  `void` | `preparationSuccessful​(Scheduler.Module module, Scheduler.Client client, java.util.Set<TCSResource<?>> resources)` | Informs the scheduler that a set of resources was successfully prepared in order of allocating them to a client.
  `default void` | `reschedule()` | Explicitly triggers a rescheduling run during which the scheduler tries to allocate resources for all waiting clients.
  `default void` | `unclaim​(Scheduler.Client client)` | Deprecated. Use `claim(org.opentcs.components.kernel.Scheduler.Client, java.util.List)` with an empty list, instead.
  `default void` | `updateProgressIndex​(Scheduler.Client client, int index)` | Deprecated. Stick to `claim()` and `allocate()`.

  ### Methods inherited from interface org.opentcs.components.Lifecycle

  `initialize, isInitialized, terminate`

- ## Field Details

  - ### PROPKEY_BLOCK_ENTRY_DIRECTION

    static final java.lang.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.
    See Also:
      Constant Field Values

- ## 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.

    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.
    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.
    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.
    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)`

  - ### 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.
    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.
    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.
    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.
    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.

  - ### 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.
    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.
    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.