def func_turn_into_waldo_var(
        self,val,force_copy,active_event, host_uuid,new_peered,
        ext_args_array,new_multi_threaded):
        '''
        turn_into_waldo_var works for all non-function types.
        function-types require additional information (which arguments
        are and are not external) to populate their ext_args_array.
        This is passed in in this function.
        '''
        if isinstance(val,wVariables.WaldoFunctionVariable):
            if force_copy:
                # means that it was a WaldoVariable: just call its copy
                # method
                return val.copy(active_event,new_peered,new_multi_threaded)
            # otherwise, just return val
            return val
        elif hasattr(val,'__call__'):
            # python function
            pass
        #### DEBUG
        else:
            util.logger_assert(
                'incorrect type passed into func_turn_into_waldo_var')
        #### END DEBUG

        waldo_func = wVariables.WaldoFunctionVariable(
            'garbage',
            host_uuid,
            new_peered,
            val).set_external_args_array(ext_args_array)

        return waldo_func

 def var_type():
     '''
     @returns {String} --- Each subtype of _ReferenceBase has a
     unique name.
     '''
     util.logger_assert(
         'var_type is pure virtual in _ReferenceBase.')

    def update_val_of_key_during_deserialize(
        self,invalid_listener,key,val):
        '''
        @param {Text,Number,TrueFalse} key --- The index of the
        internal map or list (if list, then key is just a number)

        @param {Anything} val --- Can be a python value or pointers to
        additional Waldo variables.

        Called when deserializing nested maps/lists.  See case 4 in
        the comments for the method
        waldoNetworkSerializer.deserialize_peered_object_into_variables.
        '''
        #### DEBUG
        # note only should be serializing and deserializing peered data
        if not self.peered:
            util.logger_assert(
                'Should not be updating value and version for a ' +
                'non-peered data item.')
        #### END DEBUG
        self._lock()
        self._add_invalid_listener(invalid_listener)
        dirty_element = self._dirty_map[invalid_listener.uuid]
        dirty_element.val[key] = val
        self._unlock()

 def is_value_type(self):
     '''
     @returns {bool} --- True if the reference base points at a
     value type (Text, Bool, Number).  False otherwise.
     '''
     util.logger_assert(
         'is_value_type is pure virtual in _ReferenceBase.')

    def call_func_obj(
        self,active_event,func_obj,*args):
        '''
        @param {wVariable.WaldoFunctionVariable} func_obj --- The
        wrapped function that we are calling.

        @param {*args} --- The actual arguments that get passed to the
        function.
        '''
        # {list} external_arg_list --- Each element is a number.
        # If a number is in this list, then that means that the
        # corresponding argument to func_obj is external and therefore
        # should not be de_waldo-ified.  If an argument does not have
        # its corresponding index in the array, then dewaldo-ify it.
        external_arg_list = func_obj.ext_args_array

        if external_arg_list == None:
            util.logger_assert(
                'No external arg array for function object')
        
        call_arg_list = []
        for counter in range(0,len(args)):
            to_append = args[counter]
            if counter not in external_arg_list:
                to_append = self.de_waldoify(to_append,active_event)

            call_arg_list.append(to_append)

            
        internal_func = func_obj.get_val(active_event)
        return internal_func(
            active_event.local_endpoint,*call_arg_list)

