Wiki improvements

Forum for discussion about the documentation project.
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Jul 31, 2020 15:20

No problem, thanks. I see now that it is good again.
(I thought maybe it was a backup in progress)
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 03, 2020 5:39

Referring to viewtopic.php?p=274317#p274317:
fxm wrote:
Remaining articles or parts of articles from the above post not integrated in the Programmer's Guide (or elsewhere in the Wiki)

I think those above topics do not have to be integrated into the Programmer's Guide, other than maybe the substance (implementation under the hood of vptr, vtbl, rtti info, ...) of the articles 18. How FB supports Sub-Type Polymorphism, demonstrated by Emulation very Close to Real Operating and 19. How using RTTI from FB built-in OBJECT to extract Typename and those of all Bases of an instance which could perhaps feed a new page (OBJECT built-in and RTTI info) in Hacking on FreeBASIC / Compiler internals.
What do you think, admins and users?
coderJeff
Site Admin
Posts: 3198
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 05, 2020 2:37

fxm, the articles are excellent, detailed, and comprehensive. They deserve to go somewhere....
I feel like some articles are for the advanced user for sure, but don't necessarily need to be hidden in the developer / hacking page.

How about adding a 'Technical Articles' section just before 'Other Topics'?

I think there's a couple of existing 'Other Topics' that could move to a 'Technical Articles' kind of classification.
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 05, 2020 5:09

Good idea.

In this new 'Technical Articles' section, I propose to transfer the following existing pages:
- Inline ASM (which is just a link to KeyPgAsm)
- C Standard Library Functions
- File I/O in FreeBASIC
- Dynamic memory management in FreeBASIC
plus add other new pages like the ones proposed:
+ Manage Reusable Procedures by Including Source vs Compiled Modules (will issued from article 11) -> see [edit] below
+ Replace Recursion with Iteration (will issued from article 17)
+ OBJECT built-in and RTTI info (will issued from article 18 and article 19)

There are still some fairly technical pages like for examples:
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #1)
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #2)
- Critical Sections FAQ
which I prefer to leave in their places because they fit well with the section where they are.


[edit]
After some thought, I think the Manage Reusable Procedures by Including Source vs Compiled Modules page would be better at the end of the Programmer's Guide / Source Files section (after Source Files (.bas), Header Files (.bi) and Using Prebuilt Libraries pages)

See now the updated Programmer's Guide page.
(the 3 new 'in progress ...' pages will be filled in one after the other these days)
dodicat
Posts: 6559
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Postby dodicat » Aug 05, 2020 9:55

fxm.
Regarding the OBJECT built-in RTTI info.
I have been experimenting passing this info to other modules via text file and library file.
Text file of course cannot receive this info or indeed any pointer message.
A lib file can transmit a pointer address and another module which can successfully use this address, e.g. passing the address of an array to be used by the module, but the RTTI info passed is not valid.
It seems to me that the RTTI info is easily lost.
Simple example, method2 fails.

Code: Select all

 

Type shape Extends Object
    As Long x,y
    As Long r
    As Ulong clr
End Type

Type circ Extends shape
    Declare Sub show
End Type

Type square Extends shape
    Declare Sub show
End Type


Sub circ.show
    Circle(x,y),r,clr
End Sub

Sub square.show
    Line(x,y)-(x+r,y+r),clr,b
End Sub


Dim As circ c(1 To 2)
Randomize 1
For n As Long=1 To 2
    With c(n)
        .x=100+Rnd*600
        .y=100+Rnd*400
        .r=20+Rnd*100
        .clr=Rnd*Rgb(0,0,0)
    End With
Next n

Dim As square s(1 To 1)
s(1).x=100+Rnd*600
s(1).y=100+Rnd*400
s(1).r=20+Rnd*100
s(1).clr=Rnd*Rgb(0,0,0)


Dim As shape Ptr x(1 To 3)

x(1)=@c(1)
x(2)=@c(2)
x(3)=@s(1)

Dim As shape save(1 To 3) 'dim as object fails completely
For n As Long=1 To 3
    save(n)=*x(n) '<--- information gets lost?
