/* 

 *   Copyright (c) 2001, 2002 Michael J. Roberts.  All Rights Reserved.

 *   

 *   Please see the accompanying license file, LICENSE.TXT, for information

 *   on using and copying this software.  

 */

/*

Name

  vmlookup.h - LookupTable metaclass

Function

Notes

Modified

  02/06/01 MJRoberts  - Creation

*/

#ifndef VMLOOKUP_H

#define VMLOOKUP_H

#include "t3std.h"

#include "vmtype.h"

#include "vmglob.h"

#include "vmobj.h"

#include "vmundo.h"

#include "vmcoll.h"

#include "vmiter.h"

/* ------------------------------------------------------------------------ */

/*

 *   The image file data block is arranged as follows:

 *   

 *.  UINT2 bucket_count

 *.  UINT2 value_count

 *.  UINT2 first_free_index

 *.  UINT2 bucket_index[1]

 *.  UINT2 bucket_index[2]

 *.  ...

 *.  UINT2 bucket_index[N]

 *.  value[1]

 *.  value[2]

 *.  value[3]

 *.  etc

 *   

 *   value_count gives the number of value slots allocated.  Free value

 *   slots are kept in a linked list, the head of which is at the 1-based

 *   index given by first_free_index.  If first_free_index is zero, there

 *   are no free value slots.

 *   

 *   Each bucket_index[i] is the 1-based index of the first value in the

 *   chain for that hash bucket.  If the value in a bucket_index[i] is zero,

 *   there are values for that bucket.

 *   

 *   Each free entry has a VM_EMPTY value stored in its key to indicate that

 *   it's empty.

 *   

 *   Each value[i] looks like this:

 *   

 *.  DATAHOLDER key

 *.  DATAHOLDER value

 *.  UINT2 next_index

 *   

 *   next_index gives the 1-based index of the next value in the chain for

 *   that bucket; a value of zero indicates that this is the last value in

 *   the chain.  

 */

/* value entry size */

#define VMLOOKUP_VALUE_SIZE  (VMB_DATAHOLDER + VMB_DATAHOLDER + VMB_UINT2)

/* ------------------------------------------------------------------------ */

/*

 *   in-memory value entry structure 

 */

struct vm_lookup_val

{

    /* the key */

    vm_val_t key;

    /* the value */

    vm_val_t val;

    /* next entry in same hash bucket */

    vm_lookup_val *nxt;

};

/*

 *   Our in-memory extension data structure, which mimics the image file

 *   structure but uses native types.  

 */

struct vm_lookup_ext

{

    /* allocate the structure, given the number of buckets and values */

    static vm_lookup_ext *alloc_ext(VMG_ class CVmObjLookupTable *self,

                                    uint bucket_cnt, uint value_cnt);

    /* 

     *   Initialize the extension - puts all values into the free list and

     *   clears all buckets.  We don't do this automatically as part of

     *   allocation, because some types of allocation set up the buckets and

     *   free list from a known data set and thus are more efficient if they

     *   skip the initialization step. 

     */

    void init_ext();

    /* 

     *   Reallocate the structure with a larger number of values.  Copies

     *   all of the data from the original hash table into the new hash

     *   table, and deletes the old structure.  

     */

    static vm_lookup_ext *expand_ext(VMG_ class CVmObjLookupTable *self,

                                     vm_lookup_ext *old_ext,

                                     uint new_value_cnt);

    /* 

     *   Copy the given extension's data into myself.  This can only be used

     *   when we have the same bucket count as the original (the entry count

     *   need not be the same, but it must be large enough to hold all of

     *   the data from the original).

     *   

     *   This loses any data previously in the table.  

     */

    void copy_ext_from(vm_lookup_ext *old_ext);

    /* allocate a value entry out of my free list */

    vm_lookup_val *alloc_val_entry()

    {

        vm_lookup_val *entry;

        /* if the free list is empty, return failure */

        if (first_free == 0)

            return 0;

        /* take the first item off the free list */

        entry = first_free;

        /* unlink it from the free list */

        first_free = first_free->nxt;

        /* return the allocated item */

        return entry;

    }

