From b44353777ad7ce459798518ccd99279edb9ac293 Mon Sep 17 00:00:00 2001 From: reiniero Date: Mon, 28 Jan 2013 15:49:05 +0000 Subject: [PATCH] * fcl-db: cosmetic: bufdataset comments: typos, grammar, uniform indentation git-svn-id: trunk@23530 - --- packages/fcl-db/src/base/bufdataset.pas | 182 ++++++++++++------------ 1 file changed, 89 insertions(+), 93 deletions(-) diff --git a/packages/fcl-db/src/base/bufdataset.pas b/packages/fcl-db/src/base/bufdataset.pas index 9737e4b995..2e177d9768 100644 --- a/packages/fcl-db/src/base/bufdataset.pas +++ b/packages/fcl-db/src/base/bufdataset.pas @@ -1,6 +1,6 @@ { This file is part of the Free Pascal run time library. - Copyright (c) 1999-2006 by Joost van der Sluis, member of the + Copyright (c) 1999-2013 by Joost van der Sluis and other members of the Free Pascal development team BufDataset implementation @@ -70,19 +70,19 @@ type TRecUpdateBuffer = record UpdateKind : TUpdateKind; { BookMarkData: - - Is -1 if the update has canceled out. For example: a appended record has been deleted again - - If UpdateKind is ukInsert it contains a bookmark to the new created record - - If UpdateKind is ukModify it contains a bookmark to the record with the new data - - If UpdateKind is ukDelete it contains a bookmark to the deleted record (ie: the record is still there) + - Is -1 if the update has canceled out. For example: an appended record has been deleted again + - If UpdateKind is ukInsert, it contains a bookmark to the newly created record + - If UpdateKind is ukModify, it contains a bookmark to the record with the new data + - If UpdateKind is ukDelete, it contains a bookmark to the deleted record (ie: the record is still there) } BookmarkData : TBufBookmark; { NextBookMarkData: - - If UpdateKind is ukDelete it contains a bookmark to the record just after the deleted record + - If UpdateKind is ukDelete, it contains a bookmark to the record just after the deleted record } NextBookmarkData : TBufBookmark; { OldValuesBuffer: - - If UpdateKind is ukModify it contains a record-buffer which contains the old data - - If UpdateKind is ukDelete it contains a record-buffer with the data of the deleted record + - If UpdateKind is ukModify, it contains a record buffer which contains the old data + - If UpdateKind is ukDelete, it contains a record buffer with the data of the deleted record } OldValuesBuffer : TRecordBuffer; end; @@ -90,7 +90,7 @@ type PBufBlobField = ^TBufBlobField; TBufBlobField = record - ConnBlobBuffer : array[0..11] of byte; // It's here where the db-specific data is stored + ConnBlobBuffer : array[0..11] of byte; // DB specific data is stored here BlobBuffer : PBlobBuffer; end; @@ -159,7 +159,7 @@ type // Normally only used in GetNextPacket procedure AddRecord; virtual; abstract; // Inserts a record before the current record, or if the record is sorted, - // insert it to the proper position + // inserts it in the proper position procedure InsertRecordBeforeCurrentRecord(Const ARecord : TRecordBuffer); virtual; abstract; procedure EndUpdate; virtual; abstract; @@ -352,7 +352,7 @@ type public constructor create(AStream : TStream); virtual; // Load a dataset from stream: - // Load the field-definitions from a stream. + // Load the field definitions from a stream. procedure LoadFieldDefs(AFieldDefs : TFieldDefs; var AnAutoIncValue : integer); virtual; abstract; // Is called before the records are loaded procedure InitLoadRecords; virtual; abstract; @@ -360,15 +360,15 @@ type function GetRecordRowState(out AUpdOrder : Integer) : TRowState; virtual; abstract; // Returns if there is at least one more record available in the stream function GetCurrentRecord : boolean; virtual; abstract; - // Store a record from stream in the current record-buffer + // Store a record from stream in the current record buffer procedure RestoreRecord(ADataset : TCustomBufDataset); virtual; abstract; // Move the stream to the next record procedure GotoNextRecord; virtual; abstract; // Store a dataset to stream: - // Save the field-definitions to a stream. + // Save the field definitions to a stream. procedure StoreFieldDefs(AFieldDefs : TFieldDefs; AnAutoIncValue : integer); virtual; abstract; - // Save a record from the current record-buffer to the stream + // Save a record from the current record buffer to the stream procedure StoreRecord(ADataset : TCustomBufDataset; ARowState : TRowState; AUpdOrder : integer = 0); virtual; abstract; // Is called after all records are stored procedure FinalizeStoreRecords; virtual; abstract; @@ -805,7 +805,7 @@ begin end; { -// Code to dump raw dataset data, including indexes information, usefull for debugging +// Code to dump raw dataset data, including indexes information, useful for debugging procedure DumpRawMem(const Data: pointer; ALength: PtrInt); var b: integer; @@ -911,8 +911,8 @@ var PCurRecLinkItem : PBufRecLinkItem; end; begin - // Build the DBCompareStructure - // One AS is enough, and makes debugging easier. + // Build the DBCompareStructure + // One AS is enough, and makes debugging easier. DblLinkIndex:=(AIndex as TDoubleLinkedBufIndex); Index0:=(FIndexes[0] as TDoubleLinkedBufIndex); with DblLinkIndex do @@ -947,7 +947,7 @@ begin end; end; -// This simply copies the index... + // This simply copies the index... PCurRecLinkItem:=Index0.FFirstRecBuf; PCurRecLinkItem[DblLinkIndex.IndNr].next := PCurRecLinkItem[0].next; PCurRecLinkItem[DblLinkIndex.IndNr].prior := PCurRecLinkItem[0].prior; @@ -966,46 +966,43 @@ begin // Empty dataset Exit; -// Set FirstRecBuf and FCurrentRecBuf + // Set FirstRecBuf and FCurrentRecBuf DblLinkIndex.FFirstRecBuf:=Index0.FFirstRecBuf; DblLinkIndex.FCurrentRecBuf:=DblLinkIndex.FFirstRecBuf; -// Link in the FLastRecBuf that belongs to this index + // Link in the FLastRecBuf that belongs to this index PCurRecLinkItem[DblLinkIndex.IndNr].next:=DblLinkIndex.FLastRecBuf; DblLinkIndex.FLastRecBuf[DblLinkIndex.IndNr].prior:=PCurRecLinkItem; -// Mergesort. Used the algorithm as described here by Simon Tatham -// http://www.chiark.greenend.org.uk/~sgtatham/algorithms/listsort.html -// The comments in the code are from this website. + // Mergesort. Used the algorithm as described here by Simon Tatham + // http://www.chiark.greenend.org.uk/~sgtatham/algorithms/listsort.html + // The comments in the code are from this website. -// In each pass, we are merging lists of size K into lists of size 2K. -// (Initially K equals 1.) + // In each pass, we are merging lists of size K into lists of size 2K. + // (Initially K equals 1.) k:=1; repeat -// So we start by pointing a temporary pointer p at the head of the list, -// and also preparing an empty list L which we will add elements to the end -// of as we finish dealing with them. - + // So we start by pointing a temporary pointer p at the head of the list, + // and also preparing an empty list L which we will add elements to the end + // of as we finish dealing with them. p := DblLinkIndex.FFirstRecBuf; DblLinkIndex.FFirstRecBuf := nil; q := p; MergeAmount := 0; -// Then: -// * If p is null, terminate this pass. + // Then: + // * If p is null, terminate this pass. while p <> DblLinkIndex.FLastRecBuf do begin -// * Otherwise, there is at least one element in the next pair of length-K -// lists, so increment the number of merges performed in this pass. - + // * Otherwise, there is at least one element in the next pair of length-K + // lists, so increment the number of merges performed in this pass. inc(MergeAmount); -// * Point another temporary pointer, q, at the same place as p. Step q along -// the list by K places, or until the end of the list, whichever comes -// first. Let psize be the number of elements you managed to step q past. - + // * Point another temporary pointer, q, at the same place as p. Step q along + // the list by K places, or until the end of the list, whichever comes + // first. Let psize be the number of elements you managed to step q past. i:=0; while (iDblLinkIndex.FLastRecBuf) do begin @@ -1014,23 +1011,21 @@ begin end; psize :=i; -// * Let qsize equal K. Now we need to merge a list starting at p, of length -// psize, with a list starting at q of length at most qsize. - + // * Let qsize equal K. Now we need to merge a list starting at p, of length + // psize, with a list starting at q of length at most qsize. qsize:=k; -// * So, as long as either the p-list is non-empty (psize > 0) or the q-list -// is non-empty (qsize > 0 and q points to something non-null): - + // * So, as long as either the p-list is non-empty (psize > 0) or the q-list + // is non-empty (qsize > 0 and q points to something non-null): while (psize>0) or ((qsize>0) and (q <> DblLinkIndex.FLastRecBuf)) do begin -// o Choose which list to take the next element from. If either list -// is empty, we must choose from the other one. (By assumption, at -// least one is non-empty at this point.) If both lists are -// non-empty, compare the first element of each and choose the lower -// one. If the first elements compare equal, choose from the p-list. -// (This ensures that any two elements which compare equal are never -// swapped, so stability is guaranteed.) + // * Choose which list to take the next element from. If either list + // is empty, we must choose from the other one. (By assumption, at + // least one is non-empty at this point.) If both lists are + // non-empty, compare the first element of each and choose the lower + // one. If the first elements compare equal, choose from the p-list. + // (This ensures that any two elements which compare equal are never + // swapped, so stability is guaranteed.) if (psize=0) then PlaceQRec := true else if (qsize=0) or (q = DblLinkIndex.FLastRecBuf) then @@ -1040,23 +1035,24 @@ begin else PlaceQRec := True; -// o Remove that element, e, from the start of its list, by advancing -// p or q to the next element along, and decrementing psize or qsize. -// o Add e to the end of the list L we are building up. + // * Remove that element, e, from the start of its list, by advancing + // p or q to the next element along, and decrementing psize or qsize. + // * Add e to the end of the list L we are building up. if PlaceQRec then PlaceNewRec(q,qsize) else PlaceNewRec(p,psize); end; -// * Now we have advanced p until it is where q started out, and we have -// advanced q until it is pointing at the next pair of length-K lists to -// merge. So set p to the value of q, and go back to the start of this loop. + + // * Now we have advanced p until it is where q started out, and we have + // advanced q until it is pointing at the next pair of length-K lists to + // merge. So set p to the value of q, and go back to the start of this loop. p:=q; end; -// As soon as a pass like this is performed and only needs to do one merge, the -// algorithm terminates, and the output list L is sorted. Otherwise, double the -// value of K, and go back to the beginning. + // As soon as a pass like this is performed and only needs to do one merge, the + // algorithm terminates, and the output list L is sorted. Otherwise, double the + // value of K, and go back to the beginning. l[DblLinkIndex.IndNr].next:=DblLinkIndex.FLastRecBuf; @@ -1101,8 +1097,8 @@ end; function TCustomBufDataset.AllocRecordBuffer: TRecordBuffer; begin result := AllocMem(FRecordsize + BookmarkSize + CalcfieldsSize); -// The records are initialised, or else the fields of an empty, just-opened dataset -// are not null + // The records are initialised, or else the fields of an empty, just-opened dataset + // are not null InitRecord(result); end; @@ -1138,7 +1134,7 @@ begin // is not (correctly) created. // commented for now. If there are constant expressions in the select - // statement they are ftunknown, and not created. + // statement they are ftUnknown, and not created. // See mantis #22030 // if Fields.Count ukModify then begin FUpdateBuffer[FCurrentUpdateBuffer].OldValuesBuffer := nil; //this 'disables' the updatebuffer - // Do NOT release record buffer (pointed by RemRecBookmrk.BookmarkData) here - // - When record is inserted and deleted(and memory released) and again inserted then same memory block can be returned - // which leads to confusion, because we get same BookmarkData for distinct records - // - In CancelUpdates when records are restored it is expected, that deleted records still exists in memory - // There also could be record(s) in update-buffer, linked to this record. + // Do NOT release record buffer (pointed to by RemRecBookmrk.BookmarkData) here + // - When record is inserted and deleted (and memory released) and again inserted then the same memory block can be returned + // which leads to confusion, because we get the same BookmarkData for distinct records + // - In CancelUpdates when records are restored, it is expected that deleted records still exist in memory + // There also could be record(s) in the update buffer that is linked to this record. end; end; FCurrentIndex.StoreCurrentRecIntoBookmark(@FUpdateBuffer[FCurrentUpdateBuffer].NextBookmarkData); @@ -2022,7 +2018,7 @@ var StoreRecBM : TBufBookmark; end else if (UpdateKind = ukInsert) then begin - // Process all upd-buffers linked to this record before this record is removed + // Process all update buffers linked to this record before this record is removed StoreUpdBuf:=FCurrentUpdateBuffer; Bm := BookmarkData; BookmarkData.BookmarkData:=nil; // Avoid infinite recursion... @@ -2078,7 +2074,7 @@ begin FOnUpdateError := AValue; end; -procedure TCustomBufDataset.ApplyUpdates; // For backwards-compatibility +procedure TCustomBufDataset.ApplyUpdates; // For backward compatibility begin ApplyUpdates(0); @@ -2246,7 +2242,7 @@ begin FIndexes[i].GotoBookmark(ABookmark); FIndexes[i].InsertRecordBeforeCurrentRecord(ABuff); - // new inserted record becomes current record + // newly inserted record becomes current record FIndexes[i].ScrollBackward; end; @@ -2629,7 +2625,7 @@ procedure TCustomBufDataset.GetDatasetPacket(AWriter: TDataPacketReader); ARowState := [rsvInserted]; FFilterBuffer:=AUpdBuffer.OldValuesBuffer; - // If the record is inserted or inserted and afterwards deleted then OldValuesBuffer is nil + // OldValuesBuffer is nil if the record is either inserted or inserted and then deleted if assigned(FFilterBuffer) then FDatasetReader.StoreRecord(Self,AThisRowState,FCurrentUpdateBuffer); end; @@ -2666,7 +2662,7 @@ var ScrollResult : TGetResult; begin FDatasetReader := AWriter; try - //CheckActive; + // CheckActive; ABookMark:=@ATBookmark; FDatasetReader.StoreFieldDefs(FieldDefs,FAutoIncValue); @@ -2690,7 +2686,7 @@ begin ScrollResult := FCurrentIndex.ScrollForward; end; end; - // There could be a update-buffer linked to the last (spare) record + // There could be an update buffer linked to the last (spare) record FCurrentIndex.StoreSpareRecIntoBookmark(ABookmark); HandleUpdateBuffersFromRecord(True,ABookmark^,RowState); @@ -3043,7 +3039,7 @@ begin begin FParser := TBufDatasetParser.Create(Self); end; - // have a parser now? + // is there a parser now? if FParser <> nil then begin // set options @@ -3120,7 +3116,7 @@ begin SearchFields.Free; end; - // Set The filter-buffer + // Set the filter buffer StoreDSState:=SetTempState(dsFilter); FFilterBuffer:=FCurrentIndex.SpareBuffer; SetFieldValues(keyfields,KeyValues); @@ -3136,7 +3132,7 @@ begin if Filtered then begin FFilterBuffer:=pointer(CurrLinkItem)+(sizeof(TBufRecLinkItem)*MaxIndexesCount); - // The dataset-state is still dsFilter at this point, so we don't have to set it. + // The dataset state is still dsFilter at this point, so we don't have to set it. DoFilterRecord(FiltAcceptable); if FiltAcceptable then begin @@ -3178,7 +3174,7 @@ begin try if Locate(KeyFields,KeyValues,[]) then begin -// CalculateFields(ActiveBuffer); // not needed, done by Locate more than once + // CalculateFields(ActiveBuffer); // not needed, done by Locate more than once result:=FieldValues[ResultFields]; end; GotoBookmark(bm); @@ -3280,8 +3276,8 @@ end; procedure TArrayBufIndex.SetToFirstRecord; begin -// if FCurrentRecBuf = FLastRecBuf then the dataset is just opened and empty -// in which case InternalFirst should do nothing (bug 7211) + // if FCurrentRecBuf = FLastRecBuf then the dataset is just opened and empty + // in which case InternalFirst should do nothing (bug 7211) if FCurrentRecInd <> FLastRecInd then FCurrentRecInd := -1; end; @@ -3337,7 +3333,7 @@ end; procedure TArrayBufIndex.InitialiseIndex; begin -// FRecordArray:=nil; + // FRecordArray:=nil; setlength(FRecordArray,FInitialBuffers); FCurrentRecInd:=-1; FLastRecInd:=-1; @@ -3346,7 +3342,7 @@ end; procedure TArrayBufIndex.InitialiseSpareRecord(const ASpareRecord: TRecordBuffer); begin FLastRecInd := 0; - // FCurrentRecInd := 0; + // FCurrentRecInd := 0; FRecordArray[0] := ASpareRecord; end; @@ -3381,7 +3377,7 @@ end; procedure TArrayBufIndex.BeginUpdate; begin -// inherited BeginUpdate; + // inherited BeginUpdate; end; procedure TArrayBufIndex.AddRecord; @@ -3396,7 +3392,7 @@ end; procedure TArrayBufIndex.EndUpdate; begin -// inherited EndUpdate; + // inherited EndUpdate; end; { TDataPacketReader } @@ -3491,7 +3487,7 @@ end; procedure TFpcBinaryDatapacketReader.FinalizeStoreRecords; begin -// Do nothing + // Do nothing end; function TFpcBinaryDatapacketReader.GetCurrentRecord: boolean; @@ -3502,12 +3498,12 @@ end; procedure TFpcBinaryDatapacketReader.GotoNextRecord; begin -// Do Nothing + // Do Nothing end; procedure TFpcBinaryDatapacketReader.InitLoadRecords; begin -// SetLength(AChangeLog,0); + // SetLength(AChangeLog,0); end; procedure TFpcBinaryDatapacketReader.RestoreRecord(ADataset: TCustomBufDataset); @@ -3550,7 +3546,7 @@ begin // This code could be moved to the TBufIndex but that would make things // more complicated and probably slower. So use a 'fake' bookmark of // size TBufBookmark. - // When there are other TBufIndexes which also need special bookmark-code + // When there are other TBufIndexes which also need special bookmark code // this can be adapted. Result:=sizeof(TBufBookmark); end; @@ -3562,7 +3558,7 @@ end; function TUniDirectionalBufIndex.GetCurrentRecord: TRecordBuffer; begin -// Result:=inherited GetCurrentRecord; + // Result:=inherited GetCurrentRecord; end; function TUniDirectionalBufIndex.GetIsInitialized: boolean; @@ -3628,7 +3624,7 @@ end; function TUniDirectionalBufIndex.CanScrollForward: Boolean; begin - // should return true if a next record is already fetched + // should return true if next record is already fetched result := false; end;