Wiki improvements

[coderJeff]

If I'm not mistaken, any graphics command will use the internal graphics mutex for serializing access to graphics memory. So, a mutex is not required, but there is one present, implicitly.

[MrSwiss]

Well, this idea comes straight from "what it says in the documentation":
ThreadDetach -- thread may not yet be finished executing
ThreadWait -- assures that thread has terminated
(in a nutshell)

[fxm]

See my FAQ in the 'Programmer's Guide / Multi-Threading / Critical Sections FAQ' :
8. How to use the FB runtime library for multi-threaded applications (gfxlib2) with multi-threading?

[dodicat]

This one is not destined for any help file.
I have added sine squared for a little change, required IMHO, and used callback macros, if there is such a thing.
It is not as async as I had hoped for, but I'll leave this as my swan song contribution.

Code: Select all

#macro Linear(x) 
     x
#endmacro

#macro Quadratic(x) 
     x * x
#endmacro

#macro Sinusoidal(x)
     Sin(x)
#endmacro

function squareW(x as double)as double 
    dim f as double
    for n as double=1 to 500 step 2
        f=f+sin(n*x)/n
    next n
    f=.5-(6/3.142)*f
    return f
end function

#macro sinesquared(x)
squareW(x)
#endmacro


#macro PlotF(what)
    PSet( -15, what(-15) )
    For x As Double = -15 To 15 Step 0.1
        Line -( x, what(x) )
    Next
#endmacro

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

plotF(Linear)
plotF(Quadratic)
plotF(Sinusoidal)
color 4
plotF(sinesquared)
sleep

 

[badidea]

...

I have added your asynchronous example from 23 Sep 2020, 10:18 with the remark/explanation:
"Similar plotting example (as above) but with a asynchronous callback. Here an artificial delay is added. A more realistic case would be if the data to be plotted is retrieved form a web-server with a response time larger than acceptable for the main loop of our program (prevent blocking behavior)"

I still have some problems with the term asynchrone callback. I understand asynchrone. I understand callback. But the two combined does not seem like something completely new. Analogue to 'blue cars'. I understand what a car is. I somewhat understand blue (although quite completed if you think about it). And I can accept that blue cars exist, but it is not a new thing that you find in a dictionary under 'blue car'.

(maybe I am confusing programming with philosophy)

[fxm]

Synchronous or asynchronous callback process

A callback procedure is a procedure that is passed as an argument (a procedure pointer) to another procedure which is expected to call back (execute) the "argument" at a convenient time.
This invocation may induce a callback process in a synchronous mode, or it might induce a callback process in an asynchronous mode:

• If the callback procedure is completely executed before the invocation returns to the caller code, then the callback process is said to be "synchronous".
• If the invocation immediately returns to the caller code, and the callback procedure and the caller's next code are running in parallel, then the callback process is said to be "asynchronous".

In the first two examples in the "Callback" documentation page, the invocation is implemented by calling the "PlotF()" procedure, and the callback function is the "Linear()", "Sinusoidal()", or "Quadratic()" function:

• In the first example, the three callback processes are synchronous because each callback function is completely executed before "PlotF()" returns to the caller code.
• In the second example, the three callback processes are asynchronous because the "PlotF()" function returns immediately, and each callback function is executed in parallel with the caller's next code, from a "ThreadPlot()" thread created (previously) by "PlotF()" for each of them.

In the third example in the "Callback" documentation page, the invocation is implemented by calling the "qsort()" procedure, and the callback function is the "CmpVarLenStr()" function:

• The callback process is synchronous because the callback function is completely executed (several times), (successively) called by "qsort()", before "qsort()" returns to the caller code.

[badidea]

The same asynchronous behavior is also possible without callbacks:

Code: Select all

Enum E_MATH
	E_MATH_LIN
	E_MATH_QUAD
	E_MATH_SIN
End Enum

#Include "fbthread.bi"

Sub ThreadPlot(Byval userData As Any Ptr)
	Sleep 1500, 0
	Dim As E_MATH MathFunction = Cast(E_MATH, userData)
	Dim As Double y
	Window (-15,-10)-(15,10)
	For x As Double = -15 To 15 Step 0.1
		Select Case mathFunction
		Case E_MATH_LIN:  y = x
		Case E_MATH_QUAD: y = x * x
		Case E_MATH_SIN:  y = Sin(x)
		End Select
		Pset(x, y)
	Next
End Sub

Function PlotF(mathFunction As E_MATH) As String
	Print "Plotting requested"
	Threaddetach( Threadcreate( @ThreadPlot, Cptr(Any Ptr, mathFunction) ) )
	Return "Plotting request taken into account"
End Function

Screen 19

