Generic circular buffer library released

[TurboMagic 92]

Hello,

 

just a small note that I released a generic circular buffer library under open source license (Apache 2.0) here:

https://github.com/MHumm/CircularBuffer

 

Feel free to use it or to contribute to it.

 

Cheers

TubroMagic

[FPiette 383]

Would be nice if you translate all your comments in English.

[dummzeuch 1505]

Maybe one of the first things somebody could contribute, are English translations of the comments then. 😉

[TurboMagic 92]

I can understand the request to do so. I have already written in the project description that this would be a task one could/should do.

As I'm busy enough with my other open source project (DEC - Delphi Encryption Compendium)

I will accept such translations and update the code with them but won't invest the time in those at this time.

 

As user Dummzeuch (a German by the way! ;-) ) stated: maybe somebody could contribute them.

I guess there are enough Delphi developers out there who didn't contribute code etc. yet but only consumed so far what

others contributed. That could be a start to give something back.

 

As we're talking about contributing and my next topic is related to F. Piette:

is there an easy way to write a Delphi source code parser (maybe using Delphi AST which I only know by name)

to parse the source of ICS and generate output in the Wikipedia syntax so that for the still undocumented SSL ICS code

the Wiki sceleton could be generated at least as a starting point to finally get documentation started?

 

While I value the library and its many demos, a written documentation about the individual properties and methods

is also worth quite something!

[TurboMagic 92]

Oh, another remark:

If somebody would "donnate"! English translations for CircularBuffer I would submit the updated version to GetIt!

[TurboMagic 92]

Uwe Raabe is already working on this 😉

But others than MVPs and the usual folks could contribiute as well...

Often such easy things or even parts of those would help the community!

[Angus Robertson 574]

The ICS FAQ pages already have a lot of SSL/TLS documentation for major subjects, and some of the server components have almost up to data documentation for properties and methods.  But proper documentation takes weeks and no-one will pay for it,  so I spend more time writing new components. 

 

http://wiki.overbyte.eu/wiki/index.php/Main_Page

 

I have created a complete help file of all ICS components, properties, methods and events, but it would take weeks to make it useful with actual text on what they do.  Some developers give up at that point and just leave a skeleton help file. 

 

Angus

 

[Wil van Antwerpen 25]

4 minutes ago, TurboMagic said:

Uwe Raabe is already working on this 😉

But others than MVPs and the usual folks could contribiute as well...

Often such easy things or even parts of those would help the community!

Thanks for the update... was also doing this. Will stop then. German is not my native language anyways :)

[TurboMagic 92]

24 minutes ago, Angus Robertson said:

The ICS FAQ pages already have a lot of SSL/TLS documentation for major subjects, and some of the server components have almost up to data documentation for properties and methods.  But proper documentation takes weeks and no-one will pay for it,  so I spend more time writing new components. 

 

http://wiki.overbyte.eu/wiki/index.php/Main_Page

 

I have created a complete help file of all ICS components, properties, methods and events, but it would take weeks to make it useful with actual text on what they do.  Some developers give up at that point and just leave a skeleton help file. 

 

Angus

 

 

Ok, I see the FAQ pages but in the wiki documentation for the various components the SSL ones are usually read = nonexisting links.

My earlier question was what we can do to help generate the Wiki sceleton as automatically as possible.

 

About the help you started to create: is this CHM based and is the "source" available for contribution somewhere?

[Angus Robertson 574]

I brought the ICS TWSocketServer  component page up to date, and the TWSocketServer.IcsHosts properties page, since those two components are the basis of all the servers, and I extended the capability a lot so you don't need TSslContext which is probably the component you want documented.  And I'm slowly adding new components that don't need TSslContext either, already done HTTP, FTP and SMTP, to make SSL easier to use.  

 

I used Document Insight to create a 20MB CHM file, it has various other formats,  But it really needs a large amount of XML added to the source files to be useful, which is many weeks or months of work. The file is on the wiki site but I'm not publishing the URL here since it's not useful in it's present form. 

 

Angus

 

[Anders Melander 1784]

1 hour ago, Angus Robertson said:

I used Document Insight to create a 20MB CHM file, it has various other formats,  But it really needs a large amount of XML added to the source files to be useful

Document Insight can use external XML files. Very useful when you don't want to make the source unreadable with XML DOC comments.

[FredS 138]

1 hour ago, Anders Melander said:

Document Insight can use external XML files. Very useful when you don't want to make the source unreadable with XML DOC comments.

 

Think I tried that before and moving existing documentation failed. Just tried again and same..

It does appear to work when I add new documentation, however there are these caveats:

Quote

Warning: Although separated XML documentation will make source code clean, the price is that neither built-in Help Insight nor Code Insight support this documentation style. In addition, you have to manually modify corresponding documentation file carefully when you changed a signature of an API.

 

[Anders Melander 1784]

5 minutes ago, FredS said:

moving existing documentation failed.

Well that a bug then. Report it and get it fixed.

 

1 minute ago, FredS said:

Although separated XML documentation will make source code clean, the price is that neither built-in Help Insight nor Code Insight support this documentation style. In addition, you have to manually modify corresponding documentation file carefully when you changed a signature of an API.

Since we're (you're) talking about external documentation the first part doesn't really matter but it's true that the link to the external help is broken when the signature changes. That rarely happens though.

