mnj/lua/UpVal.java

   1 /*  $Header: //info.ravenbrook.com/project/jili/version/1.1/code/mnj/lua/UpVal.java#1 $
   2  * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
   3  * All rights reserved.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining
   6  * a copy of this software and associated documentation files (the
   7  * "Software"), to deal in the Software without restriction, including
   8  * without limitation the rights to use, copy, modify, merge, publish,
   9  * distribute, sublicense, and/or sell copies of the Software, and to
  10  * permit persons to whom the Software is furnished to do so, subject
  11  * to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be
  14  * included in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  19  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
  20  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  21  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 package mnj.lua;
  26
  27 /**
  28  * Models an upvalue.  This class is internal to Jill and should not be
  29  * used by clients.
  30  * This is the analogue of the UpVal type in PUC-Rio's Lua
  31  * implementation, hence the name.
  32  * An UpVal instance is a reference to a variable.
  33  * When initially created generally the variable is kept on the VM
  34  * stack.  When the function that defines that variable returns, the
  35  * corresponding stack slots are destroyed.  In order that the UpVal
  36  * continues to reference the variable, it is closed (using the
  37  * <code>close</code> method).  Lua functions that reference, via an
  38  * upvalue, the same instance of the same variable, will share an
  39  * <code>UpVal</code> (somewhere in their <code>upval</code> array
  40  * member); hence they share updates to the variable.
  41  */
  42 final class UpVal
  43 {
  44   /**
  45    * The offset field.  Stored here, but not actually used directly by
  46    * this class.
  47    * Used (by {@link Lua}) when searching for {@link UpVal} instances.
  48    * An open UpVal has a valid offset field.  Its slot is shared
  49    * with a slot of the VM stack.
  50    * A closed UpVal has offset == -1.  It's slot will be a fresh copy
  51    * and not shared with any other.
  52    */
  53   private int offset;
  54   /**
  55    * The slot object used to store the Lua value.
  56    */
  57   private Slot s;
  58
  59   /**
  60    * A fresh upvalue from an offset, and a slot.
  61    * Conceptually <var>offset</var> and <var>slot</var> convey the same
  62    * information, only one is necessary since the offset implies the
  63    * slot and vice-versa.  <var>slot</var> is used to directly reference
  64    * the value (this avoids an indirection to the VM stack). <var>offset</var>
  65    * is used when searching for UpVals in the openupval list; this
  66    * happens when closing UpVals (function return) or creating them
  67    * (execution of functon declaration).
  68    * @param offset  index into Lua thread's VM stack, must be a valid index.
  69    * @param s  Slot corresponding to offset.
  70    * @throws NullPointerException if L is null.
  71    */
  72   UpVal(int offset, Slot s)
  73   {
  74     this.offset = offset;
  75     this.s = s;
  76   }
  77
  78   /**
  79    * Getter for underlying value.
  80    */
  81   Object getValue()
  82   {
  83     return s.asObject();
  84   }
  85
  86   /**
  87    * Setter for underlying value.
  88    */
  89   void setValue(Object o)
  90   {
  91     s.setObject(o);
  92   }
  93
  94   /**
  95    * The offset.
  96    */
  97   int offset()
  98   {
  99     return offset;
 100   }
 101
 102   /**
 103    * Closes an UpVal.  This ensures that the storage operated on by
 104    * {@link #getValue() getValue} and {@link #setValue(Object) setValue}
 105    * is not shared by any other object.
 106    * This is typically used when a function returns (executes
 107    * the <code>OP_RET</code> VM instruction).  Effectively this
 108    * transfers a variable binding from the stack to the heap.
 109    */
 110   void close()
 111   {
 112     s = new Slot(s);
 113     offset = -1;
 114   }
 115 }