Blitz3D+ Command Reference

JobErrorFunction$ ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns the name of the Worker Function retained for a failed job, or an empty string.

This is the third piece of the worker failure diagnostics, alongside JobErrorFile and JobErrorLine: it names the innermost Worker Function that was executing when the runtime error was raised. Worker helpers are themselves Worker Functions, so when a helper deep inside your job blows up, this names the helper, not just the entry function you passed to StartJob - which is usually exactly the clue you need.

The name comes back in lower case ("verifychecksum" for a function written as VerifyChecksum), because Blitz3D+ identifiers are case-insensitive and the compiler stores them lowercased. Compare with Lower$ on your side if you match against it.

Worker failures never open the GUI debugger from the background thread, so logging JobError plus these three retained positions is the standard way to make background failures diagnosable. It returns a meaningful name only while JobState is JOB_FAILED; for every other state it returns an empty string.

For the full story, see the Using Background Jobs guide.

Requires Extended mode.

See also: JobError, JobErrorFile, JobErrorLine, JobState.

Example

; JobErrorFunction Example
; ------------------------
; Requires Extended mode.

Graphics 640,480,0,2
SetBuffer BackBuffer()

; The checksum helper is where the deliberate failure happens
Worker Function VerifyChecksum(stored)
    If stored<>1234 Then RuntimeError "Save file checksum mismatch"
    Return True
End Function

; This worker fails on purpose while loading a corrupted save file
Worker Function LoadCorruptSave(inputBank)
    SetJobProgress 1L,2L,"Verifying checksum"
    ; Busy work standing in for real parsing
    For parse=1 To 4000000
        noise#=Sin(parse)
    Next
    ; The stored checksum is wrong, so the helper raises the error
    VerifyChecksum(9999)
    Return CreateBank()
End Function

job=StartJob(LoadCorruptSave)

While Not KeyDown(1)

    Cls

    Text 0,0,"Esc: exit"
    Text 70,160,"Loading save file on a worker thread..."

    If JobState(job)=JOB_FAILED
        ; JobErrorFunction names the innermost Worker Function that failed
        Text 70,210,"JobErrorFunction(job) = "+Chr(34)+JobErrorFunction(job)+Chr(34)
        Text 70,240,"JobError(job) = "+Chr(34)+JobError(job)+Chr(34)
        Text 70,270,"The failure happened inside the VerifyChecksum helper"
    Else
        Text 70,210,"Still loading..."
    EndIf

    Flip

Wend

FreeJob job
End

Index