Wiki improvements

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

Re: Wiki improvements

Postby fxm » Aug 12, 2019 19:48

I consider that:
  • For simple variables (including fix-len arrays) declared anywhere, as follows:
    Dim [Byref] [Shared] As datatype [Ptr] variablename
    or
    Static [Byref] Shared As datatype [Ptr] variablename
    they always have a lifetime related to their scope.
  • For simple variables (including fix-len arrays) declared as follows:
    Static [Byref] As datatype [Ptr] variablename
    they always have a lifetime equal to the program duration, so irrelevant to their scope if there are declared in scope blocks (including procedure scopes).
For the other keywords used to declare a dynamic allocation ([Re]Allocate, New, Imagecreate), they create an unnamed entity whose the lifetime depends on other commands of user (Deallocate, Delete, Imagedestroy):
  • Generally, these allocation keywords are included in expressions used to assign or initialize a simple variable as above.
  • Therefore, in this case, there are two distinct entities: a named pointer (or a reference) the first entity, pointing (or referring) to an allocated memory the second entity (unnamed).
  • Do not confuse the two entities, each has its own lifetime (Deallocate, Delete, Imagedestroy deallocating only the second entity, not the first).
In the same way, one can consider a var-len string or var-len array as a predefined assembly of two entities: a descriptor associated to the variable-name, and referring to a dynamic allocation in memory (the string data or the array data).
The string data being [re|de]allocated by string assignment, and array data being [re]allocated by Redim and deallocated by Erase (Erase does not destroy the descriptor but just re-initializes it).

Note:
Var [Byref] [Shared] variablename = expression
is equivalent to:
Dim [Byref] [Shared] As Typeof(expression) variablename = expression
coderJeff
Site Admin
Posts: 3093
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 13, 2019 1:09

fxm, overall, a good summary. I would like to focus on a couple of points:

fxm wrote:1) Do not confuse the two entities, each has its own lifetime (Deallocate, Delete, Imagedestroy deallocating only the second entity, not the first)
2) In the same way, one can consider a var-len string or var-len array as a predefined assembly of two entities: a descriptor associated to the variable-name, and referring to a dynamic allocation in memory (the string data or the array data).


I don't know, maybe it would make sense to have two topics.
1) "Variable Scope and Lifetime" - beginner, most common use cases
2) "Object and Data Lifetime" - advanced, more detailed mechanics of allocation/deallocation, pointers & references

For example:

Code: Select all

scope
   dim a as string = "first"
   dim p as zstring ptr = strptr(a)
   print a, *p '' OK
   a += ", second, reallocated if quite a bit longer"
   print a, *p '' Not OK
end scope


Scope and lifetime of "a" and "p" entities are essentially the same. But, the lifetime of data entity to which "a" and "p" refers (may) change within the scope due to reassignment of the string
- when referring to the data by "a", lifetime of the data is irrelevant
- when referring to the data by "*p", lifetime of data is relevant
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 13, 2019 5:26

And so to make well the difference between a pointer or a reference to a var-len string (by the address of its descriptor) and a pointer or a reference to its data only (by the address of these ones):

Code: Select all

scope
   dim s as string = "first"
   dim ps as string ptr = @s
   dim byref rs as string = s
   dim pz as zstring ptr = strptr(s)
   dim byref rz as Zstring = *strptr(s)
   print s
   print *ps '' OK
   print rs  '' OK
   print *pz '' OK
   print rz  '' OK
   s &= ", second, reallocated if quite a bit longer"
   print s
   print *ps '' OK
   print rs  '' OK
   print *pz '' Not OK
   print rz  '' Not OK
end scope
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 13, 2019 14:24

coderJeff wrote:maybe it would make sense to have two topics.
1) "Variable Scope and Lifetime" - beginner, most common use cases
2) "Object and Data Lifetime" - advanced, more detailed mechanics of allocation/deallocation, pointers & references

