Blitz3D+ Command Reference

JobProgress ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns a job's normalized progress as a value from 0 through 1000.

This is the number behind a job's loading bar: divide by 10.0 for a percentage. It reflects the worker's latest SetJobProgress snapshot, never moves backwards, stays 0 until the worker publishes something, and is forced to 1000 when the job succeeds - so a bar drawn from it always ends full.

Progress is advisory, published at whatever rhythm the worker chose. Do not use it as the completion test - a worker that never calls SetJobProgress leaves it at 0 right up until success snaps it to 1000. JobFinished, PollJob, and JobState decide when the job is actually done. For the raw numbers and a caption, read JobProgressDone, JobProgressTotal, and JobProgressText.

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

Requires Extended mode.

See also: SetJobProgress, JobProgressDone, JobProgressTotal, JobProgressText, JobFinished.

Example

; JobProgress Example
; -------------------
; Requires Extended mode.

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

; The worker carves a dungeon level on a background thread
Worker Function CarveDungeon(inputBank)
    rooms=PeekInt(inputBank,0)
    For room=1 To rooms
        ; Busy digging loop standing in for real level generation
        For dig=1 To 700000
            noise#=Sin(dig)*Sqr(dig)
        Next
        SetJobProgress room,rooms,"Carving room "+room
    Next
    Return CreateBank()
End Function

inputBank=CreateBank(4)
PokeInt inputBank,0,30
job=StartJob(CarveDungeon,inputBank,1L)
FreeBank inputBank

While Not KeyDown(1)

    Cls

    ; JobProgress returns monotonic normalized progress from 0 to 1000
    progress=JobProgress(job)

    ; Draw the loading bar from the normalized value
    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,"Generating dungeon on a worker thread..."
    Text 70,254,"JobProgress(job) = "+progress+" / 1000"
    If JobFinished(job) Then Text 70,274,"A successful Job always finishes at 1000"

    Flip

Wend

FreeJob job
End

Index