[FredS 138]

2 hours ago, Anders Melander said:

Report it

 

Believe I did that years ago.. not sure if via email or Google..

[Fr0sT.Brutal 900]

17 hours ago, TurboMagic said:

is there an easy way to write a Delphi source code parser (maybe using Delphi AST which I only know by name)

to parse the source of ICS and generate output in the Wikipedia syntax so that for the still undocumented SSL ICS code

the Wiki sceleton could be generated at least as a starting point to finally get documentation started?

You can try PasDoc

[Stefan Glienke 2005]

Spring4d 2.0 already has this: https://bitbucket.org/sglienke/spring4d/src/c336b8dd39bfc30cbcf2fa1f6d8323e663bdcc05/Source/Base/Collections/Spring.Collections.Base.pas#lines-473

It is an abstract base class (you don't simply use that one) implemented by several different ready to use collections such as queue, deque, boundedqueue (does not grow like queue does), evictingqueue (drops the oldest element when full)

 

TRingbuffer<T> unfortunately has several defects, mostly around simply using Move regardless the type of T (managed, containing weak reference)

Edited August 24, 2020 by Stefan Glienke

[pyscripter 689]

22 minutes ago, Stefan Glienke said:

Spring4d 2.0

Has this been released?  Is that the develop branch?

[Anders Melander 1784]

31 minutes ago, Stefan Glienke said:

TRingbuffer<T> unfortunately has several defects, mostly around simply using Move regardless the type of T (managed, containing weak reference)

I can't see why using Move would be a problem as long as it just moves entries within the buffer array (which it does as far as I can tell).

However there does seem to be a problem with not clearing empty slots in the array. E.g. by assigning Default(T) to them.

[Stefan Glienke 2005]

40 minutes ago, pyscripter said:

Has this been released?  Is that the develop branch?

No, yes

 

28 minutes ago, Anders Melander said:

I can't see why using Move would be a problem as long as it just moves entries within the buffer array

For managed types you can System.Move them in the internal array - however it also does it when peeking x items into the result array.

For types containing weak reference System.Move does not work even for the internal array.

Edited August 24, 2020 by Stefan Glienke

[Anders Melander 1784]

3 minutes ago, Stefan Glienke said:

For managed types you can System.Move them in the internal array - however it also does it when peeking x items into the result array.

Ah yes. I didn't spot that one. Easy to fix I guess.

 

4 minutes ago, Stefan Glienke said:

For types containing weak reference System.Move does not work even for the internal array.

I don't understand the problem. Please educate me.

[Stefan Glienke 2005]

5 minutes ago, Anders Melander said:

I don't understand the problem. Please educate me.

Read System.Collections.Generics. Particularly the places where it checks for HasWeakRef(T)

What weak references are and how they are handled and why you cannot simply System.Move them refer to System.pas (start with RegisterWeakRef)

Edited August 24, 2020 by Stefan Glienke

[Fr0sT.Brutal 900]

It's enough to use Move for internal relocations (of course, with zeroing an old copy - important nuance) and use assignment in other cases. I do this in my TRecordList<T>

[Stefan Glienke 2005]

33 minutes ago, Fr0sT.Brutal said:

It's enough to use Move for internal relocations (of course, with zeroing an old copy - important nuance) and use assignment in other cases. I do this in my TRecordList<T>

I admit - it's not common but good luck storing something like this in your list then:

 

type
  TMyRecord = record
    [weak]
    something: IWhatever;
  end;

I am not bashing any code here but when something is published as general purpose use (which an unconstrained generic collection class is) then I expect it to work for any T.

If you don't handle this in your private code because you don't have such use case you of course don't need to care.

 

As for TRingBuffer<T> - it leaks strings for example:

 

var
  b: TRingbuffer<string>;
begin
  b := TRingbuffer<string>.Create(8);
  b.Add('one');
  b.Delete(1);
  b.Add(['two', 'three']);
  b.Free;
end;

 

Edited August 24, 2020 by Stefan Glienke

[Uwe Raabe 2057]

7 minutes ago, Stefan Glienke said:

when something is published as general purpose use (which an unconstrained generic collection class is) then I expect it to work for any T.

I made a similar (simple) ring buffer implementation a couple of years ago, which worked well for my needs then, but I refused to publish it due to exactly these issues. Sometimes it is safer to re-implement things for some specific purpose by coding from first principles than use a pre-built all-purpose library implementation, that is neither easy to understand nor easy to debug. I know this is breaking the DIY rule, but it follows the KISS rule.

[Stefan Glienke 2005]

10 minutes ago, Uwe Raabe said:

Sometimes it is safer to re-implement things for some specific purpose by coding from first principles than use a pre-built all-purpose library implementation, that is neither easy to understand nor easy to debug. I know this is breaking the DIY rule, but it follows the KISS rule.

I disagree - if this implementation were done totally naive it would have actually worked for any T yet in a non optimized way - but the author tried to be clever by using Move 😉

Leave implementing generic collections to people experienced with it (which I in no way claim to have monopoly on)

 

P.S. Since the XE7 refactoring disaster of System.Generics.Collections which still has existing bugs as aftermath I am very sensitive regarding this topic.

Edited August 24, 2020 by Stefan Glienke