11002ee06b
This is threadpool_job_init(job, fn, interlock, fmt, args...), not just threadpool_job_init(job, fn, interlock).
344 lines
9.3 KiB
Groff
344 lines
9.3 KiB
Groff
.\" $NetBSD: threadpool.9,v 1.4 2020/09/07 01:07:38 riastradh Exp $
|
|
.\"
|
|
.\" Copyright (c) 2014 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Taylor R. Campbell.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd December 26, 2018
|
|
.Dt THREADPOOL 9
|
|
.Os
|
|
.\"
|
|
.Sh NAME
|
|
.Nm threadpool
|
|
.Nd shared pools of kthreads
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.Sh SYNOPSIS
|
|
.In sys/threadpool.h
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.Vt typedef void threadpool_job_fn_t(struct threadpool_job *);
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.Ft int
|
|
.Fn threadpool_get "struct threadpool **poolp" "pri_t pri"
|
|
.\"
|
|
.Ft void
|
|
.Fn threadpool_put "struct threadpool *pool" "pri_t pri"
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.Ft int
|
|
.Fn threadpool_percpu_get "struct threadpool_percpu **pool_percpup" "pri_t pri"
|
|
.\"
|
|
.Ft void
|
|
.Fn threadpool_percpu_put "struct threadpool_percpu *pool_percpu" "pri_t pri"
|
|
.\"
|
|
.Ft struct threadpool *
|
|
.Fn threadpool_percpu_ref "struct threadpool_percpu *pool"
|
|
.\"
|
|
.Ft struct threadpool *
|
|
.Fn threadpool_percpu_ref_remote "struct threadpool_percpu *pool" "struct cpu_info *ci"
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.Ft void
|
|
.Fn threadpool_job_init "struct threadpool_job *job" "threadpool_job_fn_t fn" "kmutex_t *interlock" "const char *fmt" "..."
|
|
.\"
|
|
.Ft void
|
|
.Fn threadpool_job_destroy "struct threadpool_job *job"
|
|
.\"
|
|
.Ft void
|
|
.Fn threadpool_job_done "struct threadpool_job *job"
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.Ft void
|
|
.Fn threadpool_schedule_job "struct threadpool *pool" "struct threadpool_job *job"
|
|
.\"
|
|
.Ft void
|
|
.Fn threadpool_cancel_job "struct threadpool *pool" "struct threadpool_job *job"
|
|
.\"
|
|
.Ft bool
|
|
.Fn threadpool_cancel_job_async "struct threadpool *pool" "struct threadpool_job *job"
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
abstraction is provided to share a pool of
|
|
.Xr kthread 9
|
|
kernel threads for medium- to long-term actions, called jobs, which can
|
|
be scheduled from contexts that do not allow sleeping.
|
|
.Pp
|
|
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
|
|
.Fn threadpool_get
|
|
and
|
|
.Fn threadpool_put .
|
|
Access to the per-CPU thread pools is provided by
|
|
.Fn threadpool_percpu_get
|
|
and
|
|
.Fn threadpool_percpu_put .
|
|
.Pp
|
|
Job state is stored in the
|
|
.Vt threadpool_job
|
|
structure.
|
|
Callers of the
|
|
.Nm
|
|
abstraction
|
|
must allocate memory for
|
|
.Vt threadpool_job
|
|
structures, but should consider them opaque, and should not inspect or
|
|
copy them.
|
|
Each job represented by a
|
|
.Vt threadpool_job
|
|
structure will be run only once at a time, until the action associated
|
|
with it calls
|
|
.Fn threadpool_job_done .
|
|
.Pp
|
|
Jobs are run in thread context and may take arbitrarily long to run or
|
|
sleep arbitrarily long.
|
|
.\" The
|
|
.\" .Nm
|
|
.\" abstraction is intended as a building block for cheaper abstractions,
|
|
.\" namely
|
|
.\" .Xr task 9
|
|
.\" and
|
|
.\" .Xr workqueue 9 .
|
|
.\" It should generally not be used directly.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.Sh FUNCTIONS
|
|
.\"
|
|
.Bl -tag -width abcd
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.It Fn threadpool_get "poolp" "pri"
|
|
Obtain a reference to the unbound thread pool at priority
|
|
.Fa pri
|
|
and store it in
|
|
.Fa poolp .
|
|
.Pp
|
|
May sleep.
|
|
.\"
|
|
.It Fn threadpool_put "pool" "pri"
|
|
Release the reference to the unbound thread pool
|
|
.Fa pool
|
|
at priority
|
|
.Fa pri ,
|
|
which must be the same as the priority that was passed to
|
|
.Fn threadpool_get
|
|
to obtain
|
|
.Fa pool .
|
|
.Pp
|
|
May sleep.
|
|
.Pp
|
|
Do not use
|
|
.Fn threadpool_put
|
|
with thread pools obtained from
|
|
.Fn threadpool_percpu_ref
|
|
or
|
|
.Fn threadpool_percpu_ref_remote .
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.It Fn threadpool_percpu_get "pool_percpup" "pri"
|
|
Obtain a reference to the per-CPU thread pool at priority
|
|
.Fa pri
|
|
and store it in
|
|
.Fa pool_percpup .
|
|
.Pp
|
|
Use
|
|
.Fn threadpool_percpu_ref
|
|
or
|
|
.Fn threadpool_percpu_ref_remote
|
|
with it to get at the thread pool for a particular CPU.
|
|
.Pp
|
|
May sleep.
|
|
.\"
|
|
.It Fn threadpool_percpu_put "pool_percpu" "pri"
|
|
Release a reference to the per-CPU thread pool
|
|
.Fa pool_percpu
|
|
at priority
|
|
.Fa pri .
|
|
.Pp
|
|
May sleep.
|
|
.\"
|
|
.It Fn threadpool_percpu_ref "pool_percpu"
|
|
Return the thread pool in
|
|
.Fa pool_percpu
|
|
for the current CPU.
|
|
.Pp
|
|
The resulting thread pool pointer is stable until
|
|
.Fa pool_percpu
|
|
is released with
|
|
.Fn threadpool_percpu_put .
|
|
Using it to schedule or cancel a job does not require being on the same
|
|
CPU.
|
|
.Pp
|
|
Do not use
|
|
.Fn threadpool_put
|
|
with thread pools obtained from
|
|
.Fn threadpool_percpu_ref .
|
|
.\"
|
|
.It Fn threadpool_percpu_ref_remote "pool_percpu" "ci"
|
|
Return the thread pool in
|
|
.Fa pool_percpu
|
|
for the CPU whose
|
|
.Vt struct cpu_info
|
|
is given by
|
|
.Fa ci .
|
|
.Pp
|
|
The resulting thread pool pointer is stable until
|
|
.Fa pool_percpu
|
|
is released with
|
|
.Fn 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
|
|
.Fn threadpool_percpu_ref
|
|
and use the resulting thread pool only on the same CPU.
|
|
.Pp
|
|
Do not use
|
|
.Fn threadpool_put
|
|
with thread pools obtained from
|
|
.Fn threadpool_percpu_ref_remote .
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.It Fn threadpool_job_init "job" "fn" "interlock" "fmt" "..."
|
|
Initialize the threadpool job
|
|
.Fa job
|
|
to run
|
|
.Fa fn
|
|
when scheduled and to interlock with
|
|
.Fa interlock .
|
|
The argument
|
|
.Fa fmt
|
|
is a
|
|
.Xr printf 9
|
|
format string for the job's name.
|
|
.Pp
|
|
The mutex
|
|
.Fa interlock
|
|
is used to synchronize job scheduling and completion.
|
|
The action
|
|
.Fa fn
|
|
is required to eventually call
|
|
.Fn threadpool_job_done ,
|
|
with
|
|
.Fa 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.
|
|
.Pp
|
|
To change the action of a job, you must use
|
|
.Fn threadpool_job_destroy
|
|
first and then call
|
|
.Fn threadpool_job_init
|
|
again.
|
|
.\"
|
|
.It Fn threadpool_job_destroy "job"
|
|
Destroy the threadpool job
|
|
.Fa job .
|
|
.Fa job
|
|
must not currently be scheduled to run.
|
|
If it may still be scheduled, you can use
|
|
.Fn threadpool_cancel_job
|
|
to cancel it.
|
|
However,
|
|
.Fn threadpool_cancel_job_async
|
|
is not enough.
|
|
.\"
|
|
.It Fn threadpool_job_done "job"
|
|
Notify that
|
|
.Fa job
|
|
is done, so that subsequent calls to
|
|
.Fn threadpool_schedule_job
|
|
will cause it to re-run its action.
|
|
.Pp
|
|
.Fn threadpool_job_done
|
|
must be called exactly once by a job's action, and may not be called in
|
|
any other context.
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.It Fn threadpool_schedule_job "pool" "job"
|
|
Schedule
|
|
.Fa job
|
|
to run in a thread in
|
|
.Fa pool
|
|
as soon as possible, creating a new thread if necessary.
|
|
.Pp
|
|
Caller must hold the interlock of
|
|
.Fa job .
|
|
.Pp
|
|
.Fn threadpool_schedule_job
|
|
may be called in any context, including hard interrupt context, except
|
|
at interrupt priority levels above
|
|
.Vt IPL_VM .
|
|
.\"
|
|
.It Fn threadpool_cancel_job "pool" "job"
|
|
Cancel
|
|
.Fa job
|
|
if it has been scheduled but has not yet been assigned a thread, or
|
|
wait for it to complete if it has.
|
|
.Pp
|
|
Caller must hold the interlock of
|
|
.Fa job ,
|
|
which may be released in order to wait for completion.
|
|
.Pp
|
|
If
|
|
.Fa job
|
|
has not been scheduled,
|
|
.Fn threadpool_cancel_job
|
|
returns immediately.
|
|
If
|
|
.Fa job
|
|
has been scheduled, it must have been scheduled in
|
|
.Fa pool ,
|
|
not in any other thread pool.
|
|
.Pp
|
|
May sleep.
|
|
.\"
|
|
.It Fn threadpool_cancel_job_async "pool" "job"
|
|
Try to cancel
|
|
.Fa job
|
|
like
|
|
.Fn threadpool_cancel_job ,
|
|
but if it is already running, return
|
|
.Vt false
|
|
instead of waiting;
|
|
otherwise, if it was not scheduled, or if it was scheduled and has not
|
|
yet begun to run, return
|
|
.Vt true .
|
|
.Pp
|
|
Caller must hold the interlock of
|
|
.Fa job .
|
|
.Pp
|
|
.Fn threadpool_cancel_job_async
|
|
may be called in any context, including hard interrupt context, except
|
|
at interrupt priority levels above
|
|
.Vt IPL_VM .
|
|
.\""""""""""""""""""""""""""""""""""""
|
|
.El
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.Sh CODE REFERENCES
|
|
The
|
|
.Nm
|
|
abstraction is implemented in
|
|
.Pa sys/kern/kern_threadpool.c .
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.Sh SEE ALSO
|
|
.Xr kthread 9 ,
|
|
.\" .Xr softint 9 ,
|
|
.\" .Xr task 9 ,
|
|
.Xr workqueue 9
|