/* 
 *   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
  vmbytarr.h - T3 ByteArray metaclass
Function
  
Notes
  
Modified
  06/05/01 MJRoberts  - Creation
*/

#ifndef VMBYTARR_H
#define VMBYTARR_H

#include <stdlib.h>
#include "os.h"
#include "vmtype.h"
#include "vmobj.h"
#include "vmglob.h"

/* ------------------------------------------------------------------------ */
/*
 *   A ByteArray is simply an array of byte values.  This class provides a
 *   simple, fast mechanism to store blocks of binary data, so it is not a
 *   subclass of Array and is not a Collection.
 *   
 *   The image file data for a byte array is simple:
 *   
 *   UINT4 number of bytes
 *.  BYTE bytes[1..number_of_bytes]
 *   
 *   Internally, we store the array data in chunks of 32k each.  Our
 *   extension is a first-level page table, pointing to the chunks:
 *   
 *   UINT4 number of elements
 *.  unsigned char **page0
 *.  unsigned char **page1
 *.  ...
 *   
 *   Each pageN pointer points to a second-level page table, which consists
 *   of (up to) 8192 pointers to the actual pages.  Since a page is 32k, and
 *   we can store 8k pointers per second-level table, each second-level
 *   table is capable of referencing 256MB.  By design, we can store up to
 *   4GB, so we need at most 16 second-level tables.
 *   
 *   The extension is allocated according to the actual number of
 *   second-level tables we require for the element count.  Each
 *   second-level page is allocated to 8192*sizeof(char *), except the last
 *   second-level page, which is allocated to N*sizeof(char *) where N is
 *   the number of elements required in the last second-level table.  Each
 *   page is allocated to 32K bytes, except the last, which is allocated to
 *   the actual size needed.
 *   
 *   To access an element at index i, we calculate s1 (the page table
 *   selector) as i/(32k*8k) == i/256M; s2 (the page selector within the
 *   selected page table) as (i%256M)/32k; and s3 (the byte selector within
 *   the page) as i%32k.  The byte is then accessed as
 *   
 *   page[s1][s2][s3] 
 */
