Wiki improvements

[fxm]

I just realized that I forgot to create the documentation page for 'fb_MemCopyClear' ('fb_MemCopy' and 'fb_MemMove' created only).
I'll take care of it now!

Done:
KeyPgFBMemcopyclear → fxm [new page created]

Note:
I discovered this oversight while reading the change line:
- rtlib: internal fb_MemCopyClear() argument types changed to expect unsigned lengths (UINTEGER => size_t)
in the 'changelog.txt' file, and it seems good to me to document it given that we have documented 'fb_MemCopy' and 'fb_MemMove'.
(I think there are other procedures of the form 'fb_xxx' which are directly accessible but not documented because not really necessary for the user).

[MrSwiss]

(I think there are other procedures of the form 'fb_xxx' which are directly accessible but not documented because not really necessary for the user).

Sorry but I beg to differ, on the statement: "... because not really necessary for the user".
I prefer my own judgement when it comes to decide WHAT is necessary or not.
(You can freely express your opinions but don't make them look like they're everyone elses too.)

In case it was a question like: "Should they be documented too?" then its a clear YES from my side.

[coderJeff]

Hi MrSwiss.
Have you looked at freebasic run time library code? It's freely available.

There's probably 700 or more 'fb_*' functions in the rtlib public API - what the fbc compiler depends on. Plus another 500+ functions that are 'directly' accessible that are used internally by the library only. Plus hundreds of other functions used by drivers and platform specifics.

'Necessary' is imprecise. All the functions are necessary from the perspective of a developer. Not so much from perspective of a user -- they can write normal source code in freebasic, no?

'Cost effective' might be better criteria. The cost of our real time to formally document internals, which may or may not result in something 'useful'. Decided by those people spending their own free time to get it done.

[counting_pine]

The other problem with over-documentation is that any changes to documented functions will potentially cause breakages for people who have come to rely on those functions.
So it imposes more rigidity on the internal structure of the code, or risks breaking trust with developers, or requires them to more actively review changelogs and keep their code up to date.

[badidea]

@fxm: Do you know if the concept 'callback' is decently documented on the wiki somewhere?
After this question Callback functions in freebasic I tried to look in the documentation, but I could only find pieces of documentation.

[Tourist Trap]

@fxm: Do you know if the concept 'callback' is decently documented on the wiki somewhere?
After this question Callback functions in freebasic I tried to look in the documentation, but I could only find pieces of documentation.

Hi badidea,

for me this post (-> Paul does') is a must read on the topic, it opened my eyes on this affair:
viewtopic.php?p=245419#p245419

Based on this anyone can start writing a very decent tutorial on callbacks. Maybe you could :)

[fxm]

There are currently only a few references to callback-function techniques in the documentation.
The list, except for those referring to a library:
- ProPgObjectRtti : just an example of code
- ProPgMtThreads : just an example of code
- KeyPgSubPtr : just a definition sentence + an example of code
- KeyPgFunctionPtr : same definition sentence + similar example of code

Maybe a new page to create in Programmer's Guide / Technical Articles ?

[badidea]

I think I can make the article, but today happened faster than planned. I saved links to all relevant stuff as a start.
Should it not be under Programmer's Guide / Procedures / Callback (Procedures) and "in FreeBASIC" can be left out, I would think.

[fxm]

Yes, in the same way that "Recursion" is there too.

Have you seen the Good Example of Jeff (simple and demonstrative) ?

[badidea]

Have you seen the Good Example of Jeff (simple and demonstrative) ?

Yes, I added that one now to https://www.freebasic.net/wiki/ProPgCallback
I did not like dodicats "Cast(Function(As String) As Integer, callback) (s)". Way too much stuff going on in one line.
I like to a add (later) a short (quick)sort algorithm as a example and a example of a typical asynchronous callback with a separate thread.

[fxm]

For the Callback article, I propose the same example that the first (from Jeff) but transposed to asynchronous callbacking via a thread:

Code: Select all

#include "fbthread.bi"

Type MathFunction As Function( ByVal x As Double ) As Double

Function Linear( ByVal x As Double ) As Double
    Return x
End Function