Next n


Screenres 800,600,32
#macro method1
For n As Long=1 To 3
    If Cast(Object,*x(n)) Is shape Then Print "shape"
    If Cast(Object,*x(n)) Is circ Then Cast(circ Ptr,x(n))->show:Print "circ"
    If Cast(Object,*x(n)) Is square Then Cast(square Ptr,x(n))->show:Print "square"
    Print
Next
#endmacro

#macro method2
For n As Long=1 To 3
    If Cast(Object,save(n)) Is shape Then Print "shape"
    If Cast(Object,save(n)) Is circ Then Cast(circ Ptr,x(n))->show:Print "circ"
    If Cast(Object,save(n)) Is square Then Cast(square Ptr,x(n))->show:Print "square"
    Print
Next
#endmacro

method1
'method2

Sleep

 

I shall remove this post later so not to clutter the thread.
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 05, 2020 14:06

When you assign a derived-object to a base-object:
save(n)=*x(n)
obviously the member data specific to the derived-type are not copied, but the vptr is not copied either (the run-time of this base-object must not be promoted into a derived-object because this object has been allocated in memory for a based-object and not for a derived-object).

In your specific and very simple example, the derived-type does not add any member data, so the above rule could be broken against the vptr copy.
A simple hack could solve this problem:

Code: Select all

Dim As shape save(1 To 3) 'dim as object fails completely
For n As Long=1 To 3
    save(n)=*x(n) '<--- information vptr lost
    Cptr(Any Ptr Ptr, @save(n))[0] = Cptr(Any Ptr Ptr, x(n))[0]  '<--- hacking copy of vptr
Next n
dodicat
Posts: 6559
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Postby dodicat » Aug 05, 2020 15:13

Thanks, the hack saves the RTTI.
To pass the methods I still have to use *x(n)
I can now pass the OOP across in a static library.
shapes.bas to be compiled -lib

Code: Select all

'shapes.bas
'compile -lib
type pt extends object
    as long x,y
    as long r
    as ulong clr
end type

type circ extends pt
    declare sub show
end type

type square extends pt
    declare sub show
end type

sub circ.show
    circle(x,y),r,clr
end sub

sub square.show
    line(x,y)-(x+r,y+r),clr,b
end sub

sub savefile(file as string,u() as pt)
    var h=freefile
    open file for binary access write as #h
    put #h, ,u()
    close #h
end sub

dim as circ c(1 to 2)
randomize 1
for n as long=1 to 2
    with c(n)
       .x=100+rnd*600
        .y=100+rnd*400
        .r=20+rnd*100
        .clr=rnd*rgb(0,0,0)
    end with
next n

dim as square s(1 to 1)
        s(1).x=100+rnd*600
        s(1).y=100+rnd*400
        s(1).r=20+rnd*100
        s(1).clr=rnd*rgb(0,0,0)

dim shared as pt  ptr x(1 to 3)

x(1)=@c(1)
x(2)=@c(2)
x(3)=@s(1)

dim shared as pt saveRTTI(1 to 3)
dim shared as pt saveSHAPES(1 to 3)

for n as long=1 to 3
    saveSHAPES(n)=*x(n)
    Cptr(Any Ptr Ptr, @saveRTTI(n))[0] = Cptr(Any Ptr Ptr, x(n))[0]
next n


function size() as long
    return ubound(saveRTTI)
end function

function addressRTTI() as pt ptr
    return @saveRTTI(1)
end function

function addressSHAPES() as pt ptr
    return @saveSHAPES(1)
end function

 

and a test file

Code: Select all

#inclib "shapes"

declare function addressRTTI() as any ptr
declare function addressSHAPES() as any ptr
declare function size() as long

type pt extends object
    as long x,y
    as long r
    as ulong clr
end type

type circ extends pt
    declare sub show
end type

type square extends pt
    declare sub show
end type

screenres 800,600,32
dim as pt ptr a=addressRTTI
dim as pt ptr w=addressSHAPES
dim as long L=size()


