12.12 control.thread-pool - Thread pools

Module: control.thread-pool ¶

Provides thread pools. Only available when Gauche is compiled with pthreads support.

Class: <thread-pool> ¶

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

Condition type: <thread-pool-shut-down> ¶

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

Instance Variable of <thread-pool-shut-down>: pool ¶

The thread pool object that caused the condition.

Function: make-thread-pool size :key (max-backlog 0) ¶

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

Function: thread-pool-results pool ¶

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

Function: thread-pool-shut-down? pool ¶

{control.thread-pool} Returns #t if the thread pool is shut down and no longer accepting new jobs, or #f otherwise.

Function: add-job! pool thunk :optional (need-result #f) (timeout #f) ¶

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

Function: wait-all pool :optional (timeout #f) (check-interval #e5e8) ¶

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

Function: terminate-all! pool :key (force-timeout #f) (cancel-queued-jobs #f) ¶

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