class CVmObjByteArray: public CVmObject
{
    friend class CVmMetaclassByteArray;
    friend class bytearray_undo_rec;
    
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_
                || CVmObject::is_of_metaclass(meta));
    }

    /* 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)
    {
        /* explicitly inherit our superclass handling */
        return CVmObject::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 reference no other objects and cannot ourselves be converted
         *   to constant data, so there's nothing to do here 
         */
    }

    /* convert to constant data */
    virtual void convert_to_const_data(VMG_ class CVmConstMapper *mapper,
                                       vm_obj_id_t self)
    {
        /* 
         *   we reference no data and cannot be converted to constant data,
         *   so there's nothing to do 
         */
    }

    /* create an array with no initial contents */
    static vm_obj_id_t create(VMG_ int in_root_set);

    /* create an array with a given number of elements */
    static vm_obj_id_t create(VMG_ int in_root_set,
                              unsigned long element_count);

    /* 
     *   determine if an object is a byte array - it is if the object's
     *   virtual metaclass registration index matches the class's static
     *   index 
     */
    static int is_byte_array(VMG_ vm_obj_id_t obj)
        { return vm_objp(vmg_ obj)->is_of_metaclass(metaclass_reg_); }

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

    /* undo operations */
    void notify_new_savept() { }
    void apply_undo(VMG_ struct CVmUndoRecord *rec);
    void discard_undo(VMG_ struct CVmUndoRecord *);

    /* our data are just bytes - we reference nothing */
    void mark_undo_ref(VMG_ struct CVmUndoRecord *) { }
    void remove_stale_undo_weak_ref(VMG_ struct CVmUndoRecord *) { }
    void mark_refs(VMG_ uint /*state*/) { }
    void remove_stale_weak_refs(VMG0_) { }

    /* load from an image file */
    void load_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);

    /* reload from the image file */
    void reload_from_image(VMG_ vm_obj_id_t self,
                           const char *ptr, size_t siz);

    /* 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 *fixup);

    /* index the array */
    void index_val(VMG_ vm_val_t *result, vm_obj_id_t self,
                   const vm_val_t *index_val);

    /* set an indexed element of the array */
    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);

    /* 
     *   Check a value for equality.  We will match another byte array with
     *   the same number of elements and the same value for each element.  
     */
    int equals(VMG_ vm_obj_id_t self, const vm_val_t *val, int depth) const;

    /* calculate a hash value for the array */
    uint calc_hash(VMG_ vm_obj_id_t self, int depth) const;

    /* 
     *   assume that we've been changed since loading, if we came from the
     *   image file 
     */
    int is_changed_since_load() const { return TRUE; }

    /* get the number of elements in the array */
    unsigned long get_element_count() const
        { return t3rp4u(get_ext_ptr()); }

    /* 
     *   construction: copy (without undo) bytes from a buffer into the byte
     *   array 
     */
    void cons_copy_from_buf(const unsigned char *buf,
                            unsigned long idx, size_t cnt)
    {
        /* copy the bytes into our array */
        copy_from_buf(buf, idx, cnt);
    }

    /* 
     *   Write the specified region of the array to a file.  Returns zero on
     *   success, non-zero on failure. 
     */
    int write_to_file(osfildef *fp, unsigned long start_idx,
                      unsigned long len) const;

    /* 
     *   Read bytes from a file into a region of the array, replacing
     *   existing bytes in the array; saves undo for the change.  Returns
     *   the number of bytes actually read from the file, which will be less
     *   than the number of bytes requested if we reach the end of the file
     *   before satisfying the request.  
     */
    unsigned long read_from_file(osfildef *fp, unsigned long start_idx,
                                 unsigned long len);

    /* 
     *   write to a 'data' mode file - returns zero on success, non-zero on
     *   failure 
     */
    int write_to_data_file(osfildef *fp);

    /* 
     *   read from a 'data' mode file, creating a new ByteArray object to
     *   hold the bytes from the file 
     */
    static int read_from_data_file(VMG_ vm_val_t *retval, osfildef *fp);

