17. Jobs and threads

|module-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.

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).

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).

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<(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<(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<(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.