Function Quadratic( ByVal x As Double ) As Double
    Return x * x
End Function

Function Sinusoidal( ByVal x As Double ) As Double
    Return Sin(x)
End Function

Sub ThreadPlotF( ByVal p As Any Ptr )
    Dim f As MathFunction = p
    Window (-15,-10)-(15,10)
    '' sleep added only to check the asynchronous way of the callback
    Sleep 1500, 1
    PSet( -15, f(-15) )
    For x As Double = -15 To 15 Step 0.1
        Line -( x, f(x) )
    Next
End Sub

Screen 19

ThreadDetach( ThreadCreate( @ThreadPlotF, @Linear ) )
ThreadDetach( ThreadCreate( @ThreadPlotF, @Sinusoidal ) )
ThreadDetach( ThreadCreate( @ThreadPlotF, @Quadratic ) )

'' following code added only to check the asynchronous way of callbacks
Print "Asynchronous callbacks requested"
Print "Main program continues ";
For I As Integer = 1 to 15
    Print ".";
    Sleep 200, 1
Next I
Print
Print "Main program finished"

Sleep

[dodicat]

There are quite a few definitions of asynchronous callbacks, some say that waiting for a return value makes the callback synchronous.
In this case the the C sort callback and my own quicksort callbacks are synchronous.

Quote from stack overflow:
"In computer programming, a callback is a piece of executable code that is passed as an argument to other code, which is expected to call back (execute) the argument at some convenient time. The invocation may be immediate as in a synchronous callback, or it might happen at a later time as in an asynchronous callback."

I don't know This would be classed though!

Code: Select all

Sub Linear(x As Double,Byref y As Double ) 
    y=x
End Sub

Sub Quadratic(x As Double,Byref y As Double )
    y= x * x
End Sub

Sub Sinusoidal(x As Double,Byref y As Double ) 
    y= Sin(x)
End Sub

Sub Plot( Byval p As Any Ptr )
    #define range(f,l) Rnd*((l)-(f))+(f)
    Dim As Double x=range(-15,15),y
    Cast(Sub(As Double,Byref As Double),p)(x,y)
    Pset(x,y)
End Sub

Screen 19
Window (-15,-10)-(15,10)

sub server
Dim As Sub(As Double,Byref As Double) f(1 To 3)={@linear,@Quadratic,@Sinusoidal}
Do
    plot(f(Int(1+Rnd*3)))
Loop Until Len(Inkey)
end sub

server

Sleep
 

[fxm]

For the Callback article, I propose another simple example of qsort algorithm to sort a var-len string array (forename list in this case):

Code: Select all

#include "crt/stdlib.bi"

Function CmpVarLenStr cdecl( Byval p1 As Any Ptr, Byval p2 As Any Ptr ) As long  '' compare 2 var-len strings
    Dim As String Ptr ps1 = p1
    Dim As String Ptr ps2 = p2
    If *ps1 < *ps2 Then
        Return -1
    Elseif *ps1 > *ps2 Then
        Return 1
    Else
        Return 0
    End If
End Function

Sub PrintList( array() As String)  '' print a var-len string list
    For I As Integer = Lbound(array) To Ubound(array)
        Print array(I)
    Next I
    Print
End Sub

Dim forename(1 to 12) As String = {"Madison", "Emily", "Hailey", "Sarah", "Kaitlyn", "Hannah", _
                                   "Jacob", "Christopher", "Nicholas", "Michael", "Matthew", "Joshua" }

Print "LIST OF UNSORTED FORENAMES:"
PrintList( forename() )

qsort( @forename(Lbound(forename)), Ubound(forename) - Lbound(forename) + 1, Sizeof(String), @CmpVarLenStr )

Print "LIST OF SORTED FORENAMES:"
PrintList( forename() )

Sleep

[badidea]

For the Callback article, I propose the same example that the first (from Jeff) but transposed to asynchronous callbacking via a thread: ...

There are quite a few definitions of asynchronous callbacks, some say that waiting for a return value makes the callback synchronous. In this case the the C sort callback and my own quicksort callbacks are synchronous.

