Blitz3D+ Command Reference

WaitAnyJob ( [timeout_ms] )

Parameters

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

Description

Waits until any job finishes and returns its handle, or 0 on timeout.

This is the blocking sibling of PollJob: it sleeps until some job reaches a terminal state - succeeded, failed, or cancelled - then consumes that completion notification and hands you the handle. A batch tool that fires off several jobs can sit in a WaitAnyJob loop, processing each completion as it lands, without burning CPU on a spin loop. A timeout below -1 is a runtime error.

Like WaitJob, the wait is a plain block: no rendering, no Flip, no GUI events, no callbacks. Games should poll with PollJob instead and keep drawing frames.

The returned handle still needs the usual aftercare: check JobState, TakeJobResult if it succeeded and you still want it, then FreeJob.

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

Requires Extended mode.

See also: PollJob, WaitJob, JobState, TakeJobResult, FreeJob.

Example

; WaitAnyJob Example
; ------------------
; Requires Extended mode.

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

; The worker hashes one save slot to fingerprint it
Worker Function HashSlot(inputBank)
    passes=PeekInt(inputBank,0)
    digest$="SAVE SLOT DATA"
    For pass=1 To passes
        digest=Sha256Text(digest)
    Next
    Return Sha256TextBytes(digest)
End Function

; Hash three save slots of different sizes at the same time
Dim jobs(2)
Dim slotName$(2)
For slot=0 To 2
    slotName(slot)="Slot "+(slot+1)
    inputBank=CreateBank(4)
    PokeInt inputBank,0,150000+slot*150000
    jobs(slot)=StartJob(HashSlot,inputBank,slot+1)
    FreeBank inputBank
Next

; Show one frame before blocking so the window is visible while we wait
Cls
Text 70,220,"Verifying three save slots on worker threads..."
Flip

; Collect the three completions in whatever order they finish
orderText$=""
For collect=1 To 3
    ; WaitAnyJob blocks until one Job becomes terminal and consumes its notification
    completed=WaitAnyJob(15000)
    If completed=0 Then RuntimeError "Timed out waiting for the save slots"
    For slot=0 To 2
        If jobs(slot)=completed Then orderText=orderText+slotName(slot)+"  "
    Next

    ; Show the completion order so far
    Cls
    Text 70,190,"Verifying three save slots on worker threads..."
    Text 70,220,"WaitAnyJob completion order: "+orderText
    Flip
Next

For slot=0 To 2
    FreeJob jobs(slot)
Next

While Not KeyDown(1)

    Cls

    Text 0,0,"Esc: exit"
    Text 70,190,"All save slots verified"
    Text 70,220,"WaitAnyJob completion order: "+orderText
    Text 70,250,"Smaller slots finish first - each call consumed one notification"

    Flip

Wend

End

Index