17. Jobs and threads

Apply module implements job que and threading.

All functions and symbols are in “jobque” module, use require to get access to it.

require jobque

17.1. Handled structures

JobStatus

JobStatus property operators are

isReady

bool

isValid

bool

size

int

Job status indicator (ready or not, as well as entry count).

Channel

Channel property operators are

isEmpty

bool

total

int

Channel provides a way to communicate between multiple contexts, including threads and jobs. Channel has internal entry count.

LockBox

Lockbox. Similar to channel, only for single object.

Atomic32

Atomic 32 bit integer.

Atomic64

Atomic 64 bit integer.

17.2. Channel, JobStatus, Lockbox

lock_box_create()

lock_box_create returns jobque::LockBox ?

Creates lockbox.

lock_box_remove(box: LockBox?& implicit)

Warning

This is unsafe operation.

argument

argument type

box

jobque::LockBox ?& implicit

Destroys lockbox.

append(channel: JobStatus? const implicit; size: int const)

append returns int

argument

argument type

channel

jobque::JobStatus ? const implicit

size

int const

Increase entry count to the channel.

channel_create()

channel_create returns jobque::Channel ?

Warning

This is unsafe operation.

Creates channel.

channel_remove(channel: Channel?& implicit)

Warning

This is unsafe operation.

argument

argument type

channel

jobque::Channel ?& implicit

Destroys channel.

add_ref(status: JobStatus? const implicit)

argument

argument type

status

jobque::JobStatus ? const implicit

Increase reference count of the job status or channel.

release(status: JobStatus?& implicit)

argument

argument type

status

jobque::JobStatus ?& implicit

Decrease reference count of the job status or channel. Object is delete when reference count reaches 0.

join(job: JobStatus? const implicit)

argument

argument type

job

jobque::JobStatus ? const implicit

Wait until channel entry count reaches 0.

notify(job: JobStatus? const implicit)

argument

argument type

job

jobque::JobStatus ? const implicit

Notify channel that entry is completed (decrease entry count).

notify_and_release(job: JobStatus?& implicit)

argument

argument type

job

jobque::JobStatus ?& implicit

Notify channel or job status that entry is completed (decrease entry count) and decrease reference count of the job status or channel. Object is delete when reference count reaches 0.

job_status_create()

job_status_create returns jobque::JobStatus ?

Creates job status.

job_status_remove(jobStatus: JobStatus?& implicit)

Warning

This is unsafe operation.

argument

argument type

jobStatus

jobque::JobStatus ?& implicit

Destroys job status.

17.3. Queries

get_total_hw_jobs()

get_total_hw_jobs returns int

Total number of hardware threads supporting job system.

get_total_hw_threads()

get_total_hw_threads returns int

Total number of hardware threads available.

is_job_que_shutting_down()

is_job_que_shutting_down returns bool

Returns true if job que infrastructure is shut-down or not initialized. This is useful for debug contexts, since it allows to check if job que is still alive.

17.4. Internal invocations

new_job_invoke(lambda: lambda<> const; function: function<> const; lambdaSize: int const)

argument

argument type

lambda

lambda<> const

function

function<> const

lambdaSize

int const

Creates clone of the current context, moves attached lambda to it. Adds a job to a job que, which once invoked will execute the lambda on the context clone. new_job_invoke is part of the low level (internal) job infrastructure. Recommended approach is to use jobque_boost::new_job.

new_thread_invoke(lambda: lambda<> const; function: function<> const; lambdaSize: int const)

argument

argument type

lambda

lambda<> const

function

function<> const

lambdaSize

int const

Creates clone of the current context, moves attached lambda to it. Creates a thread, invokes the lambda on the new context in that thread. new_thread_invoke is part of the low level (internal) thread infrastructure. Recommended approach is to use jobque_boost::new_thread.

new_debugger_thread(block: block<> const implicit)

argument

argument type

block

block<> const implicit

Creates a new thread for debugging purposes (tick thread).

17.5. Construction

with_lock_box(block: block<(var arg0:LockBox?):void> const implicit)

argument

argument type

block

block<( jobque::LockBox ?):void> const implicit

Creates LockBox, makes it available inside the scope of the block.

with_channel(block: block<(var arg0:Channel?):void> const implicit)

argument

argument type

block

block<( jobque::Channel ?):void> const implicit

Creates Channel, makes it available inside the scope of the block.

with_channel(count: int const; block: block<(var arg0:Channel?):void> const implicit)

argument

argument type

count

int const

block

block<( jobque::Channel ?):void> const implicit

Creates Channel, makes it available inside the scope of the block.

with_job_status(total: int const; block: block<(var arg0:JobStatus?):void> const implicit)

argument

argument type

total

int const

block

block<( jobque::JobStatus ?):void> const implicit

Creates JobStatus, makes it available inside the scope of the block.

with_job_que(block: block<void> const implicit)

argument

argument type

block

block<> const implicit

Makes sure jobque infrastructure is available inside the scope of the block. There is cost associated with creating such infrastructure (i.e. creating hardware threads, jobs, etc). If jobs are integral part of the application, with_job_que should be high in the call stack. If it`s a one-off - it should be encricled accordingly to reduce runtime memory footprint of the application.

17.6. Atomic

atomic32_create()

atomic32_create returns jobque::Atomic32 ?

Creates atomic 32 bit integer.

atomic32_remove(atomic: Atomic32?& implicit)

Warning

This is unsafe operation.

argument

argument type

atomic

jobque::Atomic32 ?& implicit

Destroys atomic 32 bit integer.

with_atomic32(block: block<(var arg0:Atomic32?):void> const implicit)

argument

argument type

block

block<( jobque::Atomic32 ?):void> const implicit

Creates Atomic32, makes it available inside the scope of the block.

set(atomic: Atomic32? const implicit; value: int const)

argument

argument type

atomic

jobque::Atomic32 ? const implicit

value

int const

Set atomic integer value.

get(atomic: Atomic32? const implicit)

get returns int

argument

argument type

atomic

jobque::Atomic32 ? const implicit

Get atomic integer value.

inc(atomic: Atomic32? const implicit)

inc returns int

argument

argument type

atomic

jobque::Atomic32 ? const implicit

Increase atomic integer value and returns result.

dec(atomic: Atomic32? const implicit)

dec returns int

argument

argument type

atomic

jobque::Atomic32 ? const implicit

Decrease atomic integer value and returns result.

atomic64_create()

atomic64_create returns jobque::Atomic64 ?

Creates atomic 64 bit integer.

atomic64_remove(atomic: Atomic64?& implicit)

Warning

This is unsafe operation.

argument

argument type

atomic

jobque::Atomic64 ?& implicit

Destroys atomic 64 bit integer.

with_atomic64(block: block<(var arg0:Atomic64?):void> const implicit)

argument

argument type

block

block<( jobque::Atomic64 ?):void> const implicit

Creates Atomic64, makes it available inside the scope of the block.

set(atomic: Atomic64? const implicit; value: int64 const)

argument

argument type

atomic

jobque::Atomic64 ? const implicit

value

int64 const

Set atomic integer value.

get(atomic: Atomic64? const implicit)

get returns int64

argument

argument type

atomic

jobque::Atomic64 ? const implicit

Get atomic integer value.

inc(atomic: Atomic64? const implicit)

inc returns int64

argument

argument type

atomic

jobque::Atomic64 ? const implicit

Increase atomic integer value and returns result.

dec(atomic: Atomic64? const implicit)

dec returns int64

argument

argument type

atomic

jobque::Atomic64 ? const implicit

Decrease atomic integer value and returns result.