Print PlotF(E_MATH_LIN)
Print PlotF(E_MATH_QUAD)
Print PlotF(E_MATH_SIN)

Print "Main program continues ";
For i As Integer = 1 To 15
	Print ".";
	Sleep 200, 0
Next i
Print
Print "Main program finished"

Sleep

[fxm]

The same asynchronous behavior is also possible without callbacks

This is also true for synchronous behavior, but in these cases the mathematical functions to be used must be defined inside the procedure which is to apply them.

Another variant is to pass a complex object (containing the specialized math function) similarly to my previous example (viewtopic.php?p=276365#p276365) that can also operate in asynchronous mode:

Code: Select all

#Include "fbthread.bi"

Type MathFunction Extends Object
   Declare Abstract Function f( ByVal x As Double ) As Double
End Type

Type Linear Extends MathFunction
   Declare Function f( ByVal x As Double ) As Double Override
End Type
Function Linear.f( ByVal x As Double ) As Double
   Return x
End Function

Type Quadratic Extends MathFunction
   Declare Function f( ByVal x As Double ) As Double Override
End Type
Function Quadratic.f( ByVal x As Double ) As Double
   Return x * x
End Function

Type Sinusoidal Extends MathFunction
   Declare Function f( ByVal x As Double ) As Double Override
End Type
Function Sinusoidal.f( ByVal x As Double ) As Double
   Return Sin(x)
End Function

Sub ThreadPlot(Byval userData As Any Ptr)
   Sleep 1500, 1
   Dim As MathFunction Ptr pmf = userData
   Window (-15,-10)-(15,10)
   For x As Double = -15 To 15 Step 0.1
      Pset(x, pmf->f(x))
   Next
End Sub

Function PlotF(Byref mt As MathFunction) As String
   Print "Plotting requested"
   Threaddetach( Threadcreate( @ThreadPlot, @mt ) )
   Return "Plotting request taken into account"
End Function

Screen 19

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

Print "Main program continues ";
For i As Integer = 1 To 15
   Print ".";
   Sleep 200, 1
Next i
Print
Print "Main program finished"

Sleep

The interest is to generalize the plotting (possibility to simply add a new function without modifying the procedure called to plot it).

[fxm]

Duplicated from viewtopic.php?p=276720#p276720:

Please add 'SCREENEVENT' to See Also at MULTIKEY, GETMOUSE, and GEYJOYSTICK.



Many years ago, when I found this, I felt cheated that it took so long to discover. Answers (like above) almost always neglect to mention this keyword.
While using this the feeling of re-inventing the wheel may happen, but that's one thing we all do here frequently.

This keyword is ESPECIALLY useful when writing your own low-level thread routines.

fxm: this keyword could use its own instructional topic. Understanding the EVENT structure and use can shed a lot of light on input related to FB core threading, FB graphics threading, and how the OS is related to FB I/O operations. Writing one's own function set may be out of reach for most, but the explanations in this topic would clarify input questions for a great many beginners, I suspect.

david

1)
- KeyPgMultikey → fxm [added link to 'Event' and 'ScreenEvent' in 'See also' paragraph]
- KeyPgGetjoystick → fxm [added link to 'Event' and 'ScreenEvent' in 'See also' paragraph]
- KeyPgGetmouse → fxm [added link to 'ScreenEvent' in 'See also' paragraph]

2)
Perhaps a new page in the 'Programmer's Guide / Other Topics' section ?

.....

Other Topics
(And topics that need to get placed elsewhere)

• ASCII
  Date Serials
  Radians
  Error Handling
  Event Catching
  Intrinsic Defines

.....

[D.J.Peters]

Hello fxm,
looks like writing good FreeBASIC help stuff is a kind of hobby or pasion for you.

If you have fun and time I would like to see a more real world example of overloading the FOR/NEXT/STEP operators.

May be it's only me but I don't get it
if the FOR "counter" = "from" to "end" STEP "value" must be the same datatype !

Can you show us how to overloading FOR/NEXT/STEP so we can do something like this code please ?

Joshy

I'm sure you know what I mean :-) pseudo code:

Code: Select all

type tVector
  as single x,y,z
end type
type tTriangle
  as tVector   vectors()
  ' or
  as tVector ptr  vectors
end type
type tMesh
  as tTriangle triangles()
  ' or
  as tTriangle ptr triangles
end type
type tScene
  as tMesh      meshes()
  ' or
  as tMesh ptr  meshes
end type
' ...
dim as tScene scene
' ...

for mesh as tMesh = 0 to scene.meshes
  for triangle as tTriangle = 0 to mesh.triangles
    for vector as tVector = 0 to triangle.vectors
      print vector.x, vector.y, vector.z
    next
  next
next

[fxm]

Before opening your post in 'Wiki improvements', I thought for a second that you volunteered to write the 'Event Catching' documentation page !

