All objects are associated with a unique_name and referenced in the global_object

[damskii9992]

General

In EasyScience, we have a unique global object called global_object, whose uniqueness is ensured by deriving from the singleton Borg class. This object has an associated map object based on the Map class, which contains weak references to all objects created in EasyScience. One of the uses of this map, is that any object can be found no matter where it lives and no matter how deeply nested in other objects it is.

Unique_name

Any object from any class inheriting from BasedBase, NewBase or DescriptorBase (i.e. all objects) has a ' unique_name' string property which acts as a runtime id. This unique_name is by default the class name of the object, subscript a number, such as 'Parameter_1'. The number corresponds to the number of this type of objects that have been created historically at runtime. The iterator for this number is handled by the global_objects _get_name_iterator method.

The user can also set a personal unique_name at object creation or afterwards through the objects setter method. The unique_name can not be set to a unique_name which already exists, which is ensured by the global_object's map, in the add_vertex method, which is the method responsible for adding the reference to the map, this method raises an error if the users unique_name already exists in the map.

The object map

The unique_name of objects can be used to get the object, no matter where it lives, using the map object of the global_object:

from easyscience import global_object
object = global_object.map.get_item_by_key('best_unique_name')

for this reason, it is advantageous for users to use memorable unique_names for their most important properties.

When changing a objects unique_name, the old unique_name still exists in the map of the global_object and still references the same object. The new unique_name is simply added to the weakref dictionary of the map as en extra reference.

Runtime only ids

unique_names are not saved when objects are serialized by the to_dict method, unless they have been explicitly set by the user. This is due to potential unique_name clashes when de-serializing objects with already claimed unique_names (like Parameter_0 after many Parameters have already been created, thus claiming this unique_name). As such, unique_names are only runtime ids. These runtime ids are replaced with serializer_ids for IO upon serialization (see #167).

Reusability and garbage collection

To reuse unique_names, which is heavily discouraged due to the risk of existing references getting the wrong object, the map must first be cleared of the existing entry. This happens naturally due to the weak references when the previous object is deleted and garbage collection is run. As a reminder, garbage collection is normally run automatically, but can be run manually through:

import gc
gc.collect()

If the previous object can not be deleted or garbage collection can not be run, the maps entry can also be cleared by using the prune method:

from easyscience import global_object
global_object.map.prune('best_unique_name')

Yet this is dangerous and is thus also heavily discouraged.

Link to the ADR suggestions:
#16
#164