/* 

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

 *   

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

 *   on using and copying this software.  

 */

/*

Name

  vmobj.h - VM object memory manager

Function

Notes

Modified

  10/20/98 MJRoberts  - Creation

*/

#ifndef VMOBJ_H

#define VMOBJ_H

#include <stdlib.h>

#include <memory.h>

#include "vmglob.h"

#include "vmtype.h"

#include "vmerr.h"

#include "vmerrnum.h"

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

/*

 *   If the VM_REGISTER_METACLASS macro hasn't been defined, define it

 *   now.  This macro is defined different ways on different inclusions,

 *   but when it's not defined, it should always be defined to do nothing.

 */

#ifndef VM_REGISTER_METACLASS

# define VM_REGISTER_METACLASS(metaclass)

#endif

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

/*

 *   NOTE TO METACLASS IMPLEMENTORS - each final concrete class derived

 *   from CVmObject that is to be available to VM programs for static

 *   image file loading and/or dynamic creation (via the "NEW"

 *   instructions) must specify a VM_REGISTER_METACLASS declaration to

 *   register the metaclass.  This declaration must occur in the

 *   metaclass's header file, and must be OUTSIDE of the region protected

 *   against multiple inclusion.  The definition should look like this:

 *   

 *   VM_REGISTER_METACLASS("metaclass-string-name", CVmClassName)

 *   

 *   The string name must be the universally unique metaclass identifier

 *   string registered with the T3 VM Specification Maintainer.  The class

 *   name is the C++ class (derived from CVmObject).

 *   

 *   Each CVmObject subclass must define certain static construction

 *   methods in addition to the virtual methods defined as abstract in

 *   CVmObject.  See the comments on CVmObject for details.

 */

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

/*

 *   To get a pointer to an object (CVmObject *) given an object ID

 *   (vm_obj_id_t), use this:

 *   

 *   CVmObject *obj = vm_objp(vmg_ id);

 *   

 *   To allocate a new object:

 *   

 *   vm_obj_id_t id = vm_newid(vmg_ in_root_set);

 *.  CVmObject *obj = new (vmg_ id) CVmObjXxx(constructor params);

 *   

 *   The functions vm_objp() and vm_newid() are defined later in this

 *   file.  

 */

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

/*

 *   Garbage collector work increment.  This is the number of objects that

 *   the GC will process on each call to gc_pass_queue().

 *   

 *   The point of running the GC incrementally is to allow GC work to be

 *   interleaved with long-running user I/O operations (such as reading a

 *   line of text from the keyboard) in the foreground thread, so the work

 *   increment should be chosen so that each call to this routine

 *   completes quickly enough that the user will perceive no delay.

 *   However, making this number too small will introduce additional

 *   overhead by making an excessive number of function calls.  

 */

const int VM_GC_WORK_INCREMENT = 500;

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

/* 

 *   flag values for propDefined 

 */

#define VMOBJ_PROPDEF_ANY           1

#define VMOBJ_PROPDEF_DIRECTLY      2

#define VMOBJ_PROPDEF_INHERITS      3

#define VMOBJ_PROPDEF_GET_CLASS     4

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

/*

 *   Objects are composed of two parts.  The first is a fixed-size

 *   portion, or header, which consists of an abstract interface (in terms

 *   of stored data, this is simply a vtable pointer) and an extension

 *   pointer.  The extension pointer points to the variable-size second

 *   part of the object, which contains all of the additional instance

 *   data for the object.  

 */

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

/*

 *   

 *   The fixed-size parts, or object headers, are allocated from a set of

 *   arrays.  A master array has a pointer to the sub-arrays, and each

 *   sub-array has a fixed number of slots for the fixed-size parts.

 *   Thus, it's very fast to find an object header given an object ID.

 *   

 *   Because each fixed-size part has an abstract interface, we can have

 *   multiple implementations for the objects.  This would allow us, for

 *   example, to include native objects (with an appropriate interface) as

 *   though they were normal VM objects.  It also allows us to have

 *   different types of implementations for VM objects.

 *   

 *   The fixed-size object parts never move in memory, so we can refer to

 *   them with pointers.  We can efficiently re-use space as object

 *   headers are allocated and deleted, because a new object will always

 *   take up exactly the same size as a previous object whose space was

 *   freed.

 *   

 *   The fixed-size objects are always allocated within the page table,

 *   thus operator new is overridden to allocate memory within the page

 *   table.  

 */

