JobState ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns a job's current state as one of the JOB_* constants.

The possible states are:
JOB_QUEUED (1): accepted, waiting for the background worker
JOB_RUNNING (2): the Worker Function is executing
JOB_SUCCEEDED (3): finished and its result Bank is waiting for TakeJobResult
JOB_FAILED (4): a runtime error occurred in the worker - see JobError
JOB_CANCELLED (5): cancellation completed; there is no result

Use the named constants in your code; the numbers are documented for logs and tools. The last three states are terminal and never change once reached, so after PollJob hands you a completion a Select on JobState routes it cleanly: take the result on JOB_SUCCEEDED, read the diagnostics on JOB_FAILED, and simply free on JOB_CANCELLED.

TakeJobResult only works in JOB_SUCCEEDED - anything else is a runtime error - which is exactly why the state check comes first.

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

Requires Extended mode.

See also: JobFinished, PollJob, TakeJobResult, JobError, CancelJob, FreeJob.

Example

; JobState 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

    ; Space restarts the job, C cancels it - watch the state change
    If KeyHit(57) And JobFinished(job)
        FreeJob job
        inputBank=CreateBank(4)
        PokeInt inputBank,0,30
        job=StartJob(CarveDungeon,inputBank,1L)
        FreeBank inputBank
    EndIf
    If KeyHit(46) Then CancelJob job

    ; JobState returns one of the five built-in JOB_ constants
    state=JobState(job)
    stateName$="UNKNOWN"
    If state=JOB_QUEUED Then stateName="JOB_QUEUED"
    If state=JOB_RUNNING Then stateName="JOB_RUNNING"
    If state=JOB_SUCCEEDED Then stateName="JOB_SUCCEEDED"
    If state=JOB_FAILED Then stateName="JOB_FAILED"
    If state=JOB_CANCELLED Then stateName="JOB_CANCELLED"

    ; Draw the loading bar so the state has context
    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,"Space: restart when finished   C: cancel   Esc: exit"
    Text 70,190,"Generating dungeon on a worker thread..."
    Text 70,254,"JobState(job) = "+state+" ("+stateName+")"
    If JobFinished(job) Then Text 70,274,"Terminal states never change"

    Flip

Wend

FreeJob job
End

Index

Blitz3D+ Command Reference

JobState ( job )

Parameters

Description

Example