kilim

Class Mailbox<T>

java.lang.Object

kilim.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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Mailbox.BlockingSubscriber

Field Summary

Fields

Modifier and Type	Field and Description
static Event	messageAvailable
static int	MSG_AVAILABLE
static int	SPACE_AVAILABLE
static Event	spaceAvailble
static int	TIMED_OUT
static Event	timedOut

Constructor Summary

Constructors

Constructor and Description
Mailbox()
Mailbox(int initialSize)
Mailbox(int initialSize, int maxSize)

Method Summary

Modifier and Type	Method and Description
void	addMsgAvailableListener(EventSubscriber msgSub)
void	addSpaceAvailableListener(EventSubscriber spcSub)
T	get()
T	get(EventSubscriber eo) Non-blocking, nonpausing get.
T	get(long timeoutMillis)
T	getb() retrieve a message, blocking the thread indefinitely.
T	getb(long timeoutMillis) retrieve a msg, and block the Java thread for the time given.
T	getnb() Get, don't pause or block.
boolean	hasMessage()
boolean	hasMessage(Task eo)
boolean	hasMessages(int num, Task eo)
boolean	hasSpace()
boolean	isValid(Task t) True if the given task's reason for pausing is still valid.
java.lang.Object[]	messages()
T	peek(int idx)
void	put(T msg) put a non-null message in the mailbox, and pause the calling task until the mailbox has space
boolean	put(T msg, EventSubscriber eo) Non-blocking, nonpausing put.
boolean	put(T msg, int timeoutMillis) put a non-null message in the mailbox, and pause the calling task for timeoutMillis if the mailbox is full.
void	putb(T msg)
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
boolean	putnb(T msg) Attempt to put a message, and return true if successful.
T	remove(int idx)
void	removeMsgAvailableListener(EventSubscriber msgSub)
void	removeSpaceAvailableListener(EventSubscriber spcSub)
static int	select(Mailbox... mboxes) Takes an array of mailboxes and returns the index of the first mailbox that has a message.
int	size()
java.lang.String	toString()
void	untilHasMessage() Block caller until at least one message is available.
void	untilHasMessages(int num) Block caller until num messages are available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SPACE_AVAILABLE

public static final int SPACE_AVAILABLE

See Also:

Constant Field Values

MSG_AVAILABLE

public static final int MSG_AVAILABLE

See Also:

Constant Field Values

TIMED_OUT

public static final int TIMED_OUT

See Also:

Constant Field Values

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()
      throws Pausable

Returns:

non-null message.

Throws:

Pausable

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