Wiki improvements

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

Re: Wiki improvements

Post by fxm »

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: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

'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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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: 3373
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Post by srvaldez »

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: 7976
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Post by dodicat »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

'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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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: 507
Joined: Jan 13, 2009 19:23

Re: Wiki improvements

Post by aloberoger »

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
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

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
Post Reply