/*

 *   In addition to the virtual methods listed, every object must define a

 *   data member as follows:

 *   

 *   public: static class CVmMetaclass *metaclass_reg_;

 *   

 *   This must be a static singleton instance of the CVmMetaclass subclass

 *   (see below) for the CVmObject subclass.  Each CVmObject subclass must

 *   have a corresponding CVmMetaclass subclass; the singleton member

 *   variable metaclass_reg_ provides the registration table entry that

 *   allows instances of this object to be dynamically linked from the

 *   image file.  

 */

class CVmObject

{

    friend class CVmVarHeap;

public:

    /* metaclass registration object (for the root object implementation) */

    static class CVmMetaclass *metaclass_reg_;

    /*

     *   Default implementation for calling a static property.  We don't

     *   have any static properties at this level, so we'll simply return

     *   false to indicate that the property wasn't evaluated.  

     */

    static int call_stat_prop(VMG_ vm_val_t *retval, const uchar **pc_ptr,

                              uint *argc, vm_prop_id_t);

    /* get the registration object for this metaclass */

    virtual class CVmMetaclass *get_metaclass_reg() const

        { return metaclass_reg_; }

    /* 

     *   Is this object of the given metaclass?  Returns true if the

     *   object is an instance of 'meta' or inherits from the metaclass.

     *   Each object class must override this.  

     */

    virtual int is_of_metaclass(class CVmMetaclass *meta) const

        { return (meta == metaclass_reg_); }

    /* 

     *   Receive notification that this object is being deleted - the

     *   garbage collector calls this function when the object is

     *   unreachable.

     *   

     *   Note that we don't use the real destructor, since we use our own

     *   memory management; instead, we have this virtual finalizer that

     *   we explicitly call when it's time to delete the object.  (This

     *   isn't entirely symmetrical with the overridden operator new, but

     *   the GC is the only code that can delete objects, and this saves

     *   us the trouble of overriding operator delete for the object.)  

     */

    virtual void notify_delete(VMG_ int in_root_set) = 0;

    /*

     *   Create an instance of this class.  If this object does not

     *   represent a class, or cannot be instanced, throw an error.  By

     *   default, objects cannot be instanced, so we'll simply throw an

     *   error.  If successful, leaves the new object in register R0.

     *   

     *   Parameters to the constructor are passed on the VM stack; 'argc'

     *   gives the number of arguments on the stack.  This routine will

     *   remove the arguments from the stack before returning.  

     */

    virtual void create_instance(VMG_ vm_obj_id_t self,

                                 const uchar **pc_ptr, uint argc)

    {

        /* throw the error */

        err_throw(VMERR_CANNOT_CREATE_INST);

    }

    /*

     *   Determine if the object has a non-trivial finalizer.  Returns

     *   true if the object has a non-trivial finalizer, false if it has

     *   no finalizer or the finalizer is trivial and hence can be

     *   ignored.  We'll return false by default.  

     */

    virtual int has_finalizer(VMG_ vm_obj_id_t /*self*/)

        { return FALSE; }

    /*

     *   Invoke the object's finalizer.  This need do nothing if the

     *   object does not define or inherit a finalizer method.  Any

     *   exceptions thrown in the course of executing the finalizer should

     *   be caught and discarded.  By default, we'll do nothing at all.

     */

    virtual void invoke_finalizer(VMG_ vm_obj_id_t /*self*/) { }

    /*

     *   Determine if this is a class object.  This returns true if this

     *   object is a class, false if it's an instance.  

     */

    virtual int is_class_object(VMG_ vm_obj_id_t /*self*/) const

        { return FALSE; }

