| job - a Job handle returned by StartJob |
|
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. |
; 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