def create_new_variable_wrapper_from_serialized(
    host_uuid,serial_obj_named_tuple):
    '''
    @param {collections.namedtuple} serial_obj_named_tuple --- @see
    util._generate_serialization_named_tuple.  Should have elements
    var_name, var_type,var_data, version_obj_data.    

    When we are deserializing sequence local objects from messages
    sent from partner endpoint, we may not already have a
    waldoVariable to deserialize the variable into using
    deserialize_peered_object_into_variable.  In this case, we should
    first create a new _WaldoVariable to serialize into.

    This function takes a serial_obj_named_tuple, and returns a new
    variable with corresponding type to its var_type
    '''
    var_name = serial_obj_named_tuple.var_name
    var_type = serial_obj_named_tuple.var_type
    #### DEBUG: Testing whether got a valid type
    if var_type not in ReferenceTypeConstructorDict:
        util.logger_assert(
            'Error when in waldoNetworkSerializer.create_new_variable_' +
            'wrapper_from_serialized.  ' +
            'Unknown Waldo type requested for deserialization.')
    #### END DEBUG

    var_constructor = ReferenceTypeConstructorDict[var_type]
    if var_type == wVariables.WaldoUserStructVariable.var_type():
        # user structs require dict initializers.  for the time being,
        # it's okay to just write in an empt dict because we know we
        # will overwrite it anyways.
        return var_constructor(var_name,host_uuid,True,{})
        
    return var_constructor(var_name,host_uuid,True)

    def __init__(self, filename, name, host_uuid, peered=False, init_val=None):
        self.filename = filename

        if peered:
            util.logger_assert("Cannot peer a file")

        WaldoTextVariable.__init__(self, name, host_uuid, False, init_val)
        self.flush_file(self.val)

 def de_waldoify(self,invalid_listener):
     '''
     Returns a Python-ized version of this object accessed by the
     current invalid listener.  Eg., if it was a Waldo number that
     wrapped 2, then it just returns 2.  Lists, maps and strings
     are more complex.
     '''
     util.logger_assert(
         'de_waldoify is pure virtual in _ReferenceBase.')

 def copy(self,invalid_listener,peered):
     '''
     Returns a deep copy of this object.  Useful when assigning
     to/from a peered variable.  Eg., if have a peered map of
     lists, any list that we assign into the map should be copied
     as peered first.  This way, avoid problem of sharing references.
     '''
     util.logger_assert(
         'copy is pure virtual in _ReferenceBase.')

    def add_to_delta_list(self,delta_to_add_to,current_internal_val,action_event):
        '''
        @param delta_to_add_to --- Either
        varStoreDeltas.SingleMapDelta or
        varStoreDeltas.SingleListDelta

        We log all operations on this variable 
        '''
        util.logger_assert(
            'Pure virutal add_to_delta_list in waldoReferenceContainerBase')

    def __init__(self, name, host_uuid, peered=False, init_val=None):
        """
        @param {dict} init_val --- Required to be non-None.  Contains
        a mapping of names to WaldoVariables.  Each name corresponds
        to one of the variable fields in the struct.  
        """
        if not isinstance(init_val, dict):
            util.logger_assert("User structs must always have init_vals.  " + "Otherwise, not initializing struct data")

        WaldoMapVariable.__init__(self, name, host_uuid, peered, init_val)

def _map_get_delete_key_incorporate_deltas(container_deleted_action):
    if container_deleted_action.HasField('deleted_key_text'):
        index_to_del_from = container_deleted_action.deleted_key_text
    elif container_deleted_action.HasField('deleted_key_num'):
        index_to_del_from = container_deleted_action.deleted_key_num
    elif container_deleted_action.HasField('deleted_key_tf'):
        index_to_del_from = container_deleted_action.deleted_key_tf
    #### DEBUG
    else:
        util.logger_assert('Error in delete: unknown key type.')
    #### END DEBUG

    return index_to_del_from

