JanosVM v1.0 API

edu.utah.janosvm.sys
Class Importable

java.lang.Object
  |
  +--edu.utah.janosvm.sys.ListNode
        |
        +--edu.utah.janosvm.sys.Importable
Direct Known Subclasses:
AggregateStateManager.IsolateStatusHandle, CommHashtableHandle, CommQueuePuller, CommQueuePusher, CommSpaceHandle, FaxPortHandle, MemoryBlock, OneWayLink_RendezvousImport, TeamHandle

public abstract class Importable
extends ListNode

An Importable is a safe, cross-team reference to a remote "Exportable" object. Implementations of Importable must provide implementations for bindTo(edu.utah.janosvm.sys.Exportable) and unbindFrom()

Methods on Importable and subclasses of Importable generally store pointers to memory in a remote team. Such pointers can be dangerous because they do not automatically become invalid when the team they point into goes away. So, beware that getting operations wrong in an Importable or Exportable can create bogus pointers into remote heaps. Such problems generally manifest as the VM crashing.

XXX note about synchronized() on the object.

Example of a 'FooBackEnd' and 'FooHandle'.

 // The "server" object that other Teams will have references to
 class FooBackEnd extends Exportable {
   ...
 }

 // The "client" object that Teams have locally as a reference to the
 // "server"s Foo.
 class FooHandle extends Importable {
   ...
   private FooBackEnd be; // this is the dangerous cross-team pointer

   private FooHandle() { } 

   protected void bindTo(Exportable ex)
   {
     this.be = (FooBackEnd)ex;
   }

   protected void unbindFrom()
   {
     this.be = null;
   }

   // Lookup a FooBackEnd in the given team.
   public static FooHandle lookupFoo(Team team, Object id) {
     FooBackEnd be;
     FooHandle fh = new FooHandle();
     
     team.importObject(fh, id);
     return fh;
   }

   // Create an anonymous FooBackEnd in team and import it into the current team.
   public static FooHandle newFoo(Team team) {
     FooHandle retval = new FooHandle();

     team.switchTo();
     {
       FooBackEnd be = new FooBackEnd();
       ExportManager em;

       em = Team.current().exportAnonymousObject(be);
       em.addImporter(retval);
     }
     team.returnFrom();
     return retval;
   }

   // perform an operation via the foo handle on the foo back end
   public void performOp(...) {
     synchronized(this) {
       // do some stuff in the context of current team
       be.doSomethingHere(...);

       // do some stuff in the context of the owner
       be.switchToOwner();
       be.doSomethingThere(...);
       be.returnFromOwner();
     }
   }
   ...
 }
 
In the above example, a FooHandle is bound to a particular Team's FooBackEnd object by looking the object up with some sort of key. Operations on the remote foo are perfomed by invoking performOp() on the FooRef. Internally this function visits the owner of the actual Foo, and performs the operation.

Note that all of the ops are done in a synchronized block on the importable. This will prevent the remote team from revoking the FooHandle while the operation is being performed on it (unless the operation in question is to destroy the Foo... be careful).

Author:
Tim Stack, Utah Janos Team
See Also:
TeamHandle.switchTo(), Team.exportAnonymousObject(edu.utah.janosvm.sys.Exportable), Team.exportObject(java.lang.Object, edu.utah.janosvm.sys.Exportable), TeamHandle.importObject(edu.utah.janosvm.sys.Importable, java.lang.Object), Exportable

Field Summary
private  ExportManager em
          The manager of the export we're importing.
 
Fields inherited from class edu.utah.janosvm.sys.ListNode
pred, succ
 
Constructor Summary
Importable()
          Construct an empty Importable.
 
Method Summary
protected abstract  void bindTo(Exportable ex)
          Bind this Importable to the given Exportable.
protected  void copy(Importable im)
          Copy the reference of the given Importable.
protected  void finalize()
           
(package private)  ExportManager getExportManager()
           
 void revoke()
           
(package private)  void setExportManager(ExportManager em)
          Store the ExportManager for the object that is being imported.
 java.lang.String toString()
           
protected abstract  void unbindFrom()
          Unbind this Importable from any objects it is referencing.
 
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

em

private ExportManager em
The manager of the export we're importing.
Constructor Detail

Importable

public Importable()
Construct an empty Importable.
Method Detail

setExportManager

void setExportManager(ExportManager em)
Store the ExportManager for the object that is being imported.
Parameters:
ex - The ExportManager that manages the object being imported.

getExportManager

ExportManager getExportManager()

bindTo

protected abstract void bindTo(Exportable ex)
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.

Parameters:
ex - The Exportable that is being imported.

unbindFrom

protected abstract void unbindFrom()
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'.

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

copy

protected void copy(Importable im)
Copy the reference of the given Importable.
Parameters:
im - The Importable to copy the reference from.

revoke

public void revoke()

finalize

protected void finalize()
Overrides:
finalize in class java.lang.Object

toString

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

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