    /* 

     *   Add a value into the given hash bucket.  The caller is responsible

     *   for ensuring there's enough room. 

     */

    void add_val(uint hash, const vm_val_t *key, const vm_val_t *val)

    {

        vm_lookup_val *entry;

        /* allocate a new entry */

        entry = alloc_val_entry();

        /* set it up with the new data */

        entry->key = *key;

        entry->val = *val;

        /* link it into the given bucket */

        entry->nxt = buckets[hash];

        buckets[hash] = entry;

    }

    /* 

     *   Given a pool index, retrieve a value entry from our pool of value

     *   entries.  This has nothing to do with the hash bucket lists or the

     *   free list - this is simply the nth entry in the master pool of all

     *   values.  

     */

    vm_lookup_val *idx_to_val(uint idx) const

    {

        vm_lookup_val *pool;

        /* the pool of values starts immediately after the buckets */

        pool = (vm_lookup_val *)(void *)&buckets[bucket_cnt];

        /* return the nth element of the pool */

        return &pool[idx];

    }

    /* given a value entry, get the pool index */

    uint val_to_idx(vm_lookup_val *val) const

    {

        return (val - idx_to_val(0));

    }

    /* 

     *   Convert an image-file or save-file index to a value pointer.  These

     *   are given as 1-based pointers, with the special value zero used to

     *   indicate a null pointer. 

     */

    vm_lookup_val *img_idx_to_val(uint idx) const

    {

        if (idx == 0)

            return 0;

        else

            return idx_to_val(idx - 1);

    }

    /* convert a value pointer to an image file index */

    uint val_to_img_idx(vm_lookup_val *val)

    {

        /* 

         *   use zero for a null pointer; otherwise, use a 1-based index in

         *   our master value pool 

         */

        if (val == 0)

            return 0;

        else

            return (val - idx_to_val(0)) + 1;

    }

    /* number of buckets and number of allocated value entries */

    uint bucket_cnt;

    uint value_cnt;

    /* pointer to the first free value */

    vm_lookup_val *first_free;

    /* 

     *   buckets (we overallocate the structure to make room): each bucket

     *   points to the first entry in the list of entries at this hash value 

     */

    vm_lookup_val *buckets[1];

};

/* ------------------------------------------------------------------------ */

/* 

 *   undo action codes 

 */

enum lookuptab_undo_action

{

    /* 

     *   null record - we use this to mark a record that has become

     *   irrelevant because of a stale weak reference 

     */

    LOOKUPTAB_UNDO_NULL,

    /* we added this word to the dictionary (undo by deleting it) */

    LOOKUPTAB_UNDO_ADD,

    /* we deleted this word from the dictionary (undo by adding it back) */

    LOOKUPTAB_UNDO_DEL,

    /* we modified the value for a given key */

    LOOKUPTAB_UNDO_MOD

};

/* ------------------------------------------------------------------------ */

/*

 *   LookupTable metaclass 

 */

class CVmObjLookupTable: public CVmObjCollection

{

    friend class CVmObjIterLookupTable;

    friend class CVmMetaclassLookupTable;

public:

    /* metaclass registration object */

    static class CVmMetaclass *metaclass_reg_;

    class CVmMetaclass *get_metaclass_reg() const { return metaclass_reg_; }

    /* am I of the given metaclass? */

    virtual int is_of_metaclass(class CVmMetaclass *meta) const

    {

        /* try my own metaclass and my base class */

        return (meta == metaclass_reg_

                || CVmObjCollection::is_of_metaclass(meta));

    }

    /* create */

    static vm_obj_id_t create(VMG_ int in_root_set,

                              uint bucket_count, uint init_capacity);

    /* create dynamically using stack arguments */

    static vm_obj_id_t create_from_stack(VMG_ const uchar **pc_ptr,

                                         uint argc);

    /* 

     *   call a static property - we don't have any of our own, so simply

     *   "inherit" the base class handling 

     */

    static int call_stat_prop(VMG_ vm_val_t *result,

                              const uchar **pc_ptr, uint *argc,

                              vm_prop_id_t prop)

