Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


THREADPOOL(9)              Kernel Developer's Manual             THREADPOOL(9)

NAME
     threadpool - shared pools of kthreads

SYNOPSIS
     #include <sys/threadpool.h>

     typedef void threadpool_job_fn_t(struct threadpool_job *);

     int
     threadpool_get(struct threadpool **poolp, pri_t pri);

     void
     threadpool_put(struct threadpool *pool, pri_t pri);

     int
     threadpool_percpu_get(struct threadpool_percpu **pool_percpup,
         pri_t pri);

     void
     threadpool_percpu_put(struct threadpool_percpu *pool_percpu, pri_t pri);

     struct threadpool *
     threadpool_percpu_ref(struct threadpool_percpu *pool);

     struct threadpool *
     threadpool_percpu_ref_remote(struct threadpool_percpu *pool,
         struct cpu_info *ci);

     void
     threadpool_job_init(struct threadpool_job *job, threadpool_job_fn_t fn,
         kmutex_t *interlock, const char *fmt, ...);

     void
     threadpool_job_destroy(struct threadpool_job *job);

     void
     threadpool_job_done(struct threadpool_job *job);

     void
     threadpool_schedule_job(struct threadpool *pool,
         struct threadpool_job *job);

     void
     threadpool_cancel_job(struct threadpool *pool,
         struct threadpool_job *job);

     bool
     threadpool_cancel_job_async(struct threadpool *pool,
         struct threadpool_job *job);

DESCRIPTION
     The threadpool abstraction is provided to share a pool of kthread(9)
     kernel threads for medium- to long-term actions, called jobs, which can
     be scheduled from contexts that do not allow sleeping.

     For each priority level, there is one unbound thread pool, and one
     collection of per-CPU thread pools.  Access to the unbound thread pools
     is provided by threadpool_get() and threadpool_put().  Access to the per-
     CPU thread pools is provided by threadpool_percpu_get() and
     threadpool_percpu_put().

     Job state is stored in the threadpool_job structure.  Callers of the
     threadpool abstraction must allocate memory for threadpool_job
     structures, but should consider them opaque, and should not inspect or
     copy them.  Each job represented by a threadpool_job structure will be
     run only once at a time, until the action associated with it calls
     threadpool_job_done().

     Jobs are run in thread context and may take arbitrarily long to run or
     sleep arbitrarily long.

FUNCTIONS
     threadpool_get(poolp, pri)
           Obtain a reference to the unbound thread pool at priority pri and
           store it in poolp.

           May sleep.

     threadpool_put(pool, pri)
           Release the reference to the unbound thread pool pool at priority
           pri, which must be the same as the priority that was passed to
           threadpool_get() to obtain pool.

           May sleep.

           Do not use threadpool_put() with thread pools obtained from
           threadpool_percpu_ref() or threadpool_percpu_ref_remote().

     threadpool_percpu_get(pool_percpup, pri)
           Obtain a reference to the per-CPU thread pool at priority pri and
           store it in pool_percpup.

           Use threadpool_percpu_ref() or threadpool_percpu_ref_remote() with
           it to get at the thread pool for a particular CPU.

           May sleep.

     threadpool_percpu_put(pool_percpu, pri)
           Release a reference to the per-CPU thread pool pool_percpu at
           priority pri.

           May sleep.

     threadpool_percpu_ref(pool_percpu)
           Return the thread pool in pool_percpu for the current CPU.

           The resulting thread pool pointer is stable until pool_percpu is
           released with threadpool_percpu_put().  Using it to schedule or
           cancel a job does not require being on the same CPU.

           Do not use threadpool_put() with thread pools obtained from
           threadpool_percpu_ref().

     threadpool_percpu_ref_remote(pool_percpu, ci)
           Return the thread pool in pool_percpu for the CPU whose struct
           cpu_info is given by ci.

           The resulting thread pool pointer is stable until pool_percpu is
           released with threadpool_percpu_put().  Using it to schedule or
           cancel a job does not require being on the same CPU, but it is
           faster and friendlier to the cache to use threadpool_percpu_ref()
           and use the resulting thread pool only on the same CPU.

           Do not use threadpool_put() with thread pools obtained from
           threadpool_percpu_ref_remote().

     threadpool_job_init(job, fn, interlock, fmt, ...)
           Initialize the threadpool job job to run fn when scheduled and to
           interlock with interlock.  The argument fmt is a printf(9) format
           string for the job's name.

           The mutex interlock is used to synchronize job scheduling and
           completion.  The action fn is required to eventually call
           threadpool_job_done(), with interlock held.  This is so that while
           the job is running and may be waiting for work to do, scheduling
           the job has no effect, but as soon as the job is done, scheduling
           the job will cause it to run again.

           To change the action of a job, you must use
           threadpool_job_destroy() first and then call threadpool_job_init()
           again.

     threadpool_job_destroy(job)
           Destroy the threadpool job job.  job must not currently be
           scheduled to run.  If it may still be scheduled, you can use
           threadpool_cancel_job() to cancel it.  However,
           threadpool_cancel_job_async() is not enough.

     threadpool_job_done(job)
           Notify that job is done, so that subsequent calls to
           threadpool_schedule_job() will cause it to re-run its action.

           threadpool_job_done() must be called exactly once by a job's
           action, and may not be called in any other context.

     threadpool_schedule_job(pool, job)
           Schedule job to run in a thread in pool as soon as possible,
           creating a new thread if necessary.

           Caller must hold the interlock of job.

           threadpool_schedule_job() may be called in any context, including
           hard interrupt context, except at interrupt priority levels above
           IPL_VM.

     threadpool_cancel_job(pool, job)
           Cancel job if it has been scheduled but has not yet been assigned a
           thread, or wait for it to complete if it has.

           Caller must hold the interlock of job, which may be released in
           order to wait for completion.

           If job has not been scheduled, threadpool_cancel_job() returns
           immediately.  If job has been scheduled, it must have been
           scheduled in pool, not in any other thread pool.

           May sleep.

     threadpool_cancel_job_async(pool, job)
           Try to cancel job like threadpool_cancel_job(), but if it is
           already running, return false instead of waiting; otherwise, if it
           was not scheduled, or if it was scheduled and has not yet begun to
           run, return true.

           Caller must hold the interlock of job.

           threadpool_cancel_job_async() may be called in any context,
           including hard interrupt context, except at interrupt priority
           levels above IPL_VM.

CODE REFERENCES
     The threadpool abstraction is implemented in sys/kern/kern_threadpool.c.

SEE ALSO
     kthread(9), workqueue(9)

NetBSD 10.99                   December 26, 2018                  NetBSD 10.99