Blitz3D+ Command Reference

JobTag:Long ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns the Long tag you gave the job when you started it.

The tag exists for one classic problem: stale results. An editor rebuilds a preview every time the user tweaks a slider; each tweak starts a new job, but an older, slower job may finish after a newer one. Pass a revision number as the tag when you StartJob, and when a completion arrives compare JobTag against the current revision - if they differ, the result is out of date, so skip TakeJobResult and just FreeJob it (the unclaimed result is discarded).

Tags are entirely yours: a revision, a generation counter, a request sequence, an entity key - any signed Long. The Job system stores the value unchanged and never looks at it; tags have no effect on scheduling.

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

Requires Extended mode.

See also: StartJob, PollJob, TakeJobResult, FreeJob.

Example

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

; Each request carries the revision it was queued for as its tag
Global revision:Long=0L
Dim liveJobs(7)
statusText$="Press Space to queue dungeon revisions"

While Not KeyDown(1)

    Cls

    ; Space queues a new revision - older jobs keep running
    If KeyHit(57)
        slot=-1
        For index=0 To 7
            If liveJobs(index)=0 Then slot=index:Exit
        Next
        If slot>=0
            revision=revision+1L
            inputBank=CreateBank(4)
            PokeInt inputBank,0,25
            ; The third argument becomes the Job's permanent tag
            liveJobs(slot)=StartJob(CarveDungeon,inputBank,revision)
            FreeBank inputBank
        EndIf
    EndIf

    ; Apply a completion only if its tag still matches the current revision
    completed=PollJob()
    While completed<>0
        If JobTag(completed)=revision
            statusText="Applied revision "+JobTag(completed)+" (JobTag matches current revision)"
        Else
            statusText="Ignored stale revision "+JobTag(completed)+" (current is "+revision+")"
        EndIf
        For index=0 To 7
            If liveJobs(index)=completed Then liveJobs(index)=0
        Next
        FreeJob completed
        completed=PollJob()
    Wend

    Text 0,0,"Space: queue a new dungeon revision   Esc: exit"
    Text 70,190,"Queue several revisions quickly - only the newest tag is applied"
    Text 70,220,"Current revision: "+revision
    Text 70,250,statusText

    Flip

Wend

For index=0 To 7
    If liveJobs(index)<>0 Then FreeJob liveJobs(index)
Next
End

Index