def _map_get_add_key_incorporate_deltas(container_added_action):
    if container_added_action.HasField('added_key_text'):
        index_to_add_to = container_added_action.added_key_text
    elif container_added_action.HasField('added_key_num'):
        index_to_add_to = container_added_action.added_key_num
    elif container_added_action.HasField('added_key_tf'):
        index_to_add_to = container_added_action.added_key_tf
    #### DEBUG
    else:
        util.logger_assert('Unknown map index')
    #### END DEBUG

    return index_to_add_to

    def add_var(self,unique_name,waldo_variable):
        '''
        @param {String} unique_name ---

        @param {_WaldoVariable} waldo_variable 
        '''
        #### DEBUG
        if self.get_var_if_exists(unique_name) != None:
            util.logger_assert(
                'Already had an entry for variable trying to ' +
                'insert into store.')
        #### END DEBUG
            
        self._name_to_var_map[unique_name] = waldo_variable

    def serializable_var_tuple_for_network(
        self,parent_delta,var_name,invalid_listener,force):
        '''
        @see waldoReferenceBase.serializable_var_tuple_for_network
        '''
        self._lock()
        self._add_invalid_listener(invalid_listener)
        dirty_element = self._dirty_map[invalid_listener.uuid]
        self._unlock()

        version_obj = dirty_element.version_obj

        is_var_store = False
        if parent_delta.parent_type == VarStoreDeltas.VAR_STORE_DELTA:
            is_var_store = True
            struct_delta = parent_delta.struct_deltas.add()
        elif parent_delta.parent_type  == VarStoreDeltas.CONTAINER_WRITTEN:            
            struct_delta = parent_delta.what_written_map
        elif parent_delta.parent_type  == VarStoreDeltas.CONTAINER_ADDED:
            struct_delta = parent_delta.added_what_map
        elif parent_delta.parent_type == VarStoreDeltas.SUB_ELEMENT_ACTION:
            struct_delta = parent_delta.struct_delta
        else:
            util.logger_assert('Unexpected parent container type when serializing map')
            
        struct_delta.parent_type = VarStoreDeltas.STRUCT_CONTAINER
        struct_delta.var_name = var_name
        struct_delta.has_been_written = version_obj.has_been_written_since_last_message

        # reset has been written to
        written_since_last_message = version_obj.has_been_written_since_last_message
        version_obj.has_been_written_since_last_message = False

        
        var_data = dirty_element.val
        internal_has_been_written = var_data.serializable_var_tuple_for_network(
            struct_delta,'',invalid_listener,
            # must force the write when we have written a new value over list
            force or written_since_last_message)
        

        # FIXME: check to ensure that second part of condition will
        # still hide elements that do not change
        if (not internal_has_been_written) and is_var_store and (not written_since_last_message):
            # remove the newly added map delta because there were no
            # changes that it encoded
            del parent_delta.struct_deltas[-1]

        return internal_has_been_written or written_since_last_message or force

    def call_func_obj(
        self,active_event,func_obj,*args):
        '''
        @param {wVariable.WaldoFunctionVariable} func_obj --- The
        wrapped function that we are calling.

        @param {*args} --- The actual arguments that get passed to the
        function.
        '''
        # {list} external_arg_list --- Each element is a number.
        # If a number is in this list, then that means that the
        # corresponding argument to func_obj is external and therefore
        # should not be de_waldo-ified.  If an argument does not have
        # its corresponding index in the array, then dewaldo-ify it.
        external_arg_list = func_obj.ext_args_array

        if external_arg_list == None:
            util.logger_assert(
                'No external arg array for function object')
        
        call_arg_list = []
        for counter in range(0,len(args)):
            to_append = args[counter]
            if counter not in external_arg_list:
                to_append = self.de_waldoify(to_append,active_event)

            call_arg_list.append(to_append)

        internal_func = func_obj.get_val(active_event)
        returned_val = internal_func(
            active_event.local_endpoint,*call_arg_list)

        if isinstance(returned_val,list):
            return wVariables.WaldoSingleThreadListVariable(
                'garbage', # actual name of variable isn't important
                active_event.local_endpoint._host_uuid,
                False, # not peered
                returned_val# used as initial value
                )

        elif isinstance(returned_val,dict):
            return wVariables.WaldoSingleThreadMapVariable(
                'garbage', # actual name of variable isn't important
                active_event.local_endpoint._host_uuid,
                False, # not peered
                returned_val# used as initial value
                )        
        
        return returned_val

 def update_version_obj_during_deserialize(
     self,invalid_listener,new_version_obj):
     '''
     @see update_val_of_key_during_deserialize
     '''
     #### DEBUG        
     # note only should be serializing and deserializing peered data
     if not self.peered:
         util.logger_assert(
             'Should not be updating value and version for a ' +
             'non-peered data item.')
     #### END DEBUG
     self._lock()
     self._add_invalid_listener(invalid_listener)
     dirty_element = self._dirty_map[invalid_listener.uuid]
     dirty_element.version_obj = new_version_obj
     self._unlock()

    def get_for_iter(self,to_iter_over,active_event):
        '''
        When call for loop on Waldo variables, need to get item to
        iterate over
        '''

        if (isinstance(to_iter_over,dict) or
            isinstance(to_iter_over,list) or
            util.is_string(to_iter_over)):
            return iter(to_iter_over)

        if wVariables.is_non_ext_text_var(to_iter_over):
            return iter(to_iter_over.get_val(active_event))

        if wVariables.is_non_ext_map_var(to_iter_over):
            return iter(to_iter_over.get_val(active_event).get_keys(active_event))

        if wVariables.is_non_ext_list_var(to_iter_over):
            # FIXME: This is an inefficient way of reading all values
            # over list.
            to_return = []
            for i in range(0, to_iter_over.get_val(active_event).get_len(active_event)):
                to_append = to_iter_over.get_val(active_event).get_val_on_key(active_event,i)

                # The reason that we do this here is that in a for
                # loop, the operation we perform in the compiled code
                # immediately following the actual for header is
                # assign to another Waldo variable the variable being
                # held by to_append.  (We do this through a write_val
                # call.  write_val must take in InternalMaps or
                # InternalLists.  Therefore, get_val on the
                # WaldoList/WaldoMap first.  Note this is unnecessary
                # for all other for iterations because none of the
                # others possibly return a WaldoObject to iterate over.
                if (wVariables.is_non_ext_list_var(to_append) or
                    wVariables.is_non_ext_map_var(to_append)):
                    to_append = to_append.get_val(active_event)
                
                to_return.append(to_append)

            return iter(to_return)

        util.logger_assert(
            'Calling get_for_iter on an object that does not support iteration')

