WaitJob ( job[,timeout_ms] )

Parameters

job - a Job handle returned by StartJob

timeout_ms (optional) - how long to wait, in milliseconds:
-1: wait indefinitely (default)
0: just check, never block
positive: wait at most this long

Description

Waits for one job to finish; returns True if it did, False on timeout.

"Finished" means any terminal state - succeeded, failed, or cancelled - so check JobState afterwards before touching the result. A timeout below -1 is a runtime error.

The wait is a plain block: it does not render, Flip, pump GUI events, or run callbacks, so the screen freezes for its duration. That makes it wrong for a game loop - poll with PollJob or JobFinished there - and right for the places where blocking is honest: a headless tool with nothing else to do, or shutdown code draining the last jobs (a bounded timeout keeps even that responsive).

WaitJob does not consume the job's completion notification - PollJob or WaitAnyJob will still report it - and it does not free the job or take its result.

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

Requires Extended mode.

See also: WaitAnyJob, PollJob, JobFinished, JobState, FreeJob.

Example

; WaitJob Example
; ---------------
; Requires Extended mode.

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

; The worker hashes the save file data over and over to fingerprint it
Worker Function HashSave(inputBank)
    passes=PeekInt(inputBank,0)
    digest$="HERO=Aria LEVEL=7 GOLD=852 CHECKPOINT=SkyTemple"
    For pass=1 To passes
        digest=Sha256Text(digest)
    Next
    ; Return the final 32-byte digest as the result Bank
    Return Sha256TextBytes(digest)
End Function

inputBank=CreateBank(4)
PokeInt inputBank,0,300000
job=StartJob(HashSave,inputBank,1L)
FreeBank inputBank

; Show one frame before blocking so the window is visible while we wait
Cls
Text 70,220,"Hashing save file on a worker thread - please wait..."
Flip

; WaitJob blocks until the Job is terminal, or 10 seconds pass
start=MilliSecs()
If Not WaitJob(job,10000) Then RuntimeError "Save hash timed out"
elapsed=MilliSecs()-start

If JobState(job)<>JOB_SUCCEEDED Then RuntimeError JobError(job)
resultBank=TakeJobResult(job)
fingerprint$=Hex(PeekInt(resultBank,0))+Hex(PeekInt(resultBank,4))+Hex(PeekInt(resultBank,8))
FreeBank resultBank
FreeJob job

While Not KeyDown(1)

    Cls

    Text 0,0,"Esc: exit"
    Text 70,190,"WaitJob(job,10000) returned true after "+elapsed+" ms"
    Text 70,220,"Save fingerprint: "+fingerprint
    Text 70,250,"WaitJob does not render or pump events - use PollJob in a game loop"

    Flip

Wend

End

Index

Blitz3D+ Command Reference

WaitJob ( job[,timeout_ms] )

Parameters

Description

Example