edu.utah.janosvm.kit.comm.commspace
Class CommSpaceHandle

java.lang.Object
  |
  +--edu.utah.janosvm.sys.ListNode
        |
        +--edu.utah.janosvm.sys.Importable
              |
              +--edu.utah.janosvm.kit.comm.commspace.CommSpaceHandle

public final class CommSpaceHandle

extends Importable

A handle on a CommSpace. A CommSpace is an inter-process communication facility based lightly on Linda's "tuples". The space consists of an array of CommSpaceElements. Elements are copied out on read. A thread may write, read, swap, "wait" or "take" any element.

XXX Semantics during a failed take() are probably wrong.

Author:

Janos Ministry of Development

See Also:

CommSpace

Field Summary

private CommSpace

cs

Fields inherited from class edu.utah.janosvm.sys.Importable

em

Fields inherited from class edu.utah.janosvm.sys.ListNode

pred, succ

Constructor Summary

CommSpaceHandle()
Create an empty handle.

CommSpaceHandle(CommSpaceHandle other)
Copy constructor.

Method Summary

protected void	bindTo(Exportable ex) Bind this Importable to the given Exportable.
(package private) boolean	empty() XXX Without this being public there is no way to tell if this thing actually points to a commSpace.
static CommSpaceHandle	newCommSpace(CommSpaceHandle csh, int size) Create a CommSpace and attach it to the given handle.
static CommSpaceHandle	newCommSpace(int size) Create a new CommSpace of the given size and return a handle to it.
CommSpaceElement	read(int index) Read the element at the given index.
int	resize(int newsize) Resize the CommSpace pointed to by this handle to contain the given number of slots.
int	size() Return the number of slots in the CommSpace pointed to by this handle.
CommSpaceElement	swap(int index, CommSpaceElement elem) Swap an element with the one currently in the given index.
CommSpaceElement	take(int index) Take an element from the given index and put a null in its place.
protected void	unbindFrom() Unbind this Importable from any objects it is referencing.
CommSpaceElement	waitToTake(int index) Wait for an element to be placed into the given index.
void	write(int index, CommSpaceElement elem) Write the given element to the given index.

Methods inherited from class edu.utah.janosvm.sys.Importable

copy, finalize, getExportManager, revoke, setExportManager, toString

Methods inherited from class edu.utah.janosvm.sys.ListNode

append, clone, inList, prepend, remove

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait, wait0

Field Detail

cs

private CommSpace cs

Constructor Detail

CommSpaceHandle

public CommSpaceHandle()

Create an empty handle.

See Also:

newCommSpace(CommSpaceHandle,int)

CommSpaceHandle

public CommSpaceHandle(CommSpaceHandle other)

Copy constructor. Only used when passing a csh to a child flow.

Parameters:

other - The handle to copy.

Method Detail

newCommSpace

public static CommSpaceHandle newCommSpace(int size)

Create a new CommSpace of the given size and return a handle to it.

Parameters:

size - The size of the CommSpace.

Returns:

The handle to the CommSpace.

newCommSpace

public static CommSpaceHandle newCommSpace(CommSpaceHandle csh,
                                           int size)

Create a CommSpace and attach it to the given handle.

Parameters:

csh - The CommSpaceHandle to attach to the newly created CommSpace.

size - The size of the CommSpace.

Returns:

The handle that was passed in.

bindTo

protected final void bindTo(Exportable ex)

Description copied from class: Importable

Bind this Importable to the given Exportable. The most common implementation of this method would be to cast the Exportable to the type that the Importable subclass handles and store it in the object as well as any other handy pointers/values.

This method will be invoked as a side-effect of binding this importable to an Exportable object via TeamHandle.importObject(edu.utah.janosvm.sys.Importable, java.lang.Object).

XXX Add note about synchronized.

Overrides:

bindTo in class Importable

Following copied from class: edu.utah.janosvm.sys.Importable

Parameters:

ex - The Exportable that is being imported.

unbindFrom

protected final void unbindFrom()

Description copied from class: Importable

Unbind this Importable from any objects it is referencing. The most common implementation of this method would be null out any object references in this object.

This method will be invoked as a side-effect of canceling this import, or when the Team owning the Exportable is terminated, or when the Exportable is revoked.

XXX rename to just 'unbind'.

Overrides:

unbindFrom in class Importable

Following copied from class: edu.utah.janosvm.sys.Importable

See Also:

TeamHandle.cancelImport(edu.utah.janosvm.sys.Importable), Team.revokeObject(java.lang.Object), TeamHandle.terminate()

empty

boolean empty()

XXX Without this being public there is no way to tell if this thing actually points to a commSpace.

size

public int size()

Return the number of slots in the CommSpace pointed to by this handle.

resize

public int resize(int newsize)

Resize the CommSpace pointed to by this handle to contain the given number of slots.

XXX what happens when resizing to smaller than current and dropping items?

write

public void write(int index,
                  CommSpaceElement elem)
           throws java.lang.ArrayIndexOutOfBoundsException

Write the given element to the given index. Overwrites whatever is already there.

Parameters:

index - The index in the CommSpace to write into.

elem - The element to copy into the CommSpace.

take

public CommSpaceElement take(int index)
                      throws java.lang.ArrayIndexOutOfBoundsException

Take an element from the given index and put a null in its place. The read and replace are atomic with respect to other take()s at the given index. XXX semantically equivalent to swap(index, null)

Parameters:

index - The index in the CommSpace that we should take.

Returns:

null or the CommSpaceElement that was in the given index.

See Also:

swap(int,CommSpaceElement)

waitToTake

public CommSpaceElement waitToTake(int index)
                            throws java.lang.InterruptedException,
                                   java.lang.ArrayIndexOutOfBoundsException

Wait for an element to be placed into the given index. Then atomically take the element and replace with null.

Parameters:

index - The index in the CommSpace that we should take.

Returns:

the CommSpaceElement that was in the given index.

read

public CommSpaceElement read(int index)
                      throws java.lang.ArrayIndexOutOfBoundsException

Read the element at the given index.

Parameters:

index - The index in the CommSpace that we should take.

Returns:

Null or the CommSpaceElement that was in the given index.

swap

public CommSpaceElement swap(int index,
                             CommSpaceElement elem)
                      throws java.lang.ArrayIndexOutOfBoundsException

Swap an element with the one currently in the given index.

Parameters:

index - The index in the CommSpace that we should take.

elem - The element to swap into the index.

Returns:

Null or the CommSpaceElement that was in the given index.