Therefore, I propose for the "Programmer's Guide / Declarationns" section:
  • Keeping the existing page "Variable Scope" for the moment (but suppressing the empty page "Variable Lifetime").
  • Filling in 2 new pages (after "Variable Scope") rather focused on the lifetime:
      - "Variable Lifetime versus Scope" - predefined simple variables, excluding var-len strings and var-len arrays, static simple UDT instances.
      - "Object and Data Lifetime" - all dynamic objects, including var-len strings and var-len arrays.
Declarations
    Implicit Declarations
    Initialization
    Storage Classes
    Variable Scope
    Variable Lifetime versus Scope
    Object and Data Lifetime
    Namespaces
    Variable and Procedure Linkage
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 19, 2019 5:27

'Namespaces' page filled in the Programmer's Guide / Declarations:
- ProPgNamespaces → fxm [new page created]
- CatPgProgrammer → fxm [added link to "Namespaces" page]
- PrintToc → fxm [added link to "Namespaces" page]
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 19, 2019 12:04

fxm wrote:
coderJeff wrote:maybe it would make sense to have two topics.
1) "Variable Scope and Lifetime" - beginner, most common use cases
2) "Object and Data Lifetime" - advanced, more detailed mechanics of allocation/deallocation, pointers & references

Therefore, I propose for the "Programmer's Guide / Declarationns" section:
  • Keeping the existing page "Variable Scope" for the moment (but suppressing the empty page "Variable Lifetime").
  • Filling in 2 new pages (after "Variable Scope") rather focused on the lifetime:
      - "Variable Lifetime versus Scope" - predefined simple variables, excluding var-len strings and var-len arrays, static simple UDT instances.
      - "Object and Data Lifetime" - all dynamic objects, including var-len strings and var-len arrays.
Declarations
    Implicit Declarations
    Initialization
    Storage Classes
    Variable Scope
    Variable Lifetime versus Scope
    Object and Data Lifetime
    Namespaces
    Variable and Procedure Linkage

Jeff,

What do you think of this cutting?
Can I start this way?

FX
coderJeff
Site Admin
Posts: 3093
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 22, 2019 13:17

fxm, yes, go for it. Thank you. It's good to have your expertise added to the programmer's guide. You should feel free to cut and rearrange topics as needed. Also, if it makes sense to rename or delete pages, just go ahead as needed because if we really had to get an old version, the pages are also stored in the repo. Besides, I don't think we would need to go back to old versions because of your thoroughness of content. :)
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 25, 2019 9:25

About ProPgVariableLifetime → fxm [new page in progress...] and its example

I tried to code an example to highlight the respective lifetimes of a local variable and a static variable, both declared in a local scope.
This example works with Windows (gas and gcc, 32 and 64 bits):
Going out their scope, the local variable's data are overwritten, but not those of the static variable.

Can anyone check this behavior with Linux or other?
srvaldez
Posts: 2111
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Postby srvaldez » Aug 25, 2019 9:46

on macOS with fbc version 1.07.0 (08-20-2019), built for darwin-x86_64 (64bit)

Code: Select all

Lifetimes comparison between local/static variables declared in a local scope:
     From inside the procedure scope:
              140732898444369             'local variable'
              4317299456    'static variable'
     From outside the procedure scope:
              140732898444369             '?k??         '
              4317299456    'static variable'

on linux Mint VM with fbc Version 1.06.0 (02-17-2019), built for linux-x86_64 (64bit)

Code: Select all

Lifetimes comparison between local/static variables declared in a local scope:
     From inside the procedure scope:
              140735663835681             'local variable'
              6312400       'static variable'
     From outside the procedure scope:
              140735663835681             '              '
              6312400       'static variable'
dodicat
Posts: 5945
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Postby dodicat » Aug 25, 2019 10:57

Scientific Linux (=Red Hat Linux)
32 bits.

Code: Select all

 
Lifetimes comparison between local/static variables declared in a local scope:
     From inside the procedure scope:
              3217155828    'local variable'
              134533612     'static variable'
     From outside the procedure scope:
              3217155828    '         ���J�'
              134533612     'static variable'

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

