Blitz3D+ Command Reference

JobError$ ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns a failed job's error message, or an empty string.

When a Worker Function hits a runtime error - a bad Peek offset, a RuntimeError of its own, an out-of-bounds array - the job simply ends in JOB_FAILED with the message retained here, instead of crashing your program or popping the debugger from a background thread. Read it after JobState reports JOB_FAILED, log it or show it, then FreeJob.

The message is a bounded main-thread copy, so very long errors arrive truncated but safe. For where the failure happened, the companion queries give the retained source position: JobErrorFile, JobErrorLine, and JobErrorFunction. A job that succeeded, was cancelled, or is still running returns an empty string.

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

Requires Extended mode.

See also: JobErrorFile, JobErrorLine, JobErrorFunction, JobState, FreeJob.

Example

; JobError Example
; ----------------
; Requires Extended mode.

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

; This worker fails on purpose while loading a corrupted save file
Worker Function LoadCorruptSave(inputBank)
    SetJobProgress 1L,3L,"Reading save header"
    ; Busy work standing in for real parsing
    For parse=1 To 4000000
        noise#=Sin(parse)
    Next
    SetJobProgress 2L,3L,"Verifying checksum"
    ; The checksum does not match - fail the Job deliberately
    RuntimeError "Save file checksum mismatch"
    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
        ; The failure stays inside the Job - query a bounded summary here
        Color 200,90,90
        Rect 70,190,500,4,True
        Color 255,255,255
        Text 70,210,"The Job failed while: "+JobProgressText(job)
        Text 70,240,"JobError(job) = "+Chr(34)+JobError(job)+Chr(34)
        Text 70,270,"The main thread keeps running - the error never becomes a crash"
    Else
        Text 70,210,"Still loading..."
    EndIf

    Flip

Wend

FreeJob job
End

Index