    /*

     *   Determine if this object is an instance of another object.

     *   Returns true if this object derives from the other object,

     *   directly or indirectly.  If this object derives from an object

     *   which in turn derives from the given object, then this object

     *   derives (indirectly) from the given object.  

     */

    virtual int is_instance_of(VMG_ vm_obj_id_t obj);

    /* 

     *   Get the number of superclasses of the object, and get the nth

     *   superclass.  By default, we have one superclass, which is the

     *   IntrinsicClass object that represents this metaclass.  

     */

    virtual int get_superclass_count(VMG_ vm_obj_id_t /*self*/) const

        { return 1; }

    virtual vm_obj_id_t get_superclass(VMG_ vm_obj_id_t /*self*/,

                                       int /*superclass_index*/) const;

    /*

     *   Determine if the object has properties that can be enumerated.

     *   Returns true if so, false if not.  Note that this should return

     *   true for an object of a type that provides properties, even if

     *   the instance happens to have zero properties.  

     */

    virtual int provides_props(VMG0_) const { return FALSE; }

    /*

     *   Enumerate properties of the object.  Invoke the callback for each

     *   property.  The callback is not permitted to make any changes to

     *   the object or its properties and should not invoke garbage

     *   collection.  

     */

    virtual void enum_props(VMG_ vm_obj_id_t self,

                            void (*cb)(VMG_ void *ctx,

                                       vm_obj_id_t self, vm_prop_id_t prop,

                                       const vm_val_t *val),

                            void *cbctx)

    {

        /* by default, assume we have nothing to enumerate */

    }

    /* set a property value */

    virtual void set_prop(VMG_ class CVmUndo *undo,

                          vm_obj_id_t self, vm_prop_id_t prop,

                          const vm_val_t *val) = 0;

    /* 

     *   Get a property value.  We do not evaluate the property, but

     *   merely get the raw value; thus, if the property value is of type

     *   code, we simply retrieve the code offset pointer.  Returns true

     *   if the property was found, false if not.

     *   

     *   If we find the object, we'll set *source_obj to the ID of the

     *   object in which we found the object.  If the property was

     *   supplied by this object directly, we'll simply set source_id to

     *   self; if we inherited the property from a superclass, we'll set

     *   *source_id to the ID of the superclass object that actually

     *   supplied the value.

     *   

     *   If 'argc' is not null, this function can consume arguments from

     *   the run-time stack, and set *argc to zero to indicate that the

     *   arguments have been consumed.

     *   

     *   If 'argc' is null, and evaluating the property would involve

     *   running system code (with or without consuming arguments), this

     *   function should return TRUE, but should NOT run the system code -

     *   instead, set val->typ to VM_NATIVE_CODE to indicate that the

     *   value is a "native code" value (i.e., evaluating it requires

     *   executing system code).  

     */