Re: Wiki improvements

Postby fxm » Aug 25, 2019 16:09

Thank you for your answers.
In view of your results, I improved the address displaying of variables (now, hexadecimal formatting 8/16-digit depending on 32/64-bit).
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 26, 2019 15:08

'Simple Variable Lifetime vs Scope' and 'Dynamic Object and Data Lifetime' pages filled in the Programmer's Guide / Declarations:
- ProPgVariableLifetime → fxm [new page created]
- ProPgObjectLifetime → fxm [new page created]
- CatPgProgrammer → fxm [predisposed links to "Simple Variable Lifetime vs Scope" and "Dynamic Object and Data Lifetime" pages]
- PrintToc → fxm [predisposed links to "Simple Variable Lifetime vs Scope" and "Dynamic Object and Data Lifetime" pages]
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 29, 2019 15:12

Starting from the content of my article on references, I propose to add two pages:
- "From Pointers to References"
- and "Using References"
- in a new section "References"
of the "Programmer's Guide / Variables and Datatypes", as follows:
    Programmer's Guide

    .....
    .....

    Variables and Datatypes
      Constants and Enumerations
      Numeric Types
      Strings (string, zstring, and wstring)
      Coercion and Conversion
      Constants
      Variables

      Arrays
        Overview
        Fixed-length Arrays
        Variable-length Arrays
        Array Indexing
        Passing Arrays to Procedures
      Pointers
        Overview
        Pointer Arithmetic
      References
        From Pointers to References
        Using References
    .....
    .....

What do you think?
aloberoger
Posts: 476
Joined: Jan 13, 2009 19:23

Re: Wiki improvements

Postby aloberoger » Aug 30, 2019 15:54

this exemple completly works with the new version

Code: Select all

scope
   dim s as string = "first"
   dim ps as string ptr = @s
   dim byref rs as string = s
   dim pz as zstring ptr = strptr(s)
   dim byref rz as Zstring = *strptr(s)
   print s
   print *ps '' OK
   print rs  '' OK
   print *pz '' OK
   print rz  '' OK
   s &= ", second, reallocated if quite a bit longer"
   print s
   print *ps '' OK
   print rs  '' OK
   print *pz ''  OK
   print rz  ''  OK
end scope
fxm
Posts: 9186
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 30, 2019 16:48

Indeed, I got some times a correct display with "Version 1.08.0 (08-26-2019), built for win64 (64bit)", but I guess after reallocation of memory, the old location has not been allocated for anything else and therefore the characters data have not been overwritten.

I completed the code to display the address of the characters data pointed at each display line, to check if the characters data memory has been effectively reallocated:

Code: Select all

scope
   dim s as string = "first"
   dim ps as string ptr = @s
   dim byref rs as string = s
   dim pz as zstring ptr = strptr(s)
   dim byref rz as Zstring = *strptr(s)
   print "'" & s & "'",,,, strptr(s)
   print "'" & *ps & "'",,,, strptr(*ps) '' OK
   print "'" & rs & "'",,,, strptr(rs)   '' OK
   print "'" & *pz & "'",,,, pz          '' OK
   print "'" & rz & "'",,,, @rz          '' OK
   s &= ", second, reallocated if quite a bit longer"
   print "'" & s & "'", strptr(s)
   print "'" & *ps & "'", strptr(*ps)    '' OK
   print "'" & rs & "'", strptr(rs)      '' OK
   print "'" & *pz & "'",,,, pz          '' NOK
   print "'" & rz & "'",,,, @rz          '' NOK
end scope

Code: Select all

'first'                                                 7740352
'first'                                                 7740352
'first'                                                 7740352
'first'                                                 7740352
'first'                                                 7740352
'first, second, reallocated if quite a bit longer'      7757680
'first, second, reallocated if quite a bit longer'      7757680
'first, second, reallocated if quite a bit longer'      7757680
''_v'                                                   7740352
''_v'                                                   7740352

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 38 guests