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¶
channel_create (context:__context const;line:__lineInfo const) : jobque::Channel?
release (channel:jobque::Channel?& implicit;context:__context const;line:__lineInfo const) : void
join (channel:jobque::Channel? const implicit;context:__context const;line:__lineInfo const) : void
release (status:jobque::JobStatus?& implicit;context:__context const;line:__lineInfo const) : void
join (job:jobque::JobStatus? const implicit;context:__context const;line:__lineInfo const) : void
notify (job:jobque::JobStatus? const implicit;context:__context const;line:__lineInfo const) : void
-
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.