    virtual 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);

    /*

     *   Inherit a property value.  This works similarly to get_prop, but

     *   finds an inherited definition of the property, as though

     *   orig_target_obj.prop (and anything overriding orig_target_obj.prop)

     *   were undefined.

     *   

     *   In broad terms, the algorithm for this method is to do the same

     *   thing as get_prop(), but to ignore every definition of the property

     *   found in the class tree until after reaching and skipping

     *   orig_target_obj.prop.  Once orig_target_obj.prop is found, this

     *   method simply continues searching in the same manner as get_prop()

     *   and returns the next definition it finds.

     *   

     *   'defining_obj' is the object containing the method currently

     *   running.  This is not necessarily 'self', because the method

     *   currently running might already have been inherited from a

     *   superclass of 'self'.

     *   

     *   'orig_target_obj' is the object that was originally targeted for the

     *   get_prop() operation that invoked the calling method (or invoked the

     *   method that inherited the calling method, or so on).  This gives us

     *   the starting point in the search, so that we can continue the

     *   original inheritance tree search that started with get_prop().

     *   

     *   'argc' has the same meaning as for get_prop().  

     *   

     *   Objects that cannot be subclassed via byte-code can ignore this

     *   method.  The base class implementation follows the inheritance chain

     *   of "modifier" objects, which allow byte-code methods to be plugged

     *   in under the native code class tree.  

     */

    virtual int inh_prop(VMG_ vm_prop_id_t prop, vm_val_t *retval,

                         vm_obj_id_t self, vm_obj_id_t orig_target_obj,

                         vm_obj_id_t defining_obj, vm_obj_id_t *source_obj,

                         uint *argc);

    /*

     *   Build a list of the properties directly defined on this object

     *   instance.  On return, retval must be filled in with the new list

     *   object.

     *   

     *   Note that a self-reference must be pushed by the caller to protect

     *   against garbage collection of self while this routine is running.

     *   

     *   Most object types do not define any properties in the instance, so

     *   this default implementation will simply return an empty list.

     *   Classes that can define properties in instances (such as

     *   TadsObjects), and the "intrinsic class" class that represents

     *   classes, must override this to build their lists.  

     */

    virtual void build_prop_list(VMG_ vm_obj_id_t self, vm_val_t *retval);

    /* 

     *   Mark all strongly-referenced objects.  Calls

     *   obj_table->mark_refs() for each referenced object.  

     */

    virtual void mark_refs(VMG_ uint state) = 0;

    /* 

     *   Remove stale weak references.  For each weakly-referenced object,

     *   check to see if the object is marked as reachable; if not, it's

     *   about to be deleted, so forget the weak reference. 

     */

    virtual void remove_stale_weak_refs(VMG0_) = 0;

    /*

     *   Receive notification that the undo manager is creating a new

     *   savepoint.  

     */

    virtual void notify_new_savept() = 0;

    /* 

     *   apply an undo record created by this object; if the record has

     *   any additional data associated with it (allocated by the object

     *   when the undo record was created), this should also discard the

     *   additional data 

     */

    virtual void apply_undo(VMG_ struct CVmUndoRecord *rec) = 0;

    /* 

     *   Discard any extra information associated with this undo record.

     *   Note that this will not be called if apply_undo() is called,

     *   since apply_undo() is expected to discard any extra information

     *   itself after applying the record.  

     */

    virtual void discard_undo(VMG_ struct CVmUndoRecord *) { }

    /*

     *   Mark an object object reference.  If this object keeps strong

     *   references, this should mark any object contained in the undo

     *   record's saved value as referenced; if this object keeps only

     *   weak references, this doesn't need to do anything. 

     */

    virtual void mark_undo_ref(VMG_ struct CVmUndoRecord *rec) = 0;

    /*

     *   Remove any stale weak reference contained in an undo record.  For

     *   objects with ordinary strong references, this doesn't need to do

     *   anything.  For objects that keep weak references to other

     *   objects, this should check the object referenced in the undo

     *   record, if any, to determine if the object is about to be

     *   deleted, and if so clear the undo record (by setting the object

     *   in the old value to 'invalid'). 

     */

    virtual void remove_stale_undo_weak_ref(VMG_

                                            struct CVmUndoRecord *rec) = 0;

    /*

     *   Post-load initialization.  This routine is called only if the object

     *   specifically requests this by calling request_post_load_init().

     *   This routine is called exactly once for each initial program load,

     *   restart, or restore, and is called after ALL objects are loaded.

     *   

     *   The purpose of this routine is to allow an object to perform

     *   initializations that depend upon other objects.  During the normal

     *   load/restore/reset methods, an object cannot assume that any other

     *   objects are already loaded, because the order of loading is

     *   arbitrary.  When this routine is called, it is guaranteed that all

     *   objects are already loaded.  

     */

    virtual void post_load_init(VMG_ vm_obj_id_t /*self*/)

    {

        /* we do nothing by default */

    }

    /*

     *   Load the object from an image file.  The object's data block is

     *   at the given address and has the given size.

     *   

     *   The underlying memory is owned by the image file loader.  The

     *   object must not attempt to deallocate this memory.  

     */

    virtual void load_from_image(VMG_ vm_obj_id_t self,

                                 const char *ptr, size_t siz) = 0;

    /*

     *   Reload the object from an image file.  The object's data block is

     *   at the given address and has the given size.  Discards any changes

     *   made since the object was loaded and restores its state as it was

     *   immediately after it was loaded from the image file.  By default,

     *   we do nothing.

     *   

     *   NOTE 1: this routine can be implemented instead of

     *   reset_to_image().  If an object doesn't have any other need to

     *   store a pointer to its image file data in its own extension, but

     *   the image file data is necessary to effect a reset, then this

     *   routine should be used, so as to avoid having to enlarge the

     *   object's extension for non-image instances.

     *   

     *   NOTE 2: in order to use this routine, the object MUST call the

     *   object table's save_image_pointer() routine during the initial

     *   loading (i.e., in the object's load_from_image()).  During a reset,

     *   the object table will only call this routine on objects whose image

     *   pointers were previously saved with save_image_pointer().  

     */

    virtual void reload_from_image(VMG_ vm_obj_id_t self,

                                   const char *ptr, size_t siz) { }

    /*

     *   Reset to the image file state.  Discards any changes made since the

     *   object was loaded and restores its state as it was immediately

     *   after it was loaded from the image file.  By default, we do nothing.

     *   

     *   NOTE: this routine doesn't have to do anything if

     *   reload_from_image() is implemented for the object.  

     */

    virtual void reset_to_image(VMG_ vm_obj_id_t /*self*/) { }

    /*

     *   Determine if the object has been changed since it was loaded from

     *   the image file.  This can only be called for objects that were

     *   originally loaded from the image file.  Returns true if the

     *   object's internal state has been changed since loading, false if

     *   the object is in exactly the same state that's stored in the

     *   image file.

     *   

     *   If this returns false, then it is not necessary to save the

     *   object to a saved state file, because the object's state can be

     *   restored simply by resetting to the image file state.  

     */

    virtual int is_changed_since_load() const { return FALSE; }

    /* 

     *   save this object to a file, so that it can be restored to its

     *   current state via restore_from_file 

     */

    virtual void save_to_file(VMG_ class CVmFile *fp) = 0;

    /* 

     *   Restore the state of the object from a file into which state was

     *   previously stored via save_to_file.  This routine may need

     *   access to the memory manager because it may need to allocate

     *   memory to make room for the variable data.  

     */

    virtual void restore_from_file(VMG_ vm_obj_id_t self,

                                   class CVmFile *fp,

                                   class CVmObjFixup *fixups) = 0;

    /*

     *   Compare to another value for equality.  Returns true if the value is

     *   equal, false if not.  By default, we return true only if the other

     *   value is an object with the same ID (i.e., a reference to exactly

     *   the same instance).  However, subclasses can override this to

     *   provide different behavior; the string class, for example, may

     *   override this so that it compares equal to any string object or

     *   constant containing the same string text.

     *   

     *   'depth' has the same meaning as in calc_hash().  

     */

    virtual int equals(VMG_ vm_obj_id_t self, const vm_val_t *val,

                       int /*depth*/) const

    {

        /* return true if the other value is a reference to this object */

        return (val->typ == VM_OBJ && val->val.obj == self);

    }

    /*

     *   Compare magnitude of this object and another object.  Returns a

     *   positive value if this object is greater than the other object, a

     *   negative value if this object is less than the other object, or

     *   zero if this object equals the other object.  Throws an error if

     *   a magnitude comparison is not meaningful between the two objects.

     *   

     *   By default, magnitude comparisons between objects are not

     *   meaningful, so we throw an error. 

     */

    virtual int compare_to(VMG_ vm_obj_id_t /*self*/, const vm_val_t *) const

    {

        /* by default, magnitude comparisons between objects are illegal */

        err_throw(VMERR_INVALID_COMPARISON);

        /* the compiler doesn't know that we'll never get here */

        AFTER_ERR_THROW(return 0;)

    }

    /*

     *   Calculate a hash value for the object.

     *   

     *   'depth' is the recursion depth of the hash calculation.  Objects

     *   that can potentially contain cyclical references back to themselves,

     *   and which follow those references to calculate the hash value

     *   recursively, must check the depth counter to see if it exceeds

     *   VM_MAX_TREE_DEPTH_EQ, throwing VMERR_TREE_TOO_DEEP_EQ if so; and

     *   they must increment the depth counter in the recursive traversals.

     *   Objects that don't traverse into their contents can ignore the depth

     *   counter.  

     */

    virtual uint calc_hash(VMG_ vm_obj_id_t self, int /*depth*/) const

    {

        /* 

         *   by default, use a 16-bit hash of our object ID as the hash

         *   value 

         */

        return (uint)(((ulong)self & 0xffff)

                      ^ (((ulong)self & 0xffff0000) >> 16));

    }

    /* 

     *   Add a value to this object, returning the result in *result.

     *   This may create a new object to hold the result, or may modify

     *   the existing object in place, depending on the subclass

     *   implementation.  'self' is the object ID of this object.

     *   

     *   By default, we'll throw an error indicating that the value cannot

     *   be added.  

     */

    virtual void add_val(VMG_ vm_val_t * /*result*/,

                         vm_obj_id_t /*self*/, const vm_val_t * /*val*/)

    {

        /* throw an error */

        err_throw(VMERR_BAD_TYPE_ADD);

    }

    /*

     *   Subtract a value from this object, returning the result in

     *   *result.  This may create a new object to hold the result, or may

     *   modify the existing object in place, depending upon the subclass

     *   implementation.  'self' is the object ID of this object.  

     */

    virtual void sub_val(VMG_ vm_val_t * /*result*/,

                         vm_obj_id_t /*self*/, const vm_val_t * /*val*/)

    {

        /* throw an error */

        err_throw(VMERR_BAD_TYPE_SUB);

    }

    /* multiply this object by a value, returning the result in *result */

    virtual void mul_val(VMG_ vm_val_t * /* result*/,

                         vm_obj_id_t /*self*/, const vm_val_t * /*val*/)

    {

        /* throw an error */

        err_throw(VMERR_BAD_TYPE_MUL);

    }

    /* divide a value into this object, returning the result in *result */

    virtual void div_val(VMG_ vm_val_t * /* result*/,

                         vm_obj_id_t /*self*/, const vm_val_t * /*val*/)

    {

        /* throw an error */

        err_throw(VMERR_BAD_TYPE_DIV);

    }

    /* negate the value, returning the result in *result */

    virtual void neg_val(VMG_ vm_val_t * /* result */, vm_obj_id_t self)

    {

        /* throw an error */

        err_throw(VMERR_BAD_TYPE_NEG);

    }

    /*

     *   Get the effective number of values this value contributes when

     *   used as the right-hand side of a '+' or '-' operator with a

     *   left-hand type that treats these operators as concatenation/set

     *   subtraction operators.  By default, a value adds/subtracts only

     *   itself, but certain collection types (List, Vector, Array)

     *   add/subtract their elements individually. 

     */

    virtual size_t get_coll_addsub_rhs_ele_cnt(VMG0_) const

    {

        /* by default, we contribute only 'self', thus only one element */

        return 1;

    }

    /* get the nth element as the rhs of a collection add/subtract */

    virtual void get_coll_addsub_rhs_ele(VMG_ vm_val_t *retval,

                                         vm_obj_id_t self, size_t /*idx*/) 

    {

        /* by default, we contribute only 'self' */

        retval->set_obj(self);

    }

    /*

     *   Index the object.  Most object types cannot be indexed, so by

     *   default we'll throw an error.  Subclasses that can be indexed

     *   (such as lists) should look up the element given by the index

     *   value, and store the value at that index in *result.  

     */

    virtual void index_val(VMG_ vm_val_t * /*result*/,

                           vm_obj_id_t /*self*/,

                           const vm_val_t * /*index_val*/)

    {

        /* by default, throw an error */

        err_throw(VMERR_CANNOT_INDEX_TYPE);

    }

    /*

     *   Set an indexed element of the object, and fill in *new_container

     *   with the new object that results if an entire new object is

     *   created to hold the modified contents, or with the original

     *   object if the contents of the original object are actually

     *   modified by this operation.  Lists, for example, cannot be

     *   modified, so always create a new list object when an element is

     *   set; arrays, in contrast, can be directly modified, so will

     *   simply return 'self' in *new_container.

     *   

     *   By default, we'll throw an error, since default objects cannot be

     *   indexed.  

     */

    virtual 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*/)

    {

        /* by default, throw an error */

        err_throw(VMERR_CANNOT_INDEX_TYPE);

    }

    /*

     *   Get a string representation of the object.  If necessary, this

     *   can create a new string object to represent the result.

     *   

     *   Returns the string representation in portable string format: the

     *   first two bytes give the byte length of the rest of the string in

     *   portable UINT2 format, and immediately following the length

     *   prefix are the bytes of the string's contents.  The length prefix

     *   does not count the length prefix itself in the length of the

     *   string.

     *   

     *   If a new string object is created, new_str must be set to a

     *   reference to the new string object.  If a pointer into our data

     *   is returned, we must set new_str to self.  If no object data are

     *   involved, new_str can be set to nil.

     *   

     *   If it is not possible to create a string representation of the

     *   object, throw an error (VMERR_NO_STR_CONV).

     *   

     *   By default, we'll throw an error indicating that the object

     *   cannot be converted to a string.  

     */

    virtual const char *cast_to_string(VMG_ vm_obj_id_t /*self*/,

                                       vm_val_t * /*new_str*/) const

    {

        /* throw an error */

        err_throw(VMERR_NO_STR_CONV);

        /* we can't get here, but the compiler doesn't know that */

        AFTER_ERR_THROW(return 0;)

    }

    /*

     *   Get the list contained in the object, if possible, or null if

     *   not.  If the value contained in the object is a list, this

     *   returns a pointer to the list value in portable format (the first

     *   two bytes are the length prefix as a portable UINT2, and the

     *   subsequent bytes form a packed array of data holders in portable

     *   format).

     *   

     *   Most object classes will return null for this, since they do not

     *   store lists.  By default, we return null.

     */

    virtual const char *get_as_list() const { return 0; }

    /*

     *   Get the string contained in the object, if possible, or null if

     *   not.  If the value contained in the object is a string, this

     *   returns a pointer to the string value in portable format (the

     *   first two bytes are the string prefix as a portable UINT2, and

     *   the bytes of the string's text immediately follow in UTF8 format).

     *   

     *   Most object classes will return null for this, since they do not

     *   store strings.  By default, we return null.  

     */

    virtual const char *get_as_string(VMG0_) const { return 0; }

    /*

     *   Rebuild the image data for the object.  This is used to write the

     *   program state to a new image file after executing the program for

     *   a while, such as after a 'preinit' step after compilation.

     *   

     *   This should write the complete metaclass-specific record needed

     *   for an OBJS data block entry, not including the generic header.

     *   

     *   On success, return the size in bytes of the data stored to the

     *   buffer; these bytes must be copied directly to the new image

     *   file.  If the given buffer isn't big enough, this should return

     *   the size needed and otherwise leave the buffer empty.  If the

     *   object doesn't need to be written at all, this should return

     *   zero.  

     */

    virtual ulong rebuild_image(VMG_ char *, ulong)

        { return 0; }

    /*

     *   Allocate space for conversion to constant data for storage in a

     *   rebuilt image file.  If this object can be stored as constant

     *   data in a rebuilt image file, this should reserve space in the

     *   provided constant mapper object for the object's data in

     *   preparation for conversion.

     *   

     *   Most objects cannot be converted to constant data, so the default

     *   here does nothing.  Those that can, such as strings and lists,

     *   should override this.  

     */

    virtual void reserve_const_data(VMG_ class CVmConstMapper *,

                                    vm_obj_id_t /*self*/)

        { /* default does nothing */ }

    /*

     *   Convert to constant data.  If this object can be stored as

     *   constant data in a rebuilt image file, it should override this

     *   routine to store its data in the provided constant mapper object.

     *   If this object makes reference to other objects, it must check

     *   each object that it references to determine if the object has a

     *   non-zero address in the mapper, and if so must convert its

     *   reference to the object to a constant data item at the given

     *   address.  There is no default implementation of this routine,

     *   because it must be overridden by essentially all objects (at

     *   least, it must be overridden by objects that can be converted or

     *   that can refer to objects that can be converted).  

     */

    virtual void convert_to_const_data(VMG_ class CVmConstMapper *,

                                       vm_obj_id_t /*self*/)

        { /* default does nothing */ }

    /*

     *   Get the type that this object uses when converted to constant

     *   data.  Objects that can be converted to constant data via

     *   convert_to_const_data() should return the appropriate type

     *   (VM_SSTRING, VM_LIST, etc); others can return VM_NIL to indicate

     *   that they have no conversion.  This will be called only when an

     *   object actually has been converted as indicated in a mapper

     *   (CVmConstMapper) object.  We'll return NIL by default.  

     */

    virtual vm_datatype_t get_convert_to_const_data_type() const

        { return VM_NIL; }

    /*

     *   Allocate memory for the fixed part from a memory manager.  We

     *   override operator new so that we can provide custom memory

     *   management for object headers.

     *   

     *   To create an object, use a sequence like this:

     *   

     *   obj_id = mem_mgr->get_obj_table()->alloc_obj(vmg_ in_root_set);

     *.  new (vmg_ obj_id) CVmObjString(subclass constructor params)

     *   

     *   The caller need not store the result of 'new'; the caller

     *   identifies the object by the obj_id value.

     *   

     *   Each CVmObject subclass should provide static methods that cover

     *   the above sequence, since it's a bit verbose to sprinkle

     *   throughout client code.  

     */

    void *operator new(size_t siz, VMG_ vm_obj_id_t obj_id);