    {

        return CVmObjCollection::

            call_stat_prop(vmg_ result, pc_ptr, argc, prop);

    }

    /* reserve constant data */

    virtual void reserve_const_data(VMG_ class CVmConstMapper *mapper,

                                    vm_obj_id_t self)

    {

        /* we cannot be converted to constant data */

    }

    /* convert to constant data */

    virtual void convert_to_const_data(VMG_ class CVmConstMapper *mapper,

                                       vm_obj_id_t self);

    /* notify of deletion */

    void notify_delete(VMG_ int in_root_set);

    /* set a property */

    void set_prop(VMG_ class CVmUndo *undo,

                  vm_obj_id_t self, vm_prop_id_t prop, const vm_val_t *val);

    /* get a property */

    int get_prop(VMG_ vm_prop_id_t prop, vm_val_t *val,

                 vm_obj_id_t self, vm_obj_id_t *source_obj, uint *argc);

    /* 

     *   receive savepoint notification - we don't keep any

     *   savepoint-relative records, so we don't need to do anything here 

     */

    void notify_new_savept() { }

    /* apply an undo record */

    void apply_undo(VMG_ struct CVmUndoRecord *rec);

    /* discard an undo record */

    void discard_undo(VMG_ struct CVmUndoRecord *);

    /* mark undo references */

    void mark_undo_ref(VMG_ struct CVmUndoRecord *rec);

    /* mark references */

    void mark_refs(VMG_ uint);

    /* we keep only strong references */

    void remove_stale_weak_refs(VMG0_) { }

    void remove_stale_undo_weak_ref(VMG_ struct CVmUndoRecord *) { }

    /* load from an image file */

    void load_from_image(VMG_ vm_obj_id_t self, const char *ptr, size_t siz);

    /* reload from an image file */

    void reload_from_image(VMG_ vm_obj_id_t self,

                           const char *ptr, size_t siz);

    /* rebuild for image file */

    virtual ulong rebuild_image(VMG_ char *buf, ulong buflen);

    /* save to a file */

    void save_to_file(VMG_ class CVmFile *fp);

    /* restore from a file */

    void restore_from_file(VMG_ vm_obj_id_t self,

                           class CVmFile *fp, class CVmObjFixup *fixups);

    /* 

     *   determine if we've been changed since loading - assume we have (if

     *   we haven't, the only harm is the cost of unnecessarily reloading or

     *   saving) 

     */

    int is_changed_since_load() const { return TRUE; }

    /* get a value by index */

    void index_val(VMG_ vm_val_t *result,

                   vm_obj_id_t self,

                   const vm_val_t *index_val);

    /* set a value by index */

    void set_index_val(VMG_ vm_val_t *new_container,

                       vm_obj_id_t self,

                       const vm_val_t *index_val,

                       const vm_val_t *new_val);

    /* add an entry - does not generate undo */

    void add_entry(VMG_ const vm_val_t *key, const vm_val_t *val);

protected:

    /* get and range-check the constructor arguments */

    static void get_constructor_args(VMG_ uint argc, size_t *bucket_count,

                                     size_t *init_capacity);

    /* load or reload image data */

    void load_image_data(VMG_ const char *ptr, size_t siz);

    /* create a new object as a copy of this object */

    vm_obj_id_t create_copy(VMG0_);

    /* add an entry, generating undo */

    void add_entry_undo(VMG_ vm_obj_id_t self,

                        const vm_val_t *key, const vm_val_t *val);

    /* delete an entry - does not generate undo */

    void del_entry(VMG_ const vm_val_t *key);

    /* 

     *   Unlink an entry - does not generate undo.  'prv_entry' is the

     *   previous entry in the hash chain containing this entry, and

     *   'hashval' is the bucket containing the entry.  Pass null for

     *   'prv_entry' when the entry to unlink is the first entry in its hash

     *   chain.  

     */

    void unlink_entry(VMG_ vm_lookup_val *entry, uint hashval,

                      vm_lookup_val *prv_entry);

