FPC Cleanroom: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		In 2007 it was found that some functions could need a new implementation because they were too similar to the implementation from Delphi. FPC 2.2.2 will be the first release after the cleanroom implementation of those routines.
2	2
3	3		The core FPC developers already know the old implementation, so impartial contributiors not familiar with the old code or the Delphi code need to be found. The functions alse need to be tested and specifications for them written.
4	4
5	5		## Volunteers to implement the functions
6	6
7	7		- Vincent
8	8		- Almindor
9	9		-
10	10		-
11	11
12	12		## Volunteers to write specs and test apps
13	13
14	14		- [[Sekelsenmat]]
15	15		- Joost
16	16
17	17		## Downloading the cleanroom branch
18	18
19	19		One can download it using subversion with:
20	20
21		-	~~`svn co `[`http://svn.freepascal.org/svn/fpc/branches/cleanroom`](http://svn.freepascal.org/svn/fpc/branches/cleanroom)` cleanroom`~~
	21	+	```text
	22	+	svn co http://svn.freepascal.org/svn/fpc/branches/cleanroom cleanroom
	23	+	```
22	24
23	25		Or use viewvc to view it: <http://svn.freepascal.org/cgi-bin/viewvc.cgi/branches/cleanroom/>
24	26
25	27		## Affected functions
26	28
27	29		The affected functions are marked with "tainted" on the branch.
28	30
29	31		### TDataset.CalculateFields
30	32
31	33		location
32	34
33		-	~~`cleanroom/packages/fpc-db/src/base/dataset.inc`~~
	35	+	```text
	36	+	cleanroom/packages/fpc-db/src/base/dataset.inc
	37	+	```
34	38
35	39		declaration
36	40
37		-	~~`(private) Procedure TDataset.CalculateFields(Buffer: PChar);`~~
	41	+	``` pascal
	42	+	(private) Procedure TDataset.CalculateFields(Buffer: PChar);
	43	+	```
38	44
39	45		Implementor: Almindor (untested)
40	46
41	47		Specifications
42	48
43	49		Basicly this procedure sets the CalcBuffer, clears it and calculates the lookupvalues for all lookup fields and then calls DoOnCalcFields.
44	50
45	51		So first it assigns the supplied Buffer to FCalcBuffer. Then if the state of the dataset is not dsInternalCalc and IsUniDirectional is False, ClearCalcFields is called to clear the CalcBuffer and for each field in the Fields collection of which the FieldKind is fkLookup, CalcLookupValue is called.
46	52
47	53		Finally DoOnCalcFields is called.
48	54
49	55		### TDataset.DataEvent
50	56
51	57		location
52	58
53		-	~~`cleanroom/packages/fpc-db/src/base/dataset.inc`~~
	59	+	```text
	60	+	cleanroom/packages/fpc-db/src/base/dataset.inc
	61	+	```
54	62
55	63		declaration
56	64
57		-	~~`(private) Procedure TDataset.DataEvent(Event: TDataEvent; Info: Ptrint);`~~
	65	+	``` pascal
	66	+	(private) Procedure TDataset.DataEvent(Event: TDataEvent; Info: Ptrint);
	67	+	```
58	68
59	69		Impementor: Vincent
60	70
61	71		#### Specifications
62	72
63	73		Handles an event
64	74
65	75		When the event is equal to deFieldChange then the provided 'Info' parameter is a TField. If it's fieldkind is fkData or fkInternalCalc then SetModified is called to set Modified to 'true'.
66	76
67	77		If the event is deFieldChange and the state of the dataset is not dssetkey then there are first two checks: if FInternalCalcFields and info's FieldKind is equal to fkData, then RefreshInternalCalcfields is called with ActiveBuffer as parameter. Second check is that if the first check is not true but the info's fieldkind is equal to fkData, FAutoCalcFields is true and FCalcFieldsSize is not equal to 0, then CalculateFields is called for the ActiveBuffer. After those two checks, Info.Change is always called.
68	78
69	79		If the event is equal to deDatasetChange or deDatasetScroll and TDataset.State is not dsInsert then UpdateCursorPos is called.
70	80
71	81		Thereafter, if ControlsDisabled is false, the event is distributed to all datasources linked to this dataset by calling the datasource's ProcessEvent with 'Event' and 'Info' as parameters.
72	82
73	83		### TDataset.EnableControls
74	84
75	85		location
76	86
77		-	~~`cleanroom/packages/fpc-db/src/base/dataset.inc`~~
	87	+	```text
	88	+	cleanroom/packages/fpc-db/src/base/dataset.inc
	89	+	```
78	90
79	91		declaration
80	92
81		-	~~`(public) Procedure TDataset.EnableControls;`~~
	93	+	``` pascal
	94	+	(public) Procedure TDataset.EnableControls;
	95	+	```
82	96
83	97		Implementor: Almindor (untested)
84	98
85	99		Specifications
86	100
87	101		Reactivates the displaying of data on screen after a call to DisableControls.
88	102
89	103		EnableControls should decrement the disabled count on the dataset, up to a minimum of zero. If it's zero, it will tell the controls using the dataset they can show their values on screen.
90	104
91	105		In detail: If FDisableControlsCount is larger then zero then it's value is decremented by 1. If thereafter FDisabledControlsCount is equal to zero then there is a check if the state of the dataset is changed since the call to DisableControls. This is done by comparing the current state with FDisableControlsState. If the state is changed, a deUpdateState event is fired, using TDataset.DataEvent. If the current state and the FDisableControlState are both unequal to dsInactive, then an FEnablecontrolsEvent is fired.
92	106
93	107		### TDataLink.CalcFirstRecord
94	108
95	109		location
96	110
97		-	~~`cleanroom/packages/fpc-db/src/base/datasource.inc`~~
	111	+	```text
	112	+	cleanroom/packages/fpc-db/src/base/datasource.inc
	113	+	```
98	114
99	115		declaration
100	116
101		-	~~`(private) Function TDataLink.CalcFirstRecord(Index : Integer) : Integer;`~~
	117	+	``` pascal
	118	+	(private) Function TDataLink.CalcFirstRecord(Index : Integer) : Integer;
	119	+	```
102	120
103	121		Implementor: Almindor (untested)
104	122
105	123		#### Specifications
106	124
107	125		This procedure returns the number of records the buffer should be scrolled if the current cursor moves 'index' places. And it sets FFirstRecord to it's new place, taking the shift of the buffer into account.
108	126
109	127		This function compare DataSource.Dataset.FActiveRecord with FFirstRecord +Index+FBuffercount-1. If the former is larger then the latter, then the result of the function is set to the difference between the two. Else if DataSource.Dataset.FActiveRecord is smaller then FFirstRecord +Index then the result is set to the difference between those two values. (The result is negative) If both evaluations are false, no shift of the buffer is necessary and the result is set to 0.
110	128
111	129		Finally the FFirstRecord is incremented by Index and the Result is added to it.
112	130
113	131		### TField.CalcLookupValue
114	132
115	133		location
116	134
117		-	~~`cleanroom/packages/fpc-db/src/base/fields.inc`~~
	135	+	```text
	136	+	cleanroom/packages/fpc-db/src/base/fields.inc
	137	+	```
118	138
119	139		declaration
120	140
121		-	~~`(private) procedure TField.CalcLookupValue;`~~
	141	+	``` pascal
	142	+	(private) procedure TField.CalcLookupValue;
	143	+	```
122	144
123	145		Implementor: Almindor (untested)
124	146
125	147		Specifications
126	148
127	149		It sets 'value' to to the lookupvalue corresponding to the fieldvalues of the keyfields.
128	150
129	151		If FLookupCache is true, then Value is set to the value of the key in 'LookupList' which corresponds to the 'FieldValues' of 'FKeyFields' of 'FDataset'. Or else if the FLookupDataSet is not nil and this dataset is active then then the value of 'Value' is determined using FLookupDataset.Lookup. The keyfields are the 'FLookupKeyFields', the keyvalues the FieldValues of the FDataset for the FKeyFields again, and the resultfield is the FLookupResultField.
130	152
131	153		### TField.RefreshLookupList
132	154
133	155		location
134	156
135		-	~~`cleanroom/packages/fpc-db/src/base/fields.inc`~~
	157	+	```text
	158	+	cleanroom/packages/fpc-db/src/base/fields.inc
	159	+	```
136	160
137	161		declaration
138	162
139		-	~~`(public) procedure TField.RefreshLookupList;`~~
	163	+	``` pascal
	164	+	(public) procedure TField.RefreshLookupList;
	165	+	```
140	166
141	167		Implementor: Almindor (untested)
142	168
143	169		#### Specifications
144	170
145	171		This procedure does nothing if FLookupDataset is nil or if any of FLookupkeyFields, FLookupResultField or FKeyFields is an empty string.
146	172
147	173		First of all the value of FLookupDataset is stored. The rest of the procedure is executed in an expcetion-block and whatever happens, FLookupDataset.Active is set to the stored value before the procedure ends. (Even in case of an exception)
148	174
149	175		Thereafter FLookupDataset.Active is set to true. Then FFields.CheckFieldNames is called for FLookupKeyFields and FLookupDataset.FieldByName(FLookupResultField) is called to check if that field does exist.
150	176
151	177		Then LookupList.Clear is called and the controls are disabled. (DisableControle). Thereafter an exception-block is started, so that EnableControls is always called after the code in the exception block. In the exception block FLookupList.Add is called for each record in FLookupDataset. The first parameter of FLookupList.Add is FieldValues\[FLookupKeyFields\] and the second is FieldValues\[FLookupResultField\]
152	178
153	179		(As said, here Enablecontrols is called and the value of FLookupDataset.Active is restored.)
154	180
155	181		Related to
156	182
157	183		- TField.LookupCache
158	184		- TField.LookupDataSet
159	185		- TField.LookupKeyFields
160	186		- TField.LookupList
161	187		- TField.LookupResultField
162	188
163	189		## TODO for the RTL
164	190
165	191		- \[Done\] There is a memleak in TReader.ReadPropValue. A FFixups object is created, but never destroyed. Where should it be freed. Possible places: in TReader.EndReference or TReader.Destroy.
166	192		- \[Done\] Fix test for streaming of enumeration with value equal to low(TMyEnum) and no explicit
167	193
168	194		default value, which means a default value of low(TMyEnum). Currently fpc 2.2.0 behaves differently from Delphi, the tests don't reflect this.
169	195
170	196		- \[Done\] There is a memleak in TTESTRESOLVEREFERENCE tests. SetupARef1A is called but the
171	197
172	198		returned object is not freed.
173	199
174	200		- There are no tests for TReader.FindComponentClass
175	201
176	202		## Variant streaming implementation
177	203
178	204		The variant streaming is very important not only for COM/CORBA compatibility, but also for general runtime access to the properties of object using GetPropValue/SetPropValue. Besides the variant is type, widely used in database components, and absence of Variant streaming limits the usage of variant as published properties.
179	205
180	206		### General considerations
181	207
182	208		Variant itself is a structure, holding the type selector for the data and the data itself (in some cases it holds a reference). Some very special cases include variant holding reverence to COM/Corba object, which streaming would be considered later.
183	209
184	210		One of the powerful concept of FPC Object Pascal RTL is the presence of abstract writer and reader, which can be easily subclassed. For our task we have to extend the functionality of basic class TAbstractObjectReader/Writer, to allow in derived classes use the methods - ReadVariant/WriteVariant.
185	211
186	212		Current FPC-implemented Delphi-compatible writer (TWriter) works in such manner -
187	213
188	214		- It enumerates properties, determining property type.
189	215		- Using the property type as selector it branches to specified property storage routine.
190	216		- Using RTTI functions writer gets the property value, determines if the property have to be stored (is not default value and stored-checker method allows storage).
191	217		- Using methods of internal TBinaryObjectWriter object, referred as Driver, Writer stores value in the stream.
192	218
193	219		#### Storing property of type Variant
194	220
195	221		For variant value there should be one additional consideration: Once we got property type and have determined that it is variant - we have to extract from variant the kind of basic pascal type which variant holds.
196	222
197	223		There is routine VarType(arg:Variant), which can help to separate if the variant is Ordinal, Floating-point or String. These three kinds of variants can be handled by corresponding separate routines. Ordinal variants include:
198	224
199	225		- varShortInt,varSmallInt,varInteger,varInt64,varQWord, which can be stored using fDriver.WriteInteger()
200	226		- varBoolean, which can be stored using fDriver.WriteBoolean()
201	227
202	228		Floating-point variants include:
203	229
204	230		- varSingle, which can be stored by fDriver.WriteSingle
205	231		- varDouble,varDate,varCurrency, which can be handled as double and stored using fDriver.WriteFloat
206	232
207	233		String-holding variants: All the flavours of strings. IMO the string should be extracted as widestring and then stored as UTF8 representation.
208	234
209	235		Other variant flavours (varXXXX) should be considered for now as non-implemented.
210	236
211	237		One special case - is a variant holding NULL reference, and variant holding none (empty variant). These are different cases, and special measures should be taken to distinguish such conditions. Empty variant should not be stored. NULL variant is the value, like other.
212	238
213	239		#### Reading property of type Variant
214	240
215	241		Reading of variants consists of the following:
216	242
217	243		- Once we have determined the property is variant, we have to read value type (ReadValue) from stream.
218	244		- Depending of the value type we have to read using fDriver methods the value of specified type, to the variable of compatible basic type without precision loss.
219	245		- We have to initialise variant using RTL assignment magic ( Variant := SomeGenericValue; ), which would implicitly invoke corresponding variant initialiser)
220	246		- Once we got assigned variant, we return it
221	247
222	248		Special consideration is made for vaTrue, vaFalse - stored in stream. Variant should contain boolean value set to true if we got vaTrue and set to false if we got vaFalse.
223	249
224	250		The very special consideration should be done for string Zoo. Read string should be converted to WideString and stored in variant.
225	251
226	252		## Bug reports
227	253
228	254		- [11060](http://bugs.freepascal.org/view.php?id=11060): Reader fails to assign class properties
229	255		- [11059](http://bugs.freepascal.org/view.php?id=11059): TComponent.DefineProperties not called
230	256
231	257		---
232	258		From the Free Pascal wiki, page "FPC Cleanroom", as it stood on 2015-07-22 after a change by FTurtle, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
233	259		Category: Old or unknown pages

Back to history