TakeJobResult ( job )

Parameters

job - a Job handle returned by StartJob, in the JOB_SUCCEEDED state

Description

Transfers a succeeded job's result Bank to the main program.

This is the hand-over at the end of a job's life: the Bank the Worker Function returned becomes an ordinary main-thread Bank that you own. Read it, build entities and resources from it, and release it with FreeBank when done. The Bank stays valid after FreeJob - taking the result and freeing the job are independent steps.

Ownership transfers exactly once. Calling TakeJobResult a second time on the same job is a runtime error ("result was already taken"), so take it, keep the Bank handle, and pass that around instead. Calling it on a job that has not succeeded - still running, failed, or cancelled - is also a runtime error; check JobState (or that PollJob handed you the completion) first.

You are never forced to take a result: for a stale completion (see JobTag), just call FreeJob and the unclaimed result is discarded cleanly.

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

Requires Extended mode.

See also: StartJob, JobState, PollJob, JobTag, FreeJob, FreeBank.

Example

; TakeJobResult Example
; ---------------------
; Requires Extended mode.

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

; The worker carves a dungeon and serializes the results into a Bank
Worker Function CarveDungeon(inputBank)
    rooms=PeekInt(inputBank,0)
    treasure=0
    monsters=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
        If (room Mod 4)=0 Then treasure=treasure+1
        If (room Mod 3)=0 Then monsters=monsters+1
        SetJobProgress room,rooms,"Carving room "+room
    Next
    outputBank=CreateBank(12)
    PokeInt outputBank,0,rooms
    PokeInt outputBank,4,treasure
    PokeInt outputBank,8,monsters
    Return outputBank
End Function

inputBank=CreateBank(4)
PokeInt inputBank,0,30
job=StartJob(CarveDungeon,inputBank,1L)
FreeBank inputBank

resultText$=""

While Not KeyDown(1)

    Cls

    ; TakeJobResult may be called exactly once, so guard with a flag
    If JobState(job)=JOB_SUCCEEDED And resultText=""
        ; Transfer the worker's Bank to the main thread
        resultBank=TakeJobResult(job)
        resultText="Rooms "+PeekInt(resultBank,0)+", treasure chests "+PeekInt(resultBank,4)+", monsters "+PeekInt(resultBank,8)
        ; The transferred Bank is ours now and must be freed normally
        FreeBank resultBank
    EndIf

    ; Draw the loading bar
    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,"Esc: exit"
    Text 70,190,"Generating dungeon on a worker thread..."
    If resultText="" Then Text 70,254,JobProgressText(job) Else Text 70,254,"TakeJobResult(job) delivered: "+resultText

    Flip

Wend

FreeJob job
End

Index

Blitz3D+ Command Reference

TakeJobResult ( job )

Parameters

Description

Example