Interface FlowControl

  • All Known Implementing Classes:
    AbstractAsynchronousAggregator, AbstractAsynchronousProcessor, AsynchronousAgent, AsynchronousAggregator, AsynchronousProcessor, ContinuousQueryCache.ConverterAsynchronousProcessor, SingleEntryAsynchronousProcessor, StreamingAsynchronousProcessor

    public interface FlowControl
    Communication facilities that provide an asynchronous (non-blocking) way of submitting data exchange requests commonly implement mechanisms of modulating the control flow for underlying data transfer units (e.g. messages or packets). Those mechanism usually include some type of request buffering and backlog detection.

    While in many cases it's desirable to automate the flow control algorithms, such automation may be sub-optimal (in a case of "auto-flush") or even completely objectionable (in a case of backlog-related delays if the caller is a part of an asynchronous communication flow by itself).

    FlowControl represents a facet of a communication end point that allows clients to opt-out from an automatic flow control and manually govern the rate of the request flow.

    Callers wishing to be exempt from automatic flow-control may declare themselves as non-blocking, code directly interacting with flow-control methods is expected to check if the calling thread has been marked as non-blocking and bypass automatic flow-control for such callers.

    Author:
    gg/mf/rhl 2013.01.09
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean checkBacklog​(Continuation<Void> continueNormal)
      Check for an excessive backlog and if the underlying communication channel is indeed clogged, call the specified continuation when the backlog is back to normal or the service terminates.
      long drainBacklog​(long cMillis)
      Check for an excessive backlog and allow blocking the calling thread for up to the specified amount of time.
      void flush()
      Ensure that any buffered asynchronous operations are dispatched to the underlying tier.
    • Method Detail

      • flush

        void flush()
        Ensure that any buffered asynchronous operations are dispatched to the underlying tier.

        Note: this is a non-blocking call.

      • drainBacklog

        long drainBacklog​(long cMillis)
        Check for an excessive backlog and allow blocking the calling thread for up to the specified amount of time.
        Parameters:
        cMillis - the maximum amount of time to wait (in milliseconds), or zero for infinite wait
        Returns:
        the remaining timeout or a negative value if timeout has occurred (the return of zero is only allowed for infinite timeout and indicates that the backlog is no longer excessive)
      • checkBacklog

        boolean checkBacklog​(Continuation<Void> continueNormal)
        Check for an excessive backlog and if the underlying communication channel is indeed clogged, call the specified continuation when the backlog is back to normal or the service terminates. It's important to remember that:
        1. The continuation could be called on any thread; concurrently with the calling thread or on the calling thread itself.
        2. The continuation is called if and only if this method returns true.
        3. The continuation must not make any blocking calls.
        Parameters:
        continueNormal - (optional) Continuation to be called when the backlog has been reduced back to normal
        Returns:
        true if the underlying communication channel is backlogged; false otherwise
        Since:
        Coherence 12.1.3