StartJob ( worker_function[,input_bank][,tag:Long] )
Parameters
|
worker_function - the name of a Worker Function, written directly. The compiler resolves it - it is not a string or a function pointer - and it must accept one Bank parameter and return a Bank. input_bank (optional) - Bank whose bytes become the job's input; 0 gives the worker a valid empty input Bank (default) tag:Long (optional) - application-owned Long stored with the job and read back with JobTag; 0 (default) |
Description
|
Queues a Worker Function to run on the background worker and returns a Job handle at once. This is how a game does heavy work - parsing level data, pathfinding, procedural generation, hashing a save file - without freezing the frame: the worker runs off the main thread while your loop keeps updating, rendering, and taking input. Poll for completion with PollJob or JobFinished, then collect the output. Bank ownership is exact and worth memorising. StartJob copies the input Bank's bytes before it returns, so the moment it returns you may change, resize, or free your Bank - the job cannot see any of it. The worker receives its own immutable private input Bank, which it must never free or return. The worker creates a new Bank for its result and returns it, without freeing it; the main program later claims that result exactly once with TakeJobResult and frees the claimed Bank itself. Returning 0, returning the input Bank, or returning a freed Bank fails the job. Worker code is isolated: no main globals, no engine, world, entity, graphics, audio, input, GUI, sockets, or writable files, and notably no Delay or MilliSecs - only the worker-safe subset of commands, which the Jobs and Worker Functions language reference lists precisely. The compiler enforces this, so mistakes are compile errors rather than crashes. Input Banks are capped at 64 MB (a runtime error here) and results at 256 MB (the job fails). Free every job with FreeJob once you have collected, rejected, or cancelled it - handles are a finite resource. For the full story, see the Using Background Jobs guide. Requires Extended mode. See also: TakeJobResult, PollJob, JobState, JobTag, CancelJob, FreeJob. |
Example
; StartJob 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) treasure=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 SetJobProgress room,rooms,"Carving room "+room Next outputBank=CreateBank(8) PokeInt outputBank,0,rooms PokeInt outputBank,4,treasure Return outputBank End Function ; Pack the request into a Bank - StartJob copies it, so it can be freed at once inputBank=CreateBank(4) PokeInt inputBank,0,30 job=StartJob(CarveDungeon,inputBank,1L) FreeBank inputBank resultText$="" While Not KeyDown(1) Cls ; Press Space for a fresh dungeon once the current one is done If KeyHit(57) And JobFinished(job) FreeJob job inputBank=CreateBank(4) PokeInt inputBank,0,30 ; Queue the Worker Function again with a new input Bank job=StartJob(CarveDungeon,inputBank,1L) FreeBank inputBank resultText="" EndIf ; Collect the result Bank once the job succeeds If JobState(job)=JOB_SUCCEEDED And resultText="" resultBank=TakeJobResult(job) resultText="Dungeon ready: "+PeekInt(resultBank,0)+" rooms, "+PeekInt(resultBank,4)+" treasure chests" FreeBank resultBank EndIf ; Draw a loading bar while the worker digs 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: start a new dungeon job Esc: exit" Text 70,190,"StartJob(CarveDungeon,inputBank,1L) queued the worker" Text 70,254,JobProgressText(job) If resultText<>"" Then Text 70,274,resultText Flip Wend FreeJob job End
Index