protected:
    /* load image data */
    virtual void load_image_data(VMG_ const char *ptr, size_t siz);

    /* create a list with no initial contents */
    CVmObjByteArray() { ext_ = 0; }

    /* 
     *   create a list with a given number of elements, for construction
     *   of the list element-by-element 
     */
    CVmObjByteArray(VMG_ unsigned long byte_count);

    /* get a pointer to my extension */
    const char *get_ext_ptr() const { return ext_; }

    /* 
     *   get my extension data pointer for construction purposes - this is
     *   a writable pointer, so that a caller can fill our data buffer
     *   during construction 
     */
    char *cons_get_ext_ptr() const { return ext_; }

    /* allocate space for the array, given the number of elements */
    void alloc_array(VMG_ unsigned long element_count);

    /* property evaluator - undefined function */
    int getp_undef(VMG_ vm_obj_id_t, vm_val_t *, uint *) { return FALSE; }

    /* property evaluator - length */
    int getp_length(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - subarray */
    int getp_subarray(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - copy from another byte array */
    int getp_copy_from(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - fill with a value */
    int getp_fill_val(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - convert to string */
    int getp_to_string(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - read integer */
    int getp_read_int(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* property evaluator - write integer */
    int getp_write_int(VMG_ vm_obj_id_t self, vm_val_t *val, uint *argc);

    /* 
     *   Given a 1-based index, get a pointer to the byte at the index, and
     *   the number of contiguous bytes available starting with that byte.
     *   The available byte count doesn't take into account a short last
     *   page, but simply returns the maximum number of bytes that would be
     *   available on the page if it were allocated to full size; the caller
     *   is responsible for ensuring that there is no reading or writing
     *   past the end of the array.  
     */
    unsigned char *get_ele_ptr(unsigned long idx, size_t *bytes_avail) const
    {
        size_t s1;
        size_t s2;
        size_t s3;

        /* convert to a zero-based index */
        --idx;
        
        /* 
         *   calculate the page table index - since each page holds 32k
         *   bytes and each page table points to 8k pages, divide by 32k*8k
         *   == 2^15*2^13 == 2^28 
         */
        s1 = idx >> 28;

        /* 
         *   calculate the page index within the page table - each page
         *   holds 32k, so calculate the excess from the page table selector
         *   (i.e, idx % 32k*8k) and then divide by 32k == 2^15 
         */
        s2 = (idx & 0x0FFFFFFF) >> 15;

        /* 
         *   calculate the page offset - this is simply the excess from the
         *   page index 
         */
        s3 = idx & 0x7FFF;

        /*
         *   Each page holds 32k, so the number of contiguous bytes starting
         *   at this byte is 32k less the index.  
         */
        *bytes_avail = (32*1024) - s3;

        /* 
         *   dereference the extension to get the page table, deference the
         *   page table to get the page, and index the page by the offset 
         */
        return get_page_table_ptr(s1)[s2] + s3;
    }

    /*
     *   Given a page table selector, return a pointer to the selected page
     *   table.  
     */
    unsigned char **get_page_table_ptr(size_t s) const
    {
        return get_page_table_array()[s];
    }

    /*
     *   Get a pointer to the page table array 
     */
    unsigned char ***get_page_table_array() const
    {
        /* the page table array starts after the element count */
        return (unsigned char ***)(ext_ + 4);
    }

    /* fill the given (1-based index) range with the given byte value */
    void fill_with(unsigned char val, unsigned long start_idx,
                   unsigned long cnt);

    /* copy bytes from another byte array into this one */
    void copy_from(unsigned long dst_idx,
                   CVmObjByteArray *src_arr,
                   unsigned long src_start_idx, unsigned long cnt);

    /* move bytes within this array */
    void move_bytes(unsigned long dst_idx, unsigned long src_idx,
                    unsigned long cnt);

    /* copy bytes into a buffer */
    void copy_to_buf(unsigned char *buf, unsigned long idx, size_t cnt) const;

    /* copy bytes from a buffer into the array */
    void copy_from_buf(const unsigned char *buf,
                       unsigned long idx, size_t cnt);

    /* map to a string */
    size_t map_to_string(unsigned long idx, unsigned long len,
                         class CVmObjString *str, size_t str_len,
                         class CCharmapToUni *mapper);
    
    /* save undo for a change to a range of the array */
    void save_undo(VMG_ vm_obj_id_t self, unsigned long start_idx,
                   unsigned long cnt);

    /* set the number of bytes in the array */
    void set_element_count(unsigned long cnt)
        { oswp4(cons_get_ext_ptr(), cnt); }

    /* property evaluation function table */
    static int (CVmObjByteArray::*func_table_[])(
        VMG_ vm_obj_id_t self, vm_val_t *retval, uint *argc);
};

/* ------------------------------------------------------------------------ */
/*
 *   Registration table object 
 */
class CVmMetaclassByteArray: public CVmMetaclass
{
public:
    /* get the global name */
    const char *get_meta_name() const { return "bytearray/030001"; }

    /* create from image file */
    void create_for_image_load(VMG_ vm_obj_id_t id)
    {
        new (vmg_ id) CVmObjByteArray();
        G_obj_table->set_obj_gc_characteristics(id, FALSE, FALSE);
    }

    /* create from restoring from saved state */
    void create_for_restore(VMG_ vm_obj_id_t id)
    {
        new (vmg_ id) CVmObjByteArray();
        G_obj_table->set_obj_gc_characteristics(id, FALSE, FALSE);
    }

    /* create dynamically using stack arguments */
    vm_obj_id_t create_from_stack(VMG_ const uchar **pc_ptr, uint argc)
        { return CVmObjByteArray::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 CVmObjByteArray::
            call_stat_prop(vmg_ result, pc_ptr, argc, prop);
    }
};

#endif /* VMBYTARR_H */


/*
 *   Register the class 
 */
VM_REGISTER_METACLASS(CVmObjByteArray)