Quote from stack overflow:
"In computer programming, a callback is a piece of executable code that is passed as an argument to other code, which is expected to call back (execute) the argument at some convenient time. The invocation may be immediate as in a synchronous callback, or it might happen at a later time as in an asynchronous callback."

I start to get confused about the term callback. In the plotting example of fxm with the threads there is delay (asynchrone behavior) compared to the main thread. But the callback 'MathFunction' is still synchrone to its plotting thread.
This callback seems different compared to this:
1. I start a phone call and dial dodicat's number.
2. Dodicat is not at home, his sectary answers, I ask if dodicat can call me back later.
3. I end the pone call waits for dodicats call (back).

I think I saw a sound example on the forum some time ago where a callback was used whenever the playing device was nearing the end of the sound buffer and additional sound data was requested. There the whole callback mechanism made sense to me. Now, not so such.

Maybe the plotting example would make more sense if first some heavy calculation needs to be done before the plotting can start. This heavy calculation is the 1.5 second delay then.

Note: qsort example added to the page.

[fxm]

I think the interpretation may depend on how the called procedure is structured.
- If the procedure called is a function which returns when finishing an acknowledgment "Plotting request taken into account" when the plotting request is effectively taken into account but not yet applied,
- and that later the plotting request is really executed (asynchronously in another thread, by calling the passed math function then plotting),
one can saying that this callback is asynchronous:

Code: Select all

#include "fbthread.bi"

Type MathFunction As Function( ByVal x As Double ) As Double

Sub ThreadPlot( ByVal p As Any Ptr )
    Sleep 1500, 1  '' sleep added only to check the asynchronous way of the callback
    Dim f As MathFunction = p
    Window (-15,-10)-(15,10)
    PSet( -15, f(-15) )
    For x As Double = -15 To 15 Step 0.1
        Line -( x, f(x) )
    Next
End Sub

Function PlotF( ByVal f As MathFunction ) As String
    Print "Plotting requested"
    ThreadDetach( ThreadCreate( @ThreadPlot, f ) )
    Return "Plotting request taken into account"
End Function

'===================================================================================

Function Linear( ByVal x As Double ) As Double
    Return x
End Function

Function Quadratic( ByVal x As Double ) As Double
    Return x * x
End Function

Function Sinusoidal( ByVal x As Double ) As Double
    Return Sin(x)
End Function

'-----------------------------------------------------------------------------------

Screen 19

Print PlotF( @Linear )
Print PlotF( @Sinusoidal )
Print PlotF( @Quadratic )

'-----------------------------------------------------------------------------------

'' following code added only to check the asynchronous way of callbacks
Print "Main program continues ";
For I As Integer = 1 to 15
    Print ".";
    Sleep 200, 1
Next I
Print
Print "Main program finished"

'-----------------------------------------------------------------------------------

Sleep

To be compared with the synchronous callback:

Code: Select all

Type MathFunction As Function( ByVal x As Double ) As Double

Sub Plot( ByVal f As MathFunction )
    Window (-15,-10)-(15,10)
    PSet( -15, f(-15) )
    For x As Double = -15 To 15 Step 0.1
        Line -( x, f(x) )
    Next
End Sub

Function PlotF( ByVal f As MathFunction ) As String
    Print "Plotting requested"
    Plot( f )
    Return "Plotting request executed"
End Function

'===================================================================================

Function Linear( ByVal x As Double ) As Double
    Return x
End Function

Function Quadratic( ByVal x As Double ) As Double
    Return x * x
End Function

Function Sinusoidal( ByVal x As Double ) As Double
    Return Sin(x)
End Function

'-----------------------------------------------------------------------------------

Screen 19

Print PlotF( @Linear )
Print PlotF( @Sinusoidal )
Print PlotF( @Quadratic )

Sleep

The difference is mainly the code inside the PlotF() function called:

Code: Select all

' asynchronous:
Function PlotF( ByVal f As MathFunction ) As String
    Print "Plotting requested"
    ThreadDetach( ThreadCreate( @ThreadPlot, f ) )
    Return "Plotting request taken into account"
End Function

' synchronous:
Function PlotF( ByVal f As MathFunction ) As String
    Print "Plotting requested"
    Plot( f )
    Return "Plotting request executed"
End Function