for n as long=1 to L
    if *cast(object ptr,a) is pt then print "shape"
    if *cast(object ptr,a) is circ then print "circ":cast(circ ptr,w)->show
    if *cast(object ptr,a) is square then print "square":cast(square ptr,w)->show
    a+=1
    w+=1
    print
next

sleep
 
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 06, 2020 17:42

fxm wrote:Good idea.

In this new 'Technical Articles' section, I propose to transfer the following existing pages:
- Inline ASM (which is just a link to KeyPgAsm)
- C Standard Library Functions
- File I/O in FreeBASIC
- Dynamic memory management in FreeBASIC
plus add other new pages like the ones proposed:
+ Manage Reusable Procedures by Including Source vs Compiled Modules (will issued from article 11) -> see [edit] below
+ Replace Recursion with Iteration (will issued from article 17)
+ OBJECT built-in and RTTI info (will issued from article 18 and article 19)

There are still some fairly technical pages like for examples:
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #1)
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #2)
- Critical Sections FAQ
which I prefer to leave in their places because they fit well with the section where they are.


[edit]
After some thought, I think the Manage Reusable Procedures by Including Source vs Compiled Modules page would be better at the end of the Programmer's Guide / Source Files section (after Source Files (.bas), Header Files (.bi) and Using Prebuilt Libraries pages)

See now the updated Programmer's Guide page.
(the 3 new 'in progress ...' pages will be filled in one after the other these days)

Done.
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 07, 2020 8:36

Regarding the only remaining article not literally integrated in the Programmer's Guide (viewtopic.php?p=274317#p274317):
=> I think it's enough like that.

From my point of view, I have thus finished everything regarding the integration of the 19 articles in the Programmer's Guide.
What new challenge now (in my skills anyway)?
coderJeff
Site Admin
Posts: 3198
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 08, 2020 20:14

Do you feel confident to remove the 'Work in Progress' from the Programmer's Guide? Something I was never able to do.

fxm wrote:From my point of view, I have thus finished everything regarding the integration of the 19 articles in the Programmer's Guide.
What new challenge now (in my skills anyway)?

You should be careful with that open invitation. :)

Can you please critique Object lifetime with reference counting?
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 08, 2020 20:41

coderJeff wrote:Do you feel confident to remove the 'Work in Progress' from the Programmer's Guide?

There are still at least 2 pages (outside of my skills) which are problematic:
- Executables (page to be completed): Imortis has promised to do so when he has free time.
- External Graphics File Formats (page to be filled in): recently I cited counting_pine (viewtopic.php?p=274110#p274110) as having no doubt the skills to do it, but without echo from him.
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 09, 2020 11:27

coderJeff wrote:
fxm wrote:From my point of view, I have thus finished everything regarding the integration of the 19 articles in the Programmer's Guide.
What new challenge now (in my skills anyway)?

You should be careful with that open invitation. :)

In fact, under this is my own questioning:
How can I make myself useful to the community?
srvaldez
Posts: 2464
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Postby srvaldez » Aug 09, 2020 23:50

Hi fxm :-)
your expert advice is more valuable than gold, Richard D. Clark and Ebben Feagan wrote "A Beginner’s Guide to FreeBasic" https://sourceforge.net/projects/fbeginner/ perhaps you might be interested in writing an Advanced version
coderJeff
Site Admin
Posts: 3198
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 10, 2020 1:43

Hey, fxm. Have you seen MissingDocs? Maybe you can sort that out. Or at least put notes on what kind user (expert) is needed to clean it up.

The finishing, in my opinion, is a hard step to complete. It's not for everyone. I think you probably have a very good understanding of the level of completion of the documentation. Next is to make a list of all the things that need to get done next. Either by yourself, or to pass on to another person (because maybe you've had enough of it).

I feel like we're really close to manual milestone. Nothing that I've done of course, as you have brought us all the way the way there I think over last couple years.
fxm
Posts: 9722
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 10, 2020 9:12

Maybe first a little break from the documentation!

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 3 guests