protected:

    /*

     *   Find a modifier property.  This is an internal service routine that

     *   we use to traverse the hierarchy of modifier objects associated with

     *   our intrinsic class hierarchy.  

     */

    int find_modifier_prop(VMG_ vm_prop_id_t prop, vm_val_t *retval,

                           vm_obj_id_t self, vm_obj_id_t orig_target_obj,

                           vm_obj_id_t defining_obj, vm_obj_id_t *source_obj,

                           uint *argc);

    /*

     *   Service routine - check a get_prop() argument count for executing

     *   a native code method implementation.  If 'argc' is null, we'll

     *   set the value to a VM_NATIVE_CODE indication and return true,

     *   which the caller should do from get_prop() as well.  If 'argc' is

     *   non-null, we'll check it against the given required argument

     *   count, and throw an error if it doesn't match.  If 'argc' is

     *   non-null and it matches the given argument count, we'll set *argc

     *   to zero to indicate that we've consumed the arguments, and return

     *   false - get_prop() should in this case execute the native code

     *   and return the appropriate result value.  

     */

    static int get_prop_check_argc(vm_val_t *val, uint *argc,

                                   const CVmNativeCodeDesc *desc)

    {

        /* 

         *   if there's no 'argc', we can't execute the native code - we're

         *   simply being asked for a description of the method, not to

         *   evaluate its result 

         */

        if (argc == 0)

        {

            /* indicate a native code evaluation is required */

            val->set_native(desc);

            /* tell get_prop() to return without further work */

            return TRUE;

        }

        /* check the argument count - throw an error if out of range */

        if (!desc->args_ok(*argc))

            err_throw(VMERR_WRONG_NUM_OF_ARGS);

        /* everything's fine - consume the arguments */

        *argc = 0;

        /* tell get_prop() to proceed with the native evaluation */

        return FALSE;

    }

#if 0

    /*

     *   Important note:

     *   

     *   This function has been removed because we no longer consider it

     *   likely that we will ever wish to implement a relocating heap

     *   manager.  Given the large memory sizes of modern computers, and

     *   recent academic research calling into question the conventional

     *   wisdom that heap fragmentation is actually a problem in practical