Interface MessagePassingQueue<T>

    • Method Detail

      • offer

        boolean offer​(T e)
        Called from a producer thread subject to the restrictions appropriate to the implementation and according to the Queue.offer(Object) interface.
        Parameters:
        e - not null, will throw NPE if it is
        Returns:
        true if element was inserted into the queue, false iff full
      • poll

        T poll()
        Called from the consumer thread subject to the restrictions appropriate to the implementation and according to the Queue.poll() interface.
        Returns:
        a message from the queue if one is available, null iff empty
      • peek

        T peek()
        Called from the consumer thread subject to the restrictions appropriate to the implementation and according to the Queue.peek() interface.
        Returns:
        a message from the queue if one is available, null iff empty
      • size

        int size()
        This method's accuracy is subject to concurrent modifications happening as the size is estimated and as such is a best effort rather than absolute value. For some implementations this method may be O(n) rather than O(1).
        Returns:
        number of messages in the queue, between 0 and Integer.MAX_VALUE but less or equals to capacity (if bounded).
      • clear

        void clear()
        Removes all items from the queue. Called from the consumer thread subject to the restrictions appropriate to the implementation and according to the Collection.clear() interface.
      • isEmpty

        boolean isEmpty()
        This method's accuracy is subject to concurrent modifications happening as the observation is carried out.
        Returns:
        true if empty, false otherwise
      • capacity

        int capacity()
        Returns:
        the capacity of this queue or UNBOUNDED_CAPACITY if not bounded
      • relaxedOffer

        boolean relaxedOffer​(T e)
        Called from a producer thread subject to the restrictions appropriate to the implementation. As opposed to Queue.offer(Object) this method may return false without the queue being full.
        Parameters:
        e - not null, will throw NPE if it is
        Returns:
        true if element was inserted into the queue, false if unable to offer
      • relaxedPoll

        T relaxedPoll()
        Called from the consumer thread subject to the restrictions appropriate to the implementation. As opposed to Queue.poll() this method may return null without the queue being empty.
        Returns:
        a message from the queue if one is available, null if unable to poll
      • relaxedPeek

        T relaxedPeek()
        Called from the consumer thread subject to the restrictions appropriate to the implementation. As opposed to Queue.peek() this method may return null without the queue being empty.
        Returns:
        a message from the queue if one is available, null if unable to peek
      • drain

        int drain​(MessagePassingQueue.Consumer<T> c,
                  int limit)
        Remove up to limit elements from the queue and hand to consume. This should be semantically similar to:

        
           M m;
           int i = 0;
           for(;i < limit && (m = relaxedPoll()) != null; i++){
             c.accept(m);
           }
           return i;
         

        There's no strong commitment to the queue being empty at the end of a drain. Called from a consumer thread subject to the restrictions appropriate to the implementation.

        WARNING: Explicit assumptions are made with regards to MessagePassingQueue.Consumer.accept(T) make sure you have read and understood these before using this method.

        Returns:
        the number of polled elements
        Throws:
        java.lang.IllegalArgumentException - c is null
        java.lang.IllegalArgumentException - if limit is negative
      • fill

        int fill​(MessagePassingQueue.Supplier<T> s,
                 int limit)
        Stuff the queue with up to limit elements from the supplier. Semantically similar to:

        
           for(int i=0; i < limit && relaxedOffer(s.get()); i++);
         

        There's no strong commitment to the queue being full at the end of a fill. Called from a producer thread subject to the restrictions appropriate to the implementation. WARNING: Explicit assumptions are made with regards to MessagePassingQueue.Supplier.get() make sure you have read and understood these before using this method.

        Returns:
        the number of offered elements
        Throws:
        java.lang.IllegalArgumentException - s is null
        java.lang.IllegalArgumentException - if limit is negative
      • drain

        int drain​(MessagePassingQueue.Consumer<T> c)
        Remove all available item from the queue and hand to consume. This should be semantically similar to:
         M m;
         while((m = relaxedPoll()) != null){
         c.accept(m);
         }
         
        There's no strong commitment to the queue being empty at the end of a drain. Called from a consumer thread subject to the restrictions appropriate to the implementation.

        WARNING: Explicit assumptions are made with regards to MessagePassingQueue.Consumer.accept(T) make sure you have read and understood these before using this method.

        Returns:
        the number of polled elements
        Throws:
        java.lang.IllegalArgumentException - c is null
      • fill

        int fill​(MessagePassingQueue.Supplier<T> s)
        Stuff the queue with elements from the supplier. Semantically similar to:
         while(relaxedOffer(s.get());
         
        There's no strong commitment to the queue being full at the end of a fill. Called from a producer thread subject to the restrictions appropriate to the implementation.

        Unbounded queues will fill up the queue with a fixed amount rather than fill up to oblivion. WARNING: Explicit assumptions are made with regards to MessagePassingQueue.Supplier.get() make sure you have read and understood these before using this method.

        Returns:
        the number of offered elements
        Throws:
        java.lang.IllegalArgumentException - s is null
      • drain

        void drain​(MessagePassingQueue.Consumer<T> c,
                   MessagePassingQueue.WaitStrategy wait,
                   MessagePassingQueue.ExitCondition exit)
        Remove elements from the queue and hand to consume forever. Semantically similar to:

          int idleCounter = 0;
          while (exit.keepRunning()) {
              E e = relaxedPoll();
              if(e==null){
                  idleCounter = wait.idle(idleCounter);
                  continue;
              }
              idleCounter = 0;
              c.accept(e);
          }
         

        Called from a consumer thread subject to the restrictions appropriate to the implementation.

        WARNING: Explicit assumptions are made with regards to MessagePassingQueue.Consumer.accept(T) make sure you have read and understood these before using this method.

        Throws:
        java.lang.IllegalArgumentException - c OR wait OR exit are null
      • fill

        void fill​(MessagePassingQueue.Supplier<T> s,
                  MessagePassingQueue.WaitStrategy wait,
                  MessagePassingQueue.ExitCondition exit)
        Stuff the queue with elements from the supplier forever. Semantically similar to:

         
          int idleCounter = 0;
          while (exit.keepRunning()) {
              E e = s.get();
              while (!relaxedOffer(e)) {
                  idleCounter = wait.idle(idleCounter);
                  continue;
              }
              idleCounter = 0;
          }
         
         

        Called from a producer thread subject to the restrictions appropriate to the implementation. The main difference being that implementors MUST assure room in the queue is available BEFORE calling MessagePassingQueue.Supplier.get(). WARNING: Explicit assumptions are made with regards to MessagePassingQueue.Supplier.get() make sure you have read and understood these before using this method.

        Throws:
        java.lang.IllegalArgumentException - s OR wait OR exit are null