Ticket #1020: plandoc.txt

File plandoc.txt, 11.6 KB (added by jessevdam, 5 years ago)

update and added documentation on the change

Line 
1----
2The status as it is on 28 okt 2009. See branch tt_1020 for more details.
3(broken at the moment will be fixed tomorrow I hope,small svn problem)
4
5This will give some extra detail on the plan and will give a view on the current status.
6Any comments are welcome.
7
8The functionality in object.pmc will move to default.pmc. With this action everything will
9become an object. (default.pmc will get renamed back to object.pmc).
10The C pmc can keep using there C structures as they did before. But with a few restrictions.
11All field must be one off the following types.
12(AT_POINTER)     void* (to some C structure/data)
13(AT_PMC_POINTER) pmc* (pointer to a pmc)
14(AT_STRING)      STRING* (pointer to a String)
15(AT_INTEGER)     INTVAL (integer)
16(AT_FLOAT)       FLOATVAL (float value)
17The usage of attributes as an array is no longer allowed. (ATTR INTVAL vals[4] = no long allowed)
18The following thing has been done to make the set/get attributes function also work for the attributes accessed via the
19C structure. The attributes array (DPOINTER **) array has been mapped over this C structure (union).
20The "get_attr_str","get_attr_keyed","set_attr_str","set_attr_keyed" use this array to access these attributes.
21This array has element size off 32 bits. Using a 32 bits I386 machine as base. Pointers and Integers are 32 bits.
22But Float (=double) are 64 bit. So they take 2 entries of this attributes array. To keep track of this sizes the
23following attributes in the class.pmc are used.
24-attrib_index2type
25Tells which type of value can be found at each index. If it is index halfway of double value then it is a invalid value.
26That is a small gap.
27-attrib_markwalk
28Array with the indexes to the items which has to marked.
29-attrib_indexes
30Array with the indexes to all items.
31
32For exmaple when using the following attributes.
33attr Context * ctx;
34attr PMC * some_pmc;
35attr INTVAL myval;
36attr FLOAT myfloat;
37attr STRING * mystring;
38Then these attributes will look like:
39attrib_index2type = [AT_POINTER,AT_PMC_POINTER,AT_INTEGER,AT_FLOAT,invalid,AT_STRING]
40attrib_mark_walk = [1,5]
41attrib_indexes = [0,1,2,3,5]
42
43The sizeof(void*), INTVAL and FLOAT are determined by a config script and placed in the
44core_pmcs.c->attrib_type2index_size function. Note that I placed some restriction on the this, see config/gen/core_pmcs.pm.
45See code oo.c "get_attrib_type_from_desc", "cache_class_attribs","build_attrib_index" for extra detail.
46
47All core pmcs get a full describing pmcclass object as a
48pir created class does have, instead of the vtable struct information. See the code in lib/Parrot/Pmc2c.
49
50A extra load pass had been added. These are the attributes of the class.pmc which the load pass
51at which they are loaded.
52 
530    ATTR INTVAL id;             /* The type number of the PMC. [deprecated: See RT #48024] */
540    ATTR STRING *name;          /* The name of the class. */
550    ATTR STRING *fullname;      /* The name of the class. */
562    ATTR PMC *_namespace;       /* The namespace it's linked to, if any. */
57-    ATTR INTVAL instantiated;   /* Any instantiations since last modification? */
581    ATTR PMC *parents;          /* Immediate parent classes. */
592    ATTR PMC *all_parents;      /* Cached list of ourself and all parents, in MRO order. */
602    ATTR PMC *roles;            /* An array of roles. */
612    ATTR PMC *methods;          /* Hash of method names to methods in this class. */
62-    ATTR PMC *vtable_overrides; /* Hash of Parrot v-table methods we override. */
632    ATTR PMC *attrib_metadata;  /* Hash of attributes in this class to hashes of metadata. */
642    ATTR PMC *attrib_index;     /* Lookup table for attributes in this and parents. */
652    ATTR PMC *attrib_cache;     /* Cache of visible attrib names to indexes. */
66-    ATTR PMC *resolve_method;   /* List of method names the class provides to resolve
67                                 * conflicts with methods from roles. */
68-    ATTR PMC *parent_overrides;
690    ATTR INTVAL attrib_count;   /* Number of attributes in attrib object store of the
70                                   object of this type
71                                   Field could be saved by combining it with instantiated */
72
730    ATTR VTABLE *vtable;        /* The vtable function of this class */
740    ATTR VTABLE *ro_vtable;
75
76The roles field uses a temporary function which create a "empty" role.pmc object.
77In the future someone could implement something, which makes it possible to define a role as
78in the same way a pmc is now.
79
80The namespace is created when the class is loaded.
81
82The attrib_metadata is created, the "type" field is now used to describe the type of the
83attributes. Which can be one of the following items "String","Void*","Integer","Float","PMC".
84
85Since all pmc will become an object, there is will be a field pointing to the pmcclass.
86The pmcclass object will contain the full describtion of the pmc/object.
87The pointer to the vtable struct will get removed since all information is stored in the
88pmcclass object. The interp->vtables[] array get replaced with the interp->classes[] array.
89This last step has already been completed.
90
91The vtable fields and initianlization of "base_type","attribute_defs","whoami","provides_str",
92"isa_hash","_namespace",*"mro",*"attr_size",*"pmc_class" will become reduntant.
93* are already removed
94
95So after completion of this change the vtable struct will only hold pointers to the vtable functions.
96The pmc will have no more pointer to the vtable struct, all needed information is stored in the pmcclass object.
97
98Because a pmcclass object, which describes a class has got a more central role and the information is used
99for the removal of an object, are they stored in a seperate gc small object arena. Class object will
100run the mark function and mark other object, but will for now will not get automatically removed.
101This means when a class is defined it will stay in the memory until shutdown.
102These can ofcourse be fixed in the future, but this "problem" has also been
103for a while in the jvm, so I think it will not be a big problem. Once the gc system get finalized, the pmcclass object
104which describes the class itself will get removed as the last one. See code src/gc/*.c.
105
106The "get_attr_str","get_attr_keyed","set_attr_str","set_attr_keyed" are the function which are
107used by pir code to access the attributes. These function do lookup via a hash, as it was before
108this change.
109When a INTVAL,FLOAT or STRING is stored it will get unbox and stored.
110When rertrieving them they will get boxed again.
111Attributes of type void* can not be accessed, they are "private".
112Note that the code in the core pmc's just keep using the c structure.
113The difference is there will be no more proxy object so setting an attribute in an extended core pmc object
114will actually set the attribute values. This will make the following test succeed.
115
116.sub int_subclass_test
117    .local pmc myint
118    $P5 = box 10
119    myint = subclass 'Integer', [ 'MyInt2' ]   
120    $P1 = new myint
121    setattribute $P1,'iv',$P5
122    $I1 = set $P1
123    is ($I1, 10, 'setattribute integer value')
124    getattribute $P3,$P1,'iv'
125    $I1 = set $P3
126    is ($I1, 10, 'getattribute integer value')
127    $S0 = $P1
128    is ($S0, "10", 'integer to string')
129.end
130
131The following work has already been doen.
132
133-Replace interp->vtables[] by interp->classes[]
134-Added needed extra fields in class.pmc
135-Make bootstrap/load code in lib/Parrot/pmc2c/ for loading the full class information of the core pmcs
136-Addapt the class registration code, (some changes still be done)
137-Creation of the new attribute indexing system 
138-Store pmcclass object into seperate gc pool.
139-Because of the restriction of the c structure some attributes of some pmc had to wrapped in a struct
140or pointer. This work has been completed.
141-All pmc has become an object, this resulted in the removal of the auto_attr fields. All changes
142needed for that has been completed. See for example the context.pmc. The pointer to the context has
143become an attribute instead of being directly stored in the pmc->data field.
144-Move the functionality of the object.pmc to default.pmc partly done
145--The mark,clone,thaw,freeze,visit and finishthaw has still to be done.
146
147Work to do and thing not yet build
148
149This is the work that has still to be done, to complete this change.
150
151-mark,clone,freeze,thaw,visit,finishthaw functions
152Pir code can extends a core pmcs class and extra attributes to it. These extra attributes also needs to get handled.
153This applies to the following function.
154Marking -> mark
155Cloning -> clone
156Freeze/thaw -> freeze,thaw,visit,finishthaw
157These function are currently implemented in the pmc files, but they should the "'object.pmc'" also to handle
158the optionally added extra attributes. But since all attributes of type of PMC,STRING,INVTAL and FLOAT can be handled
159by this "'object.pmc'" basic code, they do not need to be done by the specific pmcs code itself, except there is
160something special to them. Attributes of type Void* has to be handled by the pmcs class itself.
161The pmcÂŽs has to changed in such a way the optionally added extra attributes get also handled.
162
163-freeze/thaw system
164The freeze/thaw system, make use of the imformation stored in the pmcclass objects. These need special handling in
165the freeze/thaw system. First needs the classes get thawed before the object, because the information in the classpmc
166object is needed for the thawing.
167The current completed changed code stores the class information in the object freeze/thaw data,
168but that cost extra space, which is not needed.
169
170-get/set attr overrides
171"get_attr_keyed","set_attr_keyed" are free and not implemented by any core pmc
172"get_attr_str","set_attr_str" implemented in callsignature, exception,task,eventhandler
173
174-kill pmcproxy.pmc
175--make sure the init and init_pmc vtable function still get called in rigth order
176--step by step removal of pmcproxy functions
177--switch over to class.pmc initialize function
178--kill pmcproxy.pmc file
179
180-kill old object.pmc file
181-rename default.pmc to object.pmc
182
183-clean up
184--step by step of vtable struct fields, which are no longer used
185--remove vtable field from pmc struct
186--remove old no longer used code
187--fixup broken tests
188---threads.t and interpreter cloning may need some extra time
189--fixup coding standaard
190
191-fixup the documentation
192
193
194-
195
196Discussion on Performance
197Take in mind that the above described int_subclass_test test is not working at the moment and fixing that is going to cost
198some performance.
199
200+no more pmc proxy object
201 = gaining speed (no more looking up needed)
202 = use less memory in case of extending core pmc (lots less memory)
203-vtable function acces pmc->class->vtable->function instead of pmc->vtable->function
204-some non allowed attribute types are wrapped up
205-auto_attr is gone, see for example context.pmc. If there are no attributes then no mem is allocated.
206-call to vtable get/set attribute functions must do extra index 2 type action
207-call to vtable get/set attribute functions do unbox and boxing, but only in case of accessing
208a core pmc attribute, so this one does not count :)
209+allowing later on patch for vtable override function, which does the following thing:
210When there is a vtable override the vtable function pointer will get replaced by pointer
211pointing to a lookup function which search in the vtable overrides code. Instead of having
212to do a lookup search all the time. Gaining lots of speed.
213+no more special code inplace for handling core pmcs
214-the class.pmc needs some more initialization.
215+- the mark,clone,freeze and thaw function will change
216- mark function must only walk the pmc* and String* attributes
217- clone function must take care of the different attribute types
218
219+the already nice parrot code will get better smoothed out, gaining dev time (important one for me :))
220
221
222I hope have mentioned every thing and did not forget stuff.
223
224--------