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

Channel

Channel properties are

size

int

isEmpty

bool

isReady

bool

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

JobStatus

JobStatus properties are

isReady

bool

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

17.2. Channel and JobStatus

append(channel: jobque::Channel? const implicit; size: int const)

append returns int

argument

argument type

channel

jobque::Channel ? 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: jobque::Channel? const implicit)

Warning

This is unsafe operation.

argument

argument type

channel

jobque::Channel ? const implicit

Destroys channel.

add_ref(channel: jobque::Channel? const implicit)

argument

argument type

channel

jobque::Channel ? const implicit

Increase reference count of the job status or channel.

release(channel: jobque::Channel?& implicit)

argument

argument type

channel

jobque::Channel ?& implicit

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

join(channel: jobque::Channel? const implicit)

argument

argument type

channel

jobque::Channel ? const implicit

Wait until channel entry count reaches 0.

notify(channel: jobque::Channel? const implicit)

argument

argument type

channel

jobque::Channel ? const implicit

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

notify_and_release(channel: jobque::Channel?& implicit)

argument

argument type

channel

jobque::Channel ?& 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.

add_ref(status: jobque::JobStatus? const implicit)

argument

argument type

status

jobque::JobStatus ? const implicit

Increase reference count of the job status or channel.

release(status: jobque::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: jobque::JobStatus? const implicit)

argument

argument type

job

jobque::JobStatus ? const implicit

Wait until channel entry count reaches 0.

notify(job: jobque::JobStatus? const implicit)

argument

argument type

job

jobque::JobStatus ? const implicit

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

notify_and_release(job: jobque::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.

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.

17.5. Construction

with_channel(block: block<(var arg0:jobque::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:jobque::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:jobque::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.