Blitz3D+ Command Reference

SetJobProgress done:Long,total:Long[,stage$]

Parameters

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)

Description

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.

Example

; 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

Index