Blitz3D+ Command Reference

PollJob ( )

Parameters

None.

Description

Returns the handle of one finished job, or 0 when there is nothing to collect.

This is the game-loop way to collect background work: call it once (or in a small While loop) per frame, and it hands you the oldest completion - a job that succeeded, failed, or was cancelled - without ever blocking. Route on JobState: take the result on JOB_SUCCEEDED, log JobError on JOB_FAILED, then FreeJob in every case.

Each finished job produces exactly one completion notification, and PollJob consumes it - poll the same completion twice and the second call returns 0 or a different job. Consuming the notification does not free the job or transfer its result; TakeJobResult and FreeJob are still your responsibility. JobFinished, by contrast, inspects one known job without consuming anything, so both patterns can coexist.

Do not assume completions arrive in the order you started the jobs.

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

Requires Extended mode.

See also: WaitAnyJob, WaitJob, JobFinished, JobState, TakeJobResult, FreeJob.

Example

; PollJob Example
; ---------------
; Requires Extended mode.

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

; The worker carves one dungeon chunk on a background thread
Worker Function CarveChunk(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,"Room "+room
    Next
    Return CreateBank()
End Function

; Start three chunks of different sizes so they finish at different times
Dim jobs(2)
Dim chunkName$(2)
For chunk=0 To 2
    chunkName(chunk)="Chunk "+(chunk+1)
    inputBank=CreateBank(4)
    PokeInt inputBank,0,10+chunk*10
    jobs(chunk)=StartJob(CarveChunk,inputBank,chunk+1)
    FreeBank inputBank
Next

logText$=""

While Not KeyDown(1)

    Cls

    ; PollJob consumes the oldest terminal notification, or returns zero
    completed=PollJob()
    While completed<>0
        For chunk=0 To 2
            If jobs(chunk)=completed Then logText=logText+chunkName(chunk)+" "
        Next
        completed=PollJob()
    Wend

    ; Draw one progress bar per chunk
    For chunk=0 To 2
        progress=JobProgress(jobs(chunk))
        Color 60,60,80
        Rect 70,180+chunk*50,400,20,True
        Color 90,200,120
        Rect 70,180+chunk*50,progress*400/1000,20,True
        Color 255,255,255
        Rect 70,180+chunk*50,400,20,False
        Text 480,182+chunk*50,chunkName(chunk)
    Next

    Text 0,0,"Esc: exit"
    Text 70,150,"Three dungeon chunks generating in the background"
    Text 70,340,"PollJob completion order: "+logText

    Flip

Wend

For chunk=0 To 2
    FreeJob jobs(chunk)
Next
End

Index