001: /*=============================================================================
002: * Copyright Texas Instruments 2005. All Rights Reserved.
003: *
004: * This program is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2 of the License, or (at your option) any later version.
008: *
009: * This program is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: */
018:
019: package oscript.util;
020:
021: import oscript.data.*;
022:
023: /**
024: * A member table is a special array, with some special methods that don't
025: * need to exist for regular script arrays:
026: * <ul>
027: * <li> direct access to the Reference
028: * <li> pushN() methods
029: * </ul>
030: * Since the member table is used by scope and to pass args to a function/
031: * constructor, performance is critical, which is the reason for some of these
032: * methods.
033: *
034: * @author Rob Clark (rob@ti.com)
035: * @version 1
036: */
037: public interface MemberTable {
038: /**
039: * Return the reference at the specified index. This does not necessarily
040: * grow the array, so the user should be sure to use
041: * {@link #ensureCapacity(int)} to ensure the array has sufficient capacity
042: * before dereferencing an index into the table which is not known to exist.
043: *
044: * @param idx an index into the member-table
045: * @return a reference
046: */
047: public Reference referenceAt(int idx);
048:
049: /**
050: * Ensure that the member-table has sufficient capacity to accomodate the
051: * index <code>sz</code>. Grow the array, if necessary.
052: *
053: * @param sz the requested table size
054: */
055: public void ensureCapacity(int sz);
056:
057: /**
058: * Indication to the member-table that a "safe" copy is required. This
059: * means that the table may need to outlive the stack-frame that it was
060: * (possibly) allocated from. What it means to convert this table into
061: * a "safe" copy depends on the implementation of the table. A safe
062: * copy is still valid after {@link #free()} is called.
063: * @return a safe copy of this table
064: */
065: public MemberTable safeCopy();
066:
067: /**
068: * Push a single parameter into the table.
069: * @param val the value to push
070: */
071: public void push1(Value val);
072:
073: /**
074: * Push two values into the table.
075: *
076: * @param val1 the value to push
077: * @param val2 the value to push
078: */
079: public void push2(Value val1, Value val2);
080:
081: /**
082: * Push three values into the table.
083: *
084: * @param val1 the value to push
085: * @param val2 the value to push
086: * @param val3 the value to push
087: */
088: public void push3(Value val1, Value val2, Value val3);
089:
090: /**
091: * Push four values into the table.
092: *
093: * @param val1 the value to push
094: * @param val2 the value to push
095: * @param val3 the value to push
096: * @param val4 the value to push
097: */
098: public void push4(Value val1, Value val2, Value val3, Value val4);
099:
100: /**
101: * An indication from the creator of the member-table that, while the table
102: * itself is still required, the references referred to by the table are
103: * no longer required and can be freed.
104: */
105: public void reset();
106:
107: /**
108: * Indication from creator of member-table that resources allocated from
109: * the stack are no longer needed and should be released. (If the member
110: * table is needed after this point, a safe copy should have already been
111: * obtained by calling {@link #safeCopy()}.)
112: */
113: public void free();
114:
115: /**
116: * Get the current size of the member-table. The maximum index which
117: * can be referenced via {@link #referenceAt(int)} is <code>length()-1</code>
118: *
119: * @return the current size
120: */
121: public int length();
122: }
123:
124: /*
125: * Local Variables:
126: * tab-width: 2
127: * indent-tabs-mode: nil
128: * mode: java
129: * c-indentation-style: java
130: * c-basic-offset: 2
131: * eval: (c-set-offset 'substatement-open '0)
132: * eval: (c-set-offset 'case-label '+)
133: * eval: (c-set-offset 'inclass '+)
134: * eval: (c-set-offset 'inline-open '0)
135: * End:
136: */
|