Package kilim

Class Mailbox<T>

  • All Implemented Interfaces:
    EventPublisher, PauseReason
    public class Mailbox<T>
extends java.lang.Object
implements PauseReason, EventPublisher
    This is a typed buffer that supports multiple producers and a single consumer. It is the basic construct used for tasks to interact and synchronize with each other (as opposed to direct java calls or static member variables). put() and get() are the two essential functions. We use the term "block" to mean thread block, and "pause" to mean fiber pausing. The suffix "nb" on some methods (such as getnb()) stands for non-blocking. Both put() and get() have blocking and non-blocking variants in the form of putb(), putnb

    • Field Detail

      • msgs

        T[] msgs

      • iprod

        private int iprod

      • icons

        private int icons

      • numMsgs

        private int numMsgs

      • maxMsgs

        private int maxMsgs

      • spaceAvailble

        public static final Event spaceAvailble

      • messageAvailable

        public static final Event messageAvailable

      • timedOut

        public static final Event timedOut

    • Constructor Detail

      • Mailbox

        public Mailbox()

      • Mailbox

        public Mailbox​(int initialSize)

      • Mailbox

        public Mailbox​(int initialSize,
               int maxSize)

    • Method Detail

      • get

        public T get​(EventSubscriber eo)
        Non-blocking, nonpausing get.
        Parameters:
        eo - . If non-null, registers this observer and calls it with a MessageAvailable event when a put() is done.
        Returns:
        buffered message if there's one, or null

      • put

        public boolean put​(T msg,
                   EventSubscriber eo)
        Non-blocking, nonpausing put.
        Parameters:
        eo - . If non-null, registers this observer and calls it with an SpaceAvailable event when there's space.
        Returns:
        buffered message if there's one, or null
        See Also:
        putnb(Object), putb(Object)

      • getnb

        public T getnb()
        Get, don't pause or block.
        Returns:
        stored message, or null if no message found.

      • get

        public T get​(long timeoutMillis)
      throws Pausable
        Returns:
        non-null message, or null if timed out.
        Throws:
        Pausable

      • untilHasMessage

        public void untilHasMessage()
                     throws Pausable
        Block caller until at least one message is available.
        Throws:
        Pausable

      • untilHasMessages

        public void untilHasMessages​(int num)
                      throws Pausable
        Block caller until num messages are available.
        Parameters:
        num -
        Throws:
        Pausable

      • hasMessage

        public boolean hasMessage​(Task eo)

      • hasMessages

        public boolean hasMessages​(int num,
                           Task eo)

      • peek

        public T peek​(int idx)

      • remove

        public T remove​(int idx)

      • messages

        public java.lang.Object[] messages()

      • select

        public static int select​(Mailbox... mboxes)
                  throws Pausable
        Takes an array of mailboxes and returns the index of the first mailbox that has a message. It is possible that because of race conditions, an earlier mailbox in the list may also have received a message.
        Throws:
        Pausable

      • addSpaceAvailableListener

        public void addSpaceAvailableListener​(EventSubscriber spcSub)

      • removeSpaceAvailableListener

        public void removeSpaceAvailableListener​(EventSubscriber spcSub)

      • addMsgAvailableListener

        public void addMsgAvailableListener​(EventSubscriber msgSub)

      • removeMsgAvailableListener

        public void removeMsgAvailableListener​(EventSubscriber msgSub)

      • putnb

        public boolean putnb​(T msg)
        Attempt to put a message, and return true if successful. The thread is not blocked, nor is the task paused under any circumstance.

      • put

        public void put​(T msg)
         throws Pausable
        put a non-null message in the mailbox, and pause the calling task until the mailbox has space
        Throws:
        Pausable

      • put

        public boolean put​(T msg,
                   int timeoutMillis)
            throws Pausable
        put a non-null message in the mailbox, and pause the calling task for timeoutMillis if the mailbox is full.
        Throws:
        Pausable

      • putb

        public void putb​(T msg)

      • putb

        public boolean putb​(T msg,
                    long timeoutMillis)
        put a non-null message in the mailbox, and block the calling thread for timeoutMillis if the mailbox is full
        Returns:
        true if the message was successfully put in the mailbox

      • size

        public int size()

      • hasMessage

        public boolean hasMessage()

      • hasSpace

        public boolean hasSpace()

      • getb

        public T getb()
        retrieve a message, blocking the thread indefinitely. Note, this is a heavyweight block, unlike #get() that pauses the Fiber but doesn't block the thread.

      • getb

        public T getb​(long timeoutMillis)
        retrieve a msg, and block the Java thread for the time given.
        Parameters:
        millis - . max wait time
        Returns:
        null if timed out.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • isValid

        public boolean isValid​(Task t)
        Description copied from interface: PauseReason
        True if the given task's reason for pausing is still valid.
        Specified by:
        isValid in interface PauseReason