|
done:Long - units of work completed so far; from 0 through total total:Long - total units of work; must be greater than 0 stage$ (optional) - short human-readable stage text, kept to a bounded length; "" (default) |
|
Inside a Worker Function, publishes a progress snapshot for the main thread to read. This command runs on the worker side only - the compiler rejects a call from ordinary main-thread code as a compile error. The snapshot feeds the main-thread queries: JobProgress gets the normalized 0-1000 value (which never moves backwards, even if later snapshots report a smaller fraction), JobProgressDone and JobProgressTotal get your raw numbers, and JobProgressText gets the stage text - enough for a proper loading bar with a caption. Publish at a sensible rhythm: every N items (say, every 64) rather than every inner-loop iteration, since each call takes a lock the main thread also uses. Total must be positive and done must be from 0 through total, or the call is a runtime error - which, inside a worker, fails the job. Progress is advisory. The main thread must not treat 1000 as "finished" - completion is what JobFinished, PollJob, and JobState are for. For the full story, see the Using Background Jobs guide. Requires Extended mode. See also: JobProgress, JobProgressDone, JobProgressTotal, JobProgressText, JobCancelled. |
; SetJobProgress Example
; ----------------------
; Requires Extended mode.
Graphics 640,480,0,2
SetBuffer BackBuffer()
; The worker builds a level in three named stages
Worker Function BuildLevel(inputBank)
For phase=1 To 3
If phase=1 Then stage$="Carving rooms"
If phase=2 Then stage$="Digging corridors"
If phase=3 Then stage$="Hiding treasure"
For toil=1 To 10
; Busy work standing in for real level generation
For dig=1 To 800000
noise#=Sin(dig)
Next
; Publish an advisory done/total/stage snapshot for the main thread
SetJobProgress (phase-1)*10+toil,30L,stage
Next
Next
Return CreateBank()
End Function
job=StartJob(BuildLevel)
While Not KeyDown(1)
Cls
; Read back the snapshots the worker published with SetJobProgress
progress=JobProgress(job)
Color 60,60,80
Rect 70,220,500,24,True
Color 90,200,120
Rect 70,220,progress*500/1000,24,True
Color 255,255,255
Rect 70,220,500,24,False
Text 0,0,"Esc: exit"
Text 70,190,"Worker publishing SetJobProgress done,30L,stage$ snapshots"
Text 70,254,"Done "+JobProgressDone(job)+" of "+JobProgressTotal(job)+" Stage: "+JobProgressText(job)
If JobFinished(job) Then Text 70,274,"Level complete!"
Flip
Wend
FreeJob job
End