    /* 

     *   modify an entry - changes the value associated with the given key;

     *   does not generate undo 

     */

    void mod_entry(VMG_ const vm_val_t *key, const vm_val_t *val);

    /* find an entry */

    vm_lookup_val *find_entry(VMG_ const vm_val_t *key,

                              uint *hashval_p, vm_lookup_val **prv_entry_p);

    /*

     *   Check the table to make sure there's enough free space to add one

     *   new item, and expand the table if necessary.  

     */

    void expand_if_needed(VMG0_);

    /* allocate a new entry, expanding the table if necessary */

    vm_lookup_val *alloc_new_entry(VMG0_);

    /* calculate a value's hash code */

    uint calc_key_hash(VMG_ const vm_val_t *key);

    /* get my extension data */

    vm_lookup_ext *get_ext() const { return (vm_lookup_ext *)ext_; }

    /* get the hash bucket count */

    uint get_bucket_count() const { return get_ext()->bucket_cnt; }

    /* get the value entry count */

    uint get_entry_count() const { return get_ext()->value_cnt; }

    /* get/set the first-free item */

    vm_lookup_val *get_first_free() const { return get_ext()->first_free; }

    void set_first_free(vm_lookup_val *p) { get_ext()->first_free = p; }

    /* get a bucket's first entry given a hash code */

    vm_lookup_val **get_bucket(uint hash) const

        { return &get_ext()->buckets[hash]; }

    /* set a bucket's contents given a hash code */

    void set_bucket(uint hash, vm_lookup_val *p)

        { get_ext()->buckets[hash] = p; }

    /* set an entry, keeping undo for the change */

    void set_entry_val_undo(VMG_ vm_obj_id_t self,

                            vm_lookup_val *entry, const vm_val_t *val);

    /* create an iterator */

    virtual void new_iterator(VMG_ vm_val_t *retval,

                              const vm_val_t *self_val);

    /* create a live iterator */

    virtual void new_live_iterator(VMG_ vm_val_t *retval,

                                   const vm_val_t *self_val);

    /* create a lookup table with no initial contents */

    CVmObjLookupTable() { ext_ = 0; }

    /* 

     *   Create a lookup table with a given number of hash table buckets,

     *   and the given number of entry slots.  The hash table bucket count

     *   is fixed for the life of the object.  The entry slot count is

     *   merely advisory: the table size will be increased as necessary to

     *   accommodate new elements.  

     */

    CVmObjLookupTable(VMG_ size_t hash_count, size_t entry_count);

    /* property evaluator - undefined function */

    int getp_undef(VMG_ vm_obj_id_t, vm_val_t *, uint *) { return FALSE; }

    /* property evaluator - remove an entry given the key */

