JanosVM v1.0 API

edu.utah.janosvm.sys
Class TeamHandle

java.lang.Object
  |
  +--edu.utah.janosvm.sys.ListNode
        |
        +--edu.utah.janosvm.sys.Importable
              |
              +--edu.utah.janosvm.sys.TeamHandle
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
EventTeamHandle, IsolateServer

public class TeamHandle
extends Importable
implements java.lang.Cloneable

Provides a safe handle to a Team. Technically, this points to the kernel team's TeamBackEnd object that represents the team in question.

Allocating a TeamHandle does not create a team. See the create methods in Team.

Author:
Tim Stack, Utah Janos Team
See Also:
TeamBackEnd, Team, EventTeamHandle

Field Summary
protected  TeamBackEnd be
           
 
Fields inherited from class edu.utah.janosvm.sys.Importable
em
 
Fields inherited from class edu.utah.janosvm.sys.ListNode
pred, succ
 
Constructor Summary
  TeamHandle()
           
protected TeamHandle(TeamHandle other)
          Copy constructor.
 
Method Summary
protected  void bindTo(Exportable ex)
          Bind this Importable to the given Exportable.
 void cancelImport(Importable im)
           
 java.lang.Object clone()
          Clone a ListNode.
 boolean equals(java.lang.Object obj)
           
 int getDaemonCount()
           
 java.lang.String getDescription()
          Get the Team's description string.
 int getID()
          Returns the unique integer identifier for the team represented by this handle.
 java.lang.String getName()
          Get the name of the team associated with this handle.
 int getThreadCount()
           
 void importObject(Importable to, java.lang.Object id)
           
 boolean isTerminated()
          Test if this handle has been revoked (which is frequently associated with the death of the Team).
 boolean owns(java.lang.Object obj)
          Test if the given object is "owned" by the team this handle represents.
(package private) static void popReservation(TeamReservation tr)
          Pop the last TeamReservation off the stack.
 TeamReservation pushReservation()
          Create a new reservation that reserves the team this object points to.
static void returnFrom()
          End a visit to this team.
 void switchTo()
          Start a visit from the current team to the team this handle refers to.
 void terminate()
          Terminate the team referenced by this handle.
 java.lang.String toString()
           
protected  void unbindFrom()
          Unbind this Importable from any objects it is referencing.
 
Methods inherited from class edu.utah.janosvm.sys.Importable
copy, finalize, getExportManager, revoke, setExportManager
 
Methods inherited from class edu.utah.janosvm.sys.ListNode
append, inList, prepend, remove
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait, wait0
 

Field Detail

be

protected TeamBackEnd be
Constructor Detail

TeamHandle

public TeamHandle()

TeamHandle

protected TeamHandle(TeamHandle other)
Copy constructor.
Method Detail

bindTo

protected 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 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 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:
cancelImport(edu.utah.janosvm.sys.Importable), Team.revokeObject(java.lang.Object), terminate()

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object

getName

public java.lang.String getName()
Get the name of the team associated with this handle.
Returns:
A copy of the team's name.

getDescription

public java.lang.String getDescription()
Get the Team's description string.
Returns:
A copy of the Team's description.

getID

public int getID()
Returns the unique integer identifier for the team represented by this handle. Returns 0 if this handle is not connected, or is connected to a dead team.
Returns:
The unique integer identifier for the team represented by this handle.

getThreadCount

public int getThreadCount()
Returns:
The number of threads in the referenced team.

getDaemonCount

public int getDaemonCount()
Returns:
The number of daemon threads in the referenced team.

owns

public boolean owns(java.lang.Object obj)
Test if the given object is "owned" by the team this handle represents. More specifically, test if it owns the memory used to allocate the object.

Passing null returns true.

Parameters:
obj - The object to test for ownership.
Returns:
True if this TeamHandle owns the object. False if not or if the handle has been revoked.

terminate

public void terminate()
Terminate the team referenced by this handle. This will clean up all the importables and exportables owned by the team and schedule all of its threads for destruction.

If the calling thread is owned by the team being terminated, this function will not return.

This method blocks until after the TeamEvent.TERMINATED events are sent. It may return before the TeamEvent.BURIED events are sent. Active visits to the team being terminated will delay termination until all the visits have been completed. XXX if there is already a terminate in progress, I think this will return early.

See Also:
TeamBackEnd.terminate()

isTerminated

public boolean isTerminated()
Test if this handle has been revoked (which is frequently associated with the death of the Team). Does not actually tell if the Team this handle was associated with is dead.

To reliably know if a Team is terminated, use an EventTeamHandle to get a "terminated" or "buried" event.

XXX Perhaps this method should be moved to EventTeamHandle.


importObject

public void importObject(Importable to,
                         java.lang.Object id)
                  throws DeadTeamException,
                         TeamEjectionException,
                         NoSuchExportException

cancelImport

public void cancelImport(Importable im)

pushReservation

public TeamReservation pushReservation()
                                throws DeadTeamException
Create a new reservation that reserves the team this object points to. The reservation remains "active" until TeamReservation.pop() is invoked by the current thread. Unlike a switchTo(), this call does not implicitly switch context to the other team. That is done by invoking TeamReservation.visit() on the TeamReservation instance returned by this call.

Unlike switchTo() when creating a reservation from the current team to the current Team, termination of the current Team is delayed until the reservation is popped.

Never returns null.

See TeamReservation for an example, and for details of interaction with memory allocations, throwing exceptions, and blocking in Object.wait().

Returns:
A TeamReservation object that reserves this team.
See Also:
switchTo(), TeamBackEnd.pushReservation(int), TeamReservation.visit(), TeamReservation.leave()

switchTo

public void switchTo()
              throws DeadTeamException,
                     TeamEjectionException
Start a visit from the current team to the team this handle refers to. While the visit is active, neither team can be terminated, so object references in either team can be manipulated. The visit ends when returnFrom() is invoked.

Note that switching to the current Team (i.e., Team.current().switchTo()) does NOT prevent the current Team from being terminated. Perhaps that is a bug.

See TeamReservation for an example, and for details of interaction with memory allocations, throwing exceptions, and blocking in Object.wait().

See Also:
TeamBackEnd.switchTo(int)

returnFrom

public static void returnFrom()
End a visit to this team.

XXX Throws an exception/error if used without a corresponding switchTo?

See Also:
switchTo(), TeamBackEnd.returnFrom()

popReservation

static void popReservation(TeamReservation tr)
Pop the last TeamReservation off the stack.

Prefer use of TeamReservation.pop(). NOTE: the given tr is just used as a sanity check to make sure an intervening reservation hasn't been skipped.


clone

public java.lang.Object clone()
Description copied from class: ListNode
Clone a ListNode. The node is cloned in isolation; the clone is never on a list, regardless of the state of the original.
Overrides:
clone in class ListNode

toString

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

JanosVM v1.0 API

This documentation is Copyright (C) 2000-2003 The University of Utah. All Rights Reserved. See the documentation license for distribution terms and restrictions.
Documentation, software, and mailing lists for the JanosVM can be found at the Janos Project web page: http://www.cs.utah.edu/flux/janos/
Generated on Feb 13, 2003