Function Pointerkeyword

Data type that stores a pointer to a Function procedure returning a value

Syntax

Dim variable As Function [cdecl|pascal|stdcall] [( [parameter_list] )] [ ByRef ] [As return_type] [= initializer]

Parameters

Name		Description
`parameter_list`		: parameter[, parameter[, ...]]
`parameter`		: `[ByRef\|ByVal] identifier [As type] [= default_value]`
`identifier`		: the name of the variable referenced in the function
`type`		: the type of variable
`default_value`		: the value of the argument if none is specified in the call
`return_value`		: the value returned from the function
`intializer`		: address of a function to set as the initial value

Description

A Function pointer is a procedure pointer that stores the memory location of compiled code that returns a value. If no intializer is given the default initial value is zero (0).

The memory address for the Function procedure can be assigned to the variable by taking the address of a function with ProcPtr or Operator @ (Address Of).

The procedure must match the same Function declaration as the declared Function pointer.

To call the function assigned, use the variable name as if it were a normal declared Function, always with parentheses around the parameter list even empty (without parentheses, only the pointer value, ie the address of the function, would be accessed).

One of the primary uses for Function pointers is to create callback procedures:

- A callback Function is a Function that is passed through an argument (a Function pointer) to another procedure which is expected to call back (execute) the "argument" at a convenient time.
- If the callback Function 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 Function and the caller's next code are running in parallel, then the callback process is said to be "asynchronous".

Remarks

Differences from QB

New to FreeBASIC

Example

Function ConcatSelf( x As String ) As String

    Return x & x

End Function



Dim x As Function( x As String ) As String = ProcPtr( ConcatSelf )



Print x( "Hello" )

Function x2 (ByVal i As Integer) As Integer

  Return i * 2

End Function



Function x3 (ByVal i As Integer) As Integer

  Return i * 3

End Function



Function operation (ByVal i As Integer, ByVal op As Function (ByVal As Integer) As Integer) As Integer

  Return op(i)

End Function



Print operation(4, @x2)

Print operation(4, @x3)

' Example of basic callback Function mechanism (asynchronous) to implement a key pressed event:

' (the user callback Function address cannot be modified while the event thread is running)

'   - An asynchronous thread tests the keyboard in a loop, and calls a user callback Function each time a key is pressed.

'   - The callback Function address is passed to the thread.

'   - The callback Function prints the character of the key pressed,

'       but if the key pressed is <escape> it orders the thread to finish by using the function return value.

'   - As the user callback address is passed to the thread as argument, it cannot be modified while the thread is running.





'' thread Sub definition

  Sub threadInkey (ByVal p As Any Ptr)

    If p > 0 Then                                                '' test condition callback Function defined

      Dim As Function (ByRef As String) As Integer callback = p  '' convert the any ptr to a callback Function pointer

      Do

        Dim As String s = Inkey

        If s <> "" Then                                          '' test condition key pressed

          If callback(s) Then                                    '' test condition to finish thread

            Exit Do

          End If

        End If

        Sleep 50, 1

      Loop

    End If

  End Sub



'' user callback Function definition

  Function printInkey (ByRef s As String) As Integer

    If Asc(s) = 27 Then                                        '' test condition key pressed = <escape>

      Print

      Return -1                                                '' order thread to finish

    Else

      Print s;

      Return 0                                                 '' order thread to continue

    End If

  End Function



'' user main code

  Dim As Any Ptr p = ThreadCreate(@threadInkey, @printInkey)   '' launch the thread, passing the callback Function address

  ThreadWait(p)                                                '' wait for the thread finish

Reference

Documented in KeyPgFunctionPtr.html