    int getp_remove_entry(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - determine if a given key is in the table */

    int getp_key_present(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - apply a callback to each element */

    int getp_apply_all(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - call a callback on each element */

    int getp_for_each(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - call a callback on each element */

    int getp_for_each_assoc(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* general forEach/forEachAssoc processor */

    int for_each_gen(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc,

                     int pass_key_to_cb);

    /* get the number of buckets in the table */

    int getp_count_buckets(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* get the number of entries in the table */

    int getp_count_entries(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* make a list of all of the keys in the table */

    int getp_keys_to_list(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* make a list of all of the values in the table */

    int getp_vals_to_list(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* general handler for making a list of keys or values */

    int make_list(VMG_ vm_obj_id_t self,

                  vm_val_t *retval, uint *argc, int store_keys);

    /* add a record to the global undo stream */

    void add_undo_rec(VMG_ vm_obj_id_t self,

                      enum lookuptab_undo_action action,

                      const vm_val_t *key,

                      const vm_val_t *old_entry_val);

    /* property evaluation function table */

    static int (CVmObjLookupTable::*func_table_[])(VMG_ vm_obj_id_t self,

        vm_val_t *retval, uint *argc);

};

/* ------------------------------------------------------------------------ */

/*

 *   WeakRefLookupTable - a subclass of LookupTable that places weak

 *   references on its values.  The keys are still strong references. 

 */

class CVmObjWeakRefLookupTable: public CVmObjLookupTable

{

    friend class CVmMetaclassWeakRefLookupTable;

public:

    /* metaclass registration object */

    static class CVmMetaclass *metaclass_reg_;

    class CVmMetaclass *get_metaclass_reg() const { return metaclass_reg_; }

    /* am I of the given metaclass? */

    virtual int is_of_metaclass(class CVmMetaclass *meta) const

    {

        /* try my own metaclass and my base class */

        return (meta == metaclass_reg_

                || CVmObjLookupTable::is_of_metaclass(meta));

    }

    /* create */

    static vm_obj_id_t create(VMG_ int in_root_set,

                              uint bucket_count, uint init_capacity);

    /* create dynamically using stack arguments */

    static vm_obj_id_t create_from_stack(VMG_ const uchar **pc_ptr,

                                         uint argc);

    /* 

     *   call a static property - we don't have any of our own, so simply

     *   "inherit" the base class handling 

     */

    static int call_stat_prop(VMG_ vm_val_t *result,

                              const uchar **pc_ptr, uint *argc,

                              vm_prop_id_t prop)

    {

        return CVmObjLookupTable::

            call_stat_prop(vmg_ result, pc_ptr, argc, prop);

    }

    /* mark references */

    void mark_refs(VMG_ uint);

    /* mark undo references */

    void mark_undo_ref(VMG_ struct CVmUndoRecord *rec);

    /* remove stale weak references */

    void remove_stale_undo_weak_ref(VMG_ struct CVmUndoRecord *rec);

    /* remove stale weak references */

    void remove_stale_weak_refs(VMG0_);

protected:

    /* create a lookup table with no initial contents */

    CVmObjWeakRefLookupTable() { ext_ = 0; }

    /* construct */

    CVmObjWeakRefLookupTable(VMG_ size_t hash_count, size_t entry_count)

        : CVmObjLookupTable(vmg_ hash_count, entry_count) { }

};

/* ------------------------------------------------------------------------ */

/*

 *   LookupTable Registration table object 

 */

class CVmMetaclassLookupTable: public CVmMetaclass

{

public:

    /* get the global name */

    const char *get_meta_name() const { return "lookuptable/030002"; }

    /* create from image file */

    void create_for_image_load(VMG_ vm_obj_id_t id)

    {

        new (vmg_ id) CVmObjLookupTable();

        G_obj_table->set_obj_gc_characteristics(id, TRUE, FALSE);

    }

    /* create from restoring from saved state */

    void create_for_restore(VMG_ vm_obj_id_t id)

    {

        new (vmg_ id) CVmObjLookupTable();

        G_obj_table->set_obj_gc_characteristics(id, TRUE, FALSE);

    }

    /* create dynamically using stack arguments */

    vm_obj_id_t create_from_stack(VMG_ const uchar **pc_ptr, uint argc)

        { return CVmObjLookupTable::create_from_stack(vmg_ pc_ptr, argc); }

    /* call a static property */

    int call_stat_prop(VMG_ vm_val_t *result,

                       const uchar **pc_ptr, uint *argc,

                       vm_prop_id_t prop)

    {

        return CVmObjLookupTable::

            call_stat_prop(vmg_ result, pc_ptr, argc, prop);

    }

    /* I'm a Collection object */

    CVmMetaclass *get_supermeta_reg() const

        { return CVmObjCollection::metaclass_reg_; }

};

/*

 *   WeakRefLookupTable registration object

 */

class CVmMetaclassWeakRefLookupTable: public CVmMetaclass

{

public:

    /* get the global name */

    const char *get_meta_name() const { return "weakreflookuptable/030000"; }

    /* create from image file */

    void create_for_image_load(VMG_ vm_obj_id_t id)

        { new (vmg_ id) CVmObjWeakRefLookupTable(); }

    /* create from restoring from saved state */

    void create_for_restore(VMG_ vm_obj_id_t id)

        { new (vmg_ id) CVmObjWeakRefLookupTable(); }

    /* create dynamically using stack arguments */

    vm_obj_id_t create_from_stack(VMG_ const uchar **pc_ptr, uint argc)

        { return CVmObjWeakRefLookupTable::

        create_from_stack(vmg_ pc_ptr, argc); }

    /* call a static property */

    int call_stat_prop(VMG_ vm_val_t *result,

                       const uchar **pc_ptr, uint *argc,

                       vm_prop_id_t prop)

    {

        return CVmObjWeakRefLookupTable::

            call_stat_prop(vmg_ result, pc_ptr, argc, prop);

    }

    /* I'm a LookupTable object */

    CVmMetaclass *get_supermeta_reg() const

        { return CVmObjLookupTable::metaclass_reg_; }

};

/* ------------------------------------------------------------------------ */

/*

 *   LookupTable Iterator subclass.  This iterator is tightly coupled with

 *   the LookupTable class, since we must look into the internal

 *   implementation of the LookupTable to implement an iterator on it.  

 */

/*

 *   The extension data for an lookup table iterator consists of a reference

 *   to the associated LookupTable object, the current bucket index, and the

 *   index of the current entry.

 *   

 *   DATAHOLDER lookuptable_value

 *.  UINT2 cur_entry_index (1-based; zero is invalid)

 *.  UINT2 flags

 *   

 *   The flag values are:

 *   

 *   VMOBJITERLOOKUPTABLE_UNDO - we've saved undo for this savepoint.  If

 *   this is set, we won't save additional undo for the same savepoint.  

 */

/* total extension size */

#define VMOBJITERLOOKUPTABLE_EXT_SIZE  (VMB_DATAHOLDER + 2 + 2)

/* 

 *   flag bits 

 */

/* we've saved undo for the current savepoint */

#define VMOBJITERLOOKUPTABLE_UNDO   0x0001

/*

 *   LookupTable iterator class 

 */

class CVmObjIterLookupTable: public CVmObjIter

{

    friend class CVmMetaclassIterLookupTable;

public:

    /* metaclass registration object */

    static class CVmMetaclass *metaclass_reg_;

    class CVmMetaclass *get_metaclass_reg() const { return metaclass_reg_; }

    /* am I of the given metaclass? */

    virtual int is_of_metaclass(class CVmMetaclass *meta) const

    {

        /* try my own metaclass and my base class */

        return (meta == metaclass_reg_

                || CVmObjIter::is_of_metaclass(meta));

    }

    /* 

     *   call a static property - we don't have any of our own, so simply

     *   "inherit" the base class handling 

     */

    static int call_stat_prop(VMG_ vm_val_t *result,

                              const uchar **pc_ptr, uint *argc,

                              vm_prop_id_t prop)

    {

        return CVmObjIter::call_stat_prop(vmg_ result, pc_ptr, argc, prop);

    }

    /*

     *   Create a lookup table iterator.  This method is to be called by the

     *   lookup table to create an iterator for its value.  

     */

    static vm_obj_id_t create_for_coll(VMG_ const vm_val_t *coll);

    /* notify of deletion */

    void notify_delete(VMG_ int in_root_set);

    /* 

     *   notify of a new savepoint - clear the 'undo' flag, since we cannot

     *   have created any undo information yet for the new savepoint 

     */

    void notify_new_savept()

        { set_flags(get_flags() & ~VMOBJITERLOOKUPTABLE_UNDO); }

    /* apply undo */

    void apply_undo(VMG_ struct CVmUndoRecord *rec);

    /* mark references */

    void mark_refs(VMG_ uint state);

    /* there are no references in our undo stream */

    void mark_undo_ref(VMG_ struct CVmUndoRecord *) { }

    /* we keep only strong references */

    void remove_stale_weak_refs(VMG0_) { }

    void remove_stale_undo_weak_ref(VMG_ struct CVmUndoRecord *) { }

    /* load from an image file */

    void load_from_image(VMG_ vm_obj_id_t self, const char *ptr, size_t siz);

    /* reload from an image file */

    void reload_from_image(VMG_ vm_obj_id_t self,

                           const char *ptr, size_t siz);

    /* 

     *   determine if the object has been changed since it was loaded -

     *   assume we have 

     */

    int is_changed_since_load() const { return TRUE; }

    /* save to a file */

    void save_to_file(VMG_ class CVmFile *fp);

    /* restore from a file */

    void restore_from_file(VMG_ vm_obj_id_t self,

                           class CVmFile *fp, class CVmObjFixup *fixups);

    /* rebuild for image file */

    virtual ulong rebuild_image(VMG_ char *buf, ulong buflen);

    /* convert to constant data */

    virtual void convert_to_const_data(VMG_ class CVmConstMapper *mapper,

                                       vm_obj_id_t self);

protected:

    /* create */

    CVmObjIterLookupTable() { ext_ = 0; }

    /* create */

    CVmObjIterLookupTable(VMG_ const vm_val_t *coll);

    /* find the first valid entry, starting at the given index */

    uint find_first_valid_entry(VMG_ uint entry) const;

    /* property evaluator - get next value */

    virtual int getp_get_next(VMG_ vm_obj_id_t self, vm_val_t *retval,

                              uint *argc);

    /* property evaluator - is next value available? */

    virtual int getp_is_next_avail(VMG_ vm_obj_id_t self, vm_val_t *retval,

                                   uint *argc);

    /* property evaluator - reset to first item */

    virtual int getp_reset_iter(VMG_ vm_obj_id_t self, vm_val_t *retval,

                                uint *argc);

    /* property evaluator - get current key */

    virtual int getp_get_cur_key(VMG_ vm_obj_id_t self, vm_val_t *retval,

                                 uint *argc);

    /* property evaluator - get current value */

    virtual int getp_get_cur_val(VMG_ vm_obj_id_t self, vm_val_t *retval,

                                 uint *argc);

    /* get information on the current entry */

    void get_cur_entry(VMG_ vm_val_t *valp, vm_val_t *keyp) const;

    /* get my collection value */

    void get_coll_val(vm_val_t *val) const { vmb_get_dh(ext_, val); }

    /* get/set the current entry index (without saving undo) */

    long get_entry_index() const

        { return osrp2(ext_ + VMB_DATAHOLDER); }

    void set_entry_index(uint idx)

        { oswp2(ext_ + VMB_DATAHOLDER, idx); }

    /* update the entry index value, saving undo if necessary */

    void set_entry_index_undo(VMG_ vm_obj_id_t self, uint entry);

    /* get/set the flags */

    uint get_flags() const

        { return osrp2(ext_ + VMB_DATAHOLDER + 2); }

    void set_flags(uint flags) const

        { oswp2(ext_ + VMB_DATAHOLDER + 2, flags); }

};

/*

 *   Registration table object for lookup table iterators

 */

class CVmMetaclassIterLookupTable: public CVmMetaclass

{

public:

    /* get the global name */

    const char *get_meta_name() const

        { return "lookuptable-iterator/030000"; }

    /* create from image file */

    void create_for_image_load(VMG_ vm_obj_id_t id)

    {

        new (vmg_ id) CVmObjIterLookupTable();

        G_obj_table->set_obj_gc_characteristics(id, TRUE, FALSE);

    }

    /* create from restoring from saved state */

    void create_for_restore(VMG_ vm_obj_id_t id)

    {

        new (vmg_ id) CVmObjIterLookupTable();

        G_obj_table->set_obj_gc_characteristics(id, TRUE, FALSE);

    }

    /* create dynamically using stack arguments */

    vm_obj_id_t create_from_stack(VMG_ const uchar **pc_ptr, uint argc)

    {

        err_throw(VMERR_BAD_DYNAMIC_NEW);

        AFTER_ERR_THROW(return VM_INVALID_OBJ;)

    }

    /* call a static property */

    int call_stat_prop(VMG_ vm_val_t *result,

                       const uchar **pc_ptr, uint *argc,

                       vm_prop_id_t prop)

    {

        return CVmObjIterLookupTable::

            call_stat_prop(vmg_ result, pc_ptr, argc, prop);

    }

};

#endif /* VMLOOKUP_H */

/*