com.qualcomm.robotcore.hardware

## Interface I2cDeviceSynchReadHistory

- All Known Implementing Classes:
    I2cDeviceSynchImpl, I2cDeviceSynchImplOnSimple, I2cDeviceSynchReadHistoryImpl

      public interface I2cDeviceSynchReadHistory

  `I2cDeviceSynchReadHistory` provides a means by which one can be guaranteed to be informed of all data read by through an `I2cDeviceSynch`. This is provided by means of a queue into which all data retrieved is (optionally) be stored.

  This functionality can be useful in I2c devices in which the mere act of reading data causes state transitions in the actual device itself. For such devices, the history queue can (e.g.) assist the software driver layer for the device in reliably tracking the device state.

  Implementations of `I2cDeviceSynchReadHistory` are commonly retrieved by casting from an implementation of `I2cDeviceSynch` or `I2cDeviceSynchSimple` (but don't forget to first test using `instanceOf`).

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.concurrent.BlockingQueue<TimestampedI2cData>` | `getHistoryQueue()` (Advanced) Returns a queue into which, if requested, `TimestampedI2cData`s are (optionally) placed as they become available.
    `int` | `getHistoryQueueCapacity()` Returns the current capacity of the history queue.
    `void` | `setHistoryQueueCapacity(int capacity)` Sets the maximum number of `TimestampedI2cData`s that will simultaneously be stored in the history queue.

- - ### Method Detail

    - #### setHistoryQueueCapacity

          void setHistoryQueueCapacity(int capacity)

      Sets the maximum number of `TimestampedI2cData`s that will simultaneously be stored in the history queue. If the queue is full and new `TimestampedI2cData`s become available, older data will be discarded. The history queue initially has a capacity of zero.

      Note that calling this method invalidates any history queue retrieved previously through `getHistoryQueue()`.

      Parameters:
        `capacity` - the maximum number of items that may be stored in the history queue
      See Also:
        `getHistoryQueue()`, `getHistoryQueueCapacity()`

    - #### getHistoryQueueCapacity

          int getHistoryQueueCapacity()

      Returns the current capacity of the history queue.
      Returns:
        the current capacity of the history queue.
      See Also:
        `setHistoryQueueCapacity(int)`, `getHistoryQueue()`

    - #### getHistoryQueue

          java.util.concurrent.BlockingQueue<TimestampedI2cData> getHistoryQueue()

      (Advanced) Returns a queue into which, if requested, `TimestampedI2cData`s are (optionally) placed as they become available.

      To access these `TimestampedI2cData`s, call `setHistoryQueueCapacity(int)` to enable the history queue. Once enabled, the history queue can be accessed using `getHistoryQueue()` and the methods thereon used to access `TimestampedI2cData`s as they become available.

      When `setHistoryQueueCapacity(int)` is called, any history queue returned previously by `getHistoryQueue()` becomes invalid and must be re-fetched.

      Returns:
        a queue through which I2c `TimestampedI2cData`s may be retrieved.
      See Also:
        `setHistoryQueueCapacity(int)`