Package com.yahoo.processing.response

Interface DataList<DATATYPE extends Data>

  • All Superinterfaces:
    Data, com.yahoo.component.provider.Freezable, com.yahoo.component.provider.ListenableFreezable
    All Known Implementing Classes:
    AbstractDataList, ArrayDataList, ProcessorLibrary.UnorderedArrayDataList
    public interface DataList<DATATYPE extends Data>
extends Data
    A list of data items created due to a processing request. This list is itself a data item, allowing data items to be organized into a composite tree.

    A data list can be frozen even though its child data items are not. When a datalist is frozen the only permissible write operation is to add new items to the end of the list.

    Content in a frozen list may be returned to the requesting client immediately by the underlying engine, even if the Response owning the list is not returned yet.

    Author:
    bratseth

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      DATATYPE add​(DATATYPE data)
      Adds a child data item to this.
      void addDataListener​(java.lang.Runnable runnable)
      Adds a listener which is invoked every time data is added to this list.
      java.util.List<DATATYPE> asList()
      Returns the content of this as a List.
      default void close()
      Notify this list that is will never be accessed again, neither for read nor write.
      com.google.common.util.concurrent.ListenableFuture<DataList<DATATYPE>> complete()
      Returns a future in which all incoming data in this has become available.
      DATATYPE get​(int index)  
      IncomingData<DATATYPE> incoming()
      Returns the buffer of incoming/future data to this list.

      • Methods inherited from interface com.yahoo.processing.response.Data

        request

      • Methods inherited from interface com.yahoo.component.provider.Freezable

        freeze, isFrozen

      • Methods inherited from interface com.yahoo.component.provider.ListenableFreezable

        addFreezeListener

    • Method Detail

      • add

        DATATYPE add​(DATATYPE data)
        Adds a child data item to this.
        Parameters:
        data - the data to add to this
        Returns:
        the input data instance, for chaining

      • asList

        java.util.List<DATATYPE> asList()
        Returns the content of this as a List. The returned list is either a read-only snapshot or an editable reference to the content of this. If the returned list is editable and this is frozen, the only allowed operation is to add new items to the end of the list.

      • incoming

        IncomingData<DATATYPE> incoming()
        Returns the buffer of incoming/future data to this list. This can be used to provide data to this list from other threads, after its creation, and to consume, wait for or be notified upon the arrival of such data.

        Some list instances do not support late incoming data, such lists responds to read calls to IncomingData as expected and without incurring any synchronization, and throws an exception on write calls.

      • complete

        com.google.common.util.concurrent.ListenableFuture<DataList<DATATYPE>> complete()
        Returns a future in which all incoming data in this has become available. This has two uses:
        • Calling get(int) on this future will block (if necessary) until all incoming data has arrived, transfer that data from the incoming buffer into this list and invoke any listeners on this event on the calling thread.
        • Adding a listener on this future will cause it to be called when completion().get() is called, after the incoming data has been moved to this thread and before the get() call returns.

        Note that if no thread calls completed().get(), this future will never occur.

        Any data list consumer who wishes to make sure it sees the complete data for this list must call dataList.complete().get() before consuming this list. If a guaranteed non-blocking call to this method is desired, register a listener on the future where all data is available for draining (that is, on dataList.incoming().completed()) and resume by calling this method from the listener.

        Making this call on a list which does not support future data always returns immediately and causes no memory synchronization cost.

      • addDataListener

        void addDataListener​(java.lang.Runnable runnable)
        Adds a listener which is invoked every time data is added to this list. The listener is always invoked on the same thread which is adding the data, and hence it can modify this list freely without synchronization.

      • close

        default void close()
        Notify this list that is will never be accessed again, neither for read nor write. Implementations can override this as an optimization to release any data held in the list for garbage collection. This default implementation does nothing.