Package trclib.robotcore

Interface TrcExclusiveSubsystem

All Known Implementing Classes:
FtcCRServo, FtcDcMotor, FtcServo, TrcDifferentialServoWrist, TrcDriveBase, TrcIntake, TrcMecanumDriveBase, TrcMotor, TrcMotorGrabber, TrcPidConveyor, TrcServo, TrcServoGrabber, TrcShooter, TrcSimpleDriveBase, TrcSwerveDriveBase
public interface TrcExclusiveSubsystem
This interface defines methods for the subsystems to implement exclusive ownership support. A subsystem can be accessed by multiple callers unaware of each other. Exclusive ownership can be acquired before access will be granted. This will prevent other callers from interfering an in-progress operation by a different caller.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    TrcExclusiveSubsystem.OwnershipParams
    This class encapsulates all the parameters required to acquire and release exclusive ownership for the operation.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    acquireExclusiveAccess(String owner)
    This method acquires exclusive ownership of the subsystem if it's not already owned by somebody else.
    default TrcEvent
    acquireOwnership(String owner, TrcEvent completionEvent, TrcDbgTrace msgTracer)
    This method acquires exclusive access to the subsystem for the specified owner if the owner did not already have ownership.
    default boolean
    cancelExclusiveAccess()
    This method release exclusive ownership of the subsystem regardless who owns it.
    default String
    getCurrentOwner()
    This method returns the current owner of this subsystem.
    default boolean
    hasOwnership(String owner)
    This method checks if the caller has exclusive ownership of the subsystem.
    default boolean
    releaseExclusiveAccess(String owner)
    This method release exclusive ownership of the subsystem if the caller is indeed the owner.
    default void
    releaseOwnership(Object context)
    This method is an event callback to release exclusive ownership after the operation is completed or canceled.
    default boolean
    validateOwnership(String owner)
    This method checks if the caller has exclusive ownership of the subsystem.

  • Method Details

    • hasOwnership

      default boolean hasOwnership(String owner)
      This method checks if the caller has exclusive ownership of the subsystem. For backward compatibility with older code that's not aware of subsystem exclusive ownership, the owner parameter can be null. If the subsystem has no owner currently and the caller is not aware of exclusive ownership, the caller is considered to have acquired ownership. This means the caller is allowed to proceed with controlling the subsystem but if a new caller comes in and acquires the ownership of the subsystem while an operation is in progress, the operation will be interrupted and preempted by the new caller's operation. Therefore, callers unaware of exclusive ownership can start an operation on the subsystem but their operations are not guaranteed exclusive ownership.
      Parameters:
      owner - specifies the ID string of the caller, can be null if caller is unaware of exclusive ownership.
      Returns:
      true if caller has exclusive ownership of the subsystem, false otherwise.

    • getCurrentOwner

      default String getCurrentOwner()
      This method returns the current owner of this subsystem.
      Returns:
      current owner, null if no owner.

    • validateOwnership

      default boolean validateOwnership(String owner)
      This method checks if the caller has exclusive ownership of the subsystem. If not, it throws an exception. It throws an exception only if the caller is aware of exclusive ownership and the it doesn't currently own the subsystem. If the caller is unaware of exclusive ownership and the subsystem is owned by somebody else, it will just return false and not throw an exception. This is to ensure older code that's unaware of exclusive ownership will not hit an unexpected exception and will just fail quietly.
      Parameters:
      owner - specifies the ID string of the caller, can be null if caller is unaware of exclusive ownership.
      Returns:
      true if the caller currently owns the subsystem, false otherwise.
      Throws:
      IllegalStateException - if caller is not the owner of the subsystem.

    • acquireExclusiveAccess

      default boolean acquireExclusiveAccess(String owner)
      This method acquires exclusive ownership of the subsystem if it's not already owned by somebody else.
      Parameters:
      owner - specifies the ID string of the caller requesting ownership.
      Returns:
      true if successfully acquired ownership, false otherwise.

    • releaseExclusiveAccess

      default boolean releaseExclusiveAccess(String owner)
      This method release exclusive ownership of the subsystem if the caller is indeed the owner.
      Parameters:
      owner - specifies the ID string of the caller releasing ownership.
      Returns:
      true if successfully releasing ownership, false otherwise.

    • cancelExclusiveAccess

      default boolean cancelExclusiveAccess()
      This method release exclusive ownership of the subsystem regardless who owns it.
      Returns:
      true if successfully releasing ownership, false if no owner.

    • acquireOwnership

      default TrcEvent acquireOwnership(String owner, TrcEvent completionEvent, TrcDbgTrace msgTracer)
      This method acquires exclusive access to the subsystem for the specified owner if the owner did not already have ownership. If successfully acquired exclusive access, it will return an event that the owner must signal when exclusive access is no longer needed. At that time, the exclusive access will be released for the owner.
      Parameters:
      owner - specifies the owner who wishes to acquire exclusive access, can be null if not requiring exclusive access in which case this call is a no-op.
      completionEvent - specifies the original event that will be signaled when the operation is completed. This event will be signaled for the owner when the exclusive access is released.
      Returns:
      release ownership event that the caller must signal when exclusive access is no longer needed. Typically, it replaces the original completion event of the operation so that when the operation is completed, the caller will signal this event to release the exclusive access and it will then signal the original completion event for the caller.

    • releaseOwnership

      default void releaseOwnership(Object context)
      This method is an event callback to release exclusive ownership after the operation is completed or canceled. It will also signal the original completion event for the owner.
      Parameters:
      context - specifies the releaseOwnership parameters.