[speedfixer]

Thank you for the added references.

Event Catching -- sounds too much like a more generalized topic relating to catching/handling an event. Yeah, but this *specific* event (FB EVENT structure) is handed to us by the language - not the same.

Probably something more like 'FreeBASIC EVENT handling' would set it apart from a general event management topic.
Hopefully anyone would recognize the caps on 'event' would mean a keyword reference. Even simple titles can be more work than expected.

A discussion of using this with and without threading will help explain to beginners why simply throwing another 'x = INKEY' somewhere may not be a good idea.

david

[fxm]

Event Catching -- sounds too much like a more generalized topic relating to catching/handling an event. Yeah, but this *specific* event (FB EVENT structure) is handed to us by the language - not the same.

Probably something more like 'FreeBASIC EVENT handling' would set it apart from a general event management topic.
Hopefully anyone would recognize the caps on 'event' would mean a keyword reference. Even simple titles can be more work than expected.

I proposed this title by analogy with the other title 'Error Handling' already existing.
But it might be good if both titles were personalized the same ? :
- 'FreeBASIC ERROR Handling'
- 'FreeBASIC EVENT Handling'
or (to be consistent with other titles):
- 'ERROR Handling with FreeBASIC'
- 'EVENT Handling with FreeBASIC'

[fxm]

A discussion of using this with and without threading will help explain to beginners why simply throwing another 'x = INKEY' somewhere may not be a good idea.

I do not see where the problem is.
EVENT queuing and INKEY buffering are two completely independent ways to test the keyboard state.
They can be used in two competing threads (each in one thread) without any conflict.

Simple example highlighting that none keyboard action is lost, viewed from each thread:
(ESC to quit)

Code: Select all

#include "fbgfx.bi"

Sub Thread (Byval p As Any Ptr)
    Dim e As fb.Event
    Do
        If (ScreenEvent(@e)) Then
            Select Case As Const e.type
            Case fb.EVENT_KEY_PRESS
                Print "'" & Chr(e.ascii) & "'" " was pressed"
                If (e.scancode = fb.SC_ESCAPE) Then
                    Exit Sub
                End If
            Case fb.EVENT_KEY_RELEASE
                Print "'" & Chr(e.ascii) & "'" & " was released"
            Case fb.EVENT_KEY_REPEAT
                Print "'" & Chr(e.ascii) & "'" & " is being repeated"
            End Select
        End If
        Sleep 1, 1
    Loop
End Sub


Screen 19

Dim As String s
Dim As Any Ptr p
p = Threadcreate(@Thread)

Do
    s = Inkey
    If s <> "" Then
        Print "'" & s & "'" & " is viewed"
    End If
    Sleep 1, 1
Loop Until s = Chr(27)

Threadwait(p)

Sleep

[fxm]

Can you show us how to overloading FOR/NEXT/STEP so we can do something like this code please ?
(pseudo code)

Code: Select all

type tVector
  as single x,y,z
end type
type tTriangle
  as tVector   vectors()
  ' or
  as tVector ptr  vectors
end type
type tMesh
  as tTriangle triangles()
  ' or
  as tTriangle ptr triangles
end type
type tScene
  as tMesh      meshes()
  ' or
  as tMesh ptr  meshes
end type
' ...
dim as tScene scene
' ...

for mesh as tMesh = 0 to scene.meshes
  for triangle as tTriangle = 0 to mesh.triangles
    for vector as tVector = 0 to triangle.vectors
      print vector.x, vector.y, vector.z
    next
  next
next

I think I understand what you are functionally trying to achieve, but with a more compact syntax than this:

Code: Select all

for i as integer = lbound(scene.meshes) to ubound(scene.meshes)
  for j as integer = lbound(scene.meshes(i).triangles) to ubound(scene.meshes(i).triangles)
    for k as integer = lbound(scene.meshes(i).triangles(j).vectors) to ubound(scene.meshes(i).triangles(j).vectors)
      print scene.meshes(i).triangles(j).vectors(k).x, _
            scene.meshes(i).triangles(j).vectors(k).y, _
            scene.meshes(i).triangles(j).vectors(k).z
    next k
  next j
next i

For that, I do not see what the overload of the operators 'FOR' / 'NEXT' / 'STEP' could bring.

I only see the use of shortcuts by using chained (and nested) 'WITH's:

Code: Select all

with scene : for i as integer = lbound(.meshes) to ubound(.meshes)
  with .meshes(i) : for j as integer = lbound(.triangles) to ubound(.triangles)
    with .triangles(j) : for k as integer = lbound(.vectors) to ubound(.vectors)
      with .vectors(k) : print .x, .y, .z : end with
    next k : end with
  next j : end with
next i : end with