* fcl-db: cosmetic: bufdataset comments: typos, grammar, uniform indentation

git-svn-id: trunk@23530 -
This commit is contained in:
reiniero 2013-01-28 15:49:05 +00:00
parent bb00325d85
commit b44353777a

View File

@ -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 (i<k) and (q<>DblLinkIndex.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<FieldDefs.Count then
@ -1146,7 +1142,7 @@ begin
// If there is a field with FieldNo=0 then the fields are not found to the
// FieldDefs which is a sign that there is no dataset created. (Calculated and
// lookupfields have FieldNo=-1)
// lookup fields have FieldNo=-1)
for i := 0 to Fields.Count-1 do
if fields[i].FieldNo=0 then
DatabaseError(SErrNoDataset)
@ -1386,7 +1382,7 @@ end;
procedure TDoubleLinkedBufIndex.InitialiseIndex;
begin
// Do nothing
// Do nothing
end;
function TDoubleLinkedBufIndex.CanScrollForward: Boolean;
@ -1790,7 +1786,7 @@ end;
function TCustomBufDataset.GetRecordUpdateBufferCached(const ABookmark: TBufBookmark;
IncludePrior: boolean): boolean;
begin
// if the current update buffer complies, immediately return true
// if the current update buffer matches, immediately return true
if (FCurrentUpdateBuffer < length(FUpdateBuffer)) and (
FCurrentIndex.CompareBookmarks(@FUpdateBuffer[FCurrentUpdateBuffer].BookmarkData,@ABookmark) or
(IncludePrior and (FUpdateBuffer[FCurrentUpdateBuffer].UpdateKind=ukDelete) and FCurrentIndex.CompareBookmarks(@FUpdateBuffer[FCurrentUpdateBuffer].NextBookmarkData,@ABookmark))) then
@ -1969,11 +1965,11 @@ begin
if FUpdateBuffer[FCurrentUpdateBuffer].UpdateKind <> 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;