def get_constructed_obj(
    var_type,var_name,host_uuid,peered,init_data,invalidation_listener):
    '''
    @returns {WaldoReferenceObject} --- Either a wVariable or an
    InternalList or InternalMap.
    '''
    #### DEBUG
    if var_type not in ReferenceTypeConstructorDict:
        util.logger_assert(
            'Unknown variable type to deserialize')
    #### END DEBUG

    if var_type == wVariables.WaldoUserStructVariable.var_type():
        # we are constructing a user struct: in this case, init_data
        # will be an internal map.  can just deserialize the map into

        #### DEBUG
        if not isinstance(init_data,waldoInternalMap.InternalMap):
            util.logger_assert(
                'Must initialize user struct data with internal map')
        #### END DEBUG

        # FIXME: it is unclear if we just created an internal map for
        # no reason here.  maybe just serialize and deserialize
        # internal values of structs as dicts.
            
        # FIXME: it is gross that reaching into the internal map this
        # way.
        init_data._lock()
        if invalidation_listener.uuid not in init_data._dirty_map:
            new_init_data = init_data.val
        else:
            new_init_data = init_data._dirty_map[invalidation_listener.uuid].val
        init_data._unlock()
        init_data = new_init_data
        
    var_constructor = ReferenceTypeConstructorDict[var_type]
    
    if requires_name_arg_in_constructor(var_type):
        return var_constructor(var_name,host_uuid,peered,init_data)
    
    return var_constructor(host_uuid,peered,init_data)    

    def promote_multithreaded(self,peered):
        '''
        Whenever we assign a single threaded variable, A, into a
        multithreaded variable, B, we need to "promote" the single
        threaded variable to be a multithreaded variable.  This is so
        that reads/writes to A.B from multiple threads do not cause
        read-write conflicts.

        This method returns a multithreaded version of this variable
        containing the same data within it.

        Importantly, it does not genearte a new multithreaded version
        of itself each time.  This is to account for assigning the
        same single threaded variable to more than one multithreaded
        connection.
        '''

        util.logger_assert(
            'In Waldo single threaded container, promote_multithreaded ' +
            'is pure virtual.  Must overload.')