control.thread-pool - Thread pools ¶Provides thread pools.
{control.thread-pool}
A class for thread pool objects. It maintains a set of worker threads, and
let them work on the jobs you ask to do asynchronously.
Currently the size of pool (number of threads) is fixed and you have to specify it when creating a pool. In future we might add a feature to grow or shrink the pool.
You can also set maximum backlog of the job queue. You cannot
put a job when the queue already reaches the max length (see
add-job! below).
{control.thread-pool}
A condition indicating that a thread pool is already shut down
by terminate-all! and no longer accepting new jobs.
Inherits <error>. The following slot is provided.
<thread-pool-shut-down>: pool ¶The thread pool object that caused the condition.
{control.thread-pool}
Creates a new thread pool of size size (the number of
worker threads). Optionally you can give a nonnegative integer
to the maximum backlog; 0 means unlimited.
{control.thread-pool}
When you put a job to a thread pool, you can specify
whether you need to check its result or not. If you say you need
a result, the terminated job is queued to a result queue,
an <mt-queue> object, in the pool.
This procedure returns the pool’s result queue.
See data.queue - Queue, for the details of <mt-queue>.
{control.thread-pool}
Returns #t if the thread pool is shut down and no longer
accepting new jobs, or #f otherwise.
{control.thread-pool}
Add a thunk to be executed in the thread pool pool.
Returns a job record (see control.job - A common job descriptor for control modules).
The returned job record is not waitable; if you need to track
its result, you have to give a true value to need-result
argument. Then when the job is terminated (either normally or
abnormally) the job is queued to the result-queue of
the pool, and you can check the queue. If you don’t pass
a true value to need-result, the job won’t be queued
to result-queue even it is terminated.
The returned job is timestamped. You can examine acknowledged
time, start time and finish time of the job (if the job hasn’t
been started and/or finished, the corresponding timestamp fields
are #f.) It’s sometimes
handy to find out how long the job was waiting in the
queue and how long it took to run.
If the pool has positive max-backlog value, and it
already has that many jobs to be waiting, then add-job!
blocks until some jobs are start being executed.
You can give a real number in seconds, or a <time> object
as an absolute point of time, to the timeout argument
to set the time limit of blocking. If timeout is reached,
add-job! returns #f without creating any job.
Omitting timeout
or giving #f to it sets no timeout.
(Note: This behavior is different from 0.9.1, in which add-job!
didn’t take the timeout argument and always behaved as if zero
timeout value was given. To achieve the same behavior, you have
to give 0 to the timeout argument explicitly.)
If the thread pool is shut down, this procedure
raises <thread-pool-shut-down> condition.
{control.thread-pool}
Wait for the job queue to be empty and
all worker threads to finish. It is done by polling the
pool’s status in every check-interval nanoseconds.
Returns #t if all jobs are finished.
You can give a real number in seconds, or a <time> object
as an absolute point of time, in timeout optional argument.
When timeout is reached, wait-all returns #f.
While this procedure is called, no new jobs should be put into pool.
{control.thread-pool}
Wait for all the queued jobs to be finished, then ask all threads
to terminate. After calling this procedure, the pool no longer
accepts new jobs. Calling add-job! on this module would
raise a <thread-pool-shut-down> condition.
This is intended to be called when shutting down the application.
By default, this procedure first waits for all queued jobs to be handled, then tries to terminate threads gracefully.
Giving a true value to the cancel-queued-jobs argument
immediately cancels queued but not started jobs; the status
of such jobs is set killed.
It does not cancels already started jobs, though.
If you want to cancel already started jobs,
you can give a timeout value (either <time> object to
specify absolute point of time, or a real number indicating
relative time in seconds) to the force-timeout argument.
Once timeout is reached, it forcefully terminates the threads
and the jobs handled at that time are also killed.
Forcing termination of threads is an extreme measure; the terminated thread may not have a chance to clean up properly. So it is usually better to give some time for the thread to finish the executing jobs.