JobCancelled ( )

Parameters

None.

Description

Inside a Worker Function, returns True once cancellation has been requested for this job.

This command runs on the worker side only - the compiler rejects a call from ordinary main-thread code as a compile error. Most workers never need it: the compiler already plants automatic cancellation safe points at every Worker Function entry and loop backedge, so a normal loop-shaped algorithm reacts to CancelJob by itself. Reach for JobCancelled inside a long indivisible step - a big single computation between loop iterations - to bail out gracefully rather than finishing work nobody wants.

When it returns True, wrap up quickly and Return any valid Bank (an empty CreateBank() will do): the job still ends JOB_CANCELLED and the returned result is discarded, so there is no point polishing it. There is no way to "un-cancel" - once requested, it stays requested.

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

Requires Extended mode.

See also: CancelJob, SetJobProgress, StartJob, JobState.

Example

; JobCancelled Example
; --------------------
; Requires Extended mode.

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

; The worker maps a huge cavern system, checking for cancellation as it goes
Worker Function MapCaverns(inputBank)
    chambers=PeekInt(inputBank,0)
    For chamber=1 To chambers
        ; JobCancelled is worker-only: take a graceful early exit when asked.
        ; Automatic safe points would also stop us, but this branch lets an
        ; algorithm tidy up on its own terms first.
        If JobCancelled() Then Return 0
        ; Busy mapping loop standing in for real exploration work
        For survey=1 To 500000
            noise#=Sin(survey)*Sqr(survey)
        Next
        SetJobProgress chamber,chambers,"Mapping chamber "+chamber
    Next
    Return CreateBank()
End Function

inputBank=CreateBank(4)
PokeInt inputBank,0,200
job=StartJob(MapCaverns,inputBank,1L)
FreeBank inputBank

While Not KeyDown(1)

    Cls

    ; Space requests cancellation, which the worker observes via JobCancelled
    If KeyHit(57) Then CancelJob job

    state=JobState(job)
    stateName$="JOB_RUNNING"
    If state=JOB_QUEUED Then stateName="JOB_QUEUED"
    If state=JOB_SUCCEEDED Then stateName="JOB_SUCCEEDED"
    If state=JOB_CANCELLED Then stateName="JOB_CANCELLED"

    ; Draw the loading bar - it freezes where the worker bailed out
    progress=JobProgress(job)
    Color 60,60,80
    Rect 70,220,500,24,True
    Color 90,200,120
    If state=JOB_CANCELLED Then Color 200,90,90
    Rect 70,220,progress*500/1000,24,True
    Color 255,255,255
    Rect 70,220,500,24,False

    Text 0,0,"Space: cancel the survey   Esc: exit"
    Text 70,190,"Mapping 200 cavern chambers on a worker thread"
    Text 70,254,"State: "+stateName+"   "+JobProgressText(job)
    If state=JOB_CANCELLED Then Text 70,274,"The worker saw JobCancelled()=True and returned early"

    Flip

Wend

FreeJob job
End

Index

Blitz3D+ Command Reference

JobCancelled ( )

Parameters

Description

Example