2000-05-28 16:53:50 +00:00
|
|
|
.\" -*- nroff -*-
|
|
|
|
.\"
|
|
|
|
.\" Copyright (c) 2000 Doug Rabson
|
|
|
|
.\"
|
|
|
|
.\" All rights reserved.
|
|
|
|
.\"
|
|
|
|
.\" This program is free software.
|
|
|
|
.\"
|
|
|
|
.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
|
|
|
|
.\"
|
|
|
|
.\" $FreeBSD$
|
|
|
|
.\"
|
2020-06-07 09:17:57 +00:00
|
|
|
.Dd June 6, 2020
|
2000-05-28 16:53:50 +00:00
|
|
|
.Dt TASKQUEUE 9
|
|
|
|
.Os
|
|
|
|
.Sh NAME
|
|
|
|
.Nm taskqueue
|
|
|
|
.Nd asynchronous task execution
|
|
|
|
.Sh SYNOPSIS
|
2001-10-01 16:09:29 +00:00
|
|
|
.In sys/param.h
|
2001-12-26 23:14:04 +00:00
|
|
|
.In sys/kernel.h
|
|
|
|
.In sys/malloc.h
|
2001-10-01 16:09:29 +00:00
|
|
|
.In sys/queue.h
|
|
|
|
.In sys/taskqueue.h
|
2000-05-28 16:53:50 +00:00
|
|
|
.Bd -literal
|
2004-10-26 17:14:45 +00:00
|
|
|
typedef void (*task_fn_t)(void *context, int pending);
|
2000-05-28 16:53:50 +00:00
|
|
|
|
|
|
|
typedef void (*taskqueue_enqueue_fn)(void *context);
|
|
|
|
|
|
|
|
struct task {
|
|
|
|
STAILQ_ENTRY(task) ta_link; /* link for queue */
|
2005-05-01 02:12:44 +00:00
|
|
|
u_short ta_pending; /* count times queued */
|
|
|
|
u_short ta_priority; /* priority of task in queue */
|
2004-10-26 17:14:45 +00:00
|
|
|
task_fn_t ta_func; /* task handler */
|
2000-05-28 16:53:50 +00:00
|
|
|
void *ta_context; /* argument for handler */
|
|
|
|
};
|
2011-04-26 11:43:57 +00:00
|
|
|
|
Extend taskqueue(9) to enable per-taskqueue callbacks.
The scope of these callbacks is primarily to support actions that affect the
taskqueue's thread environments. They are entirely optional, and
consequently are introduced as a new API: taskqueue_set_callback().
This interface allows the caller to specify that a taskqueue requires a
callback and optional context pointer for a given callback type.
The callback types included in this commit can be used to register a
constructor and destructor for thread-local storage using osd(9). This
allows a particular taskqueue to define that its threads require a specific
type of TLS, without the need for a specially-orchestrated task-based
mechanism for startup and shutdown in order to accomplish it.
Two callback types are supported at this point:
- TASKQUEUE_CALLBACK_TYPE_INIT, called by every thread when it starts, prior
to processing any tasks.
- TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, called by every thread when it exits,
after it has processed its last task but before the taskqueue is
reclaimed.
While I'm here:
- Add two new macros, TQ_ASSERT_LOCKED and TQ_ASSERT_UNLOCKED, and use them
in appropriate locations.
- Fix taskqueue.9 to mention taskqueue_start_threads(), which is a required
interface for all consumers of taskqueue(9).
Reviewed by: kib (all), eadler (taskqueue.9), brd (taskqueue.9)
Approved by: ken (mentor)
Sponsored by: Spectra Logic
MFC after: 1 month
2013-03-23 15:11:53 +00:00
|
|
|
enum taskqueue_callback_type {
|
|
|
|
TASKQUEUE_CALLBACK_TYPE_INIT,
|
|
|
|
TASKQUEUE_CALLBACK_TYPE_SHUTDOWN,
|
|
|
|
};
|
|
|
|
|
|
|
|
typedef void (*taskqueue_callback_fn)(void *context);
|
|
|
|
|
2011-04-26 11:43:57 +00:00
|
|
|
struct timeout_task;
|
2000-05-28 16:53:50 +00:00
|
|
|
.Ed
|
|
|
|
.Ft struct taskqueue *
|
2008-05-22 21:41:19 +00:00
|
|
|
.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
|
2008-06-13 19:35:17 +00:00
|
|
|
.Ft struct taskqueue *
|
|
|
|
.Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context"
|
Extend taskqueue(9) to enable per-taskqueue callbacks.
The scope of these callbacks is primarily to support actions that affect the
taskqueue's thread environments. They are entirely optional, and
consequently are introduced as a new API: taskqueue_set_callback().
This interface allows the caller to specify that a taskqueue requires a
callback and optional context pointer for a given callback type.
The callback types included in this commit can be used to register a
constructor and destructor for thread-local storage using osd(9). This
allows a particular taskqueue to define that its threads require a specific
type of TLS, without the need for a specially-orchestrated task-based
mechanism for startup and shutdown in order to accomplish it.
Two callback types are supported at this point:
- TASKQUEUE_CALLBACK_TYPE_INIT, called by every thread when it starts, prior
to processing any tasks.
- TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, called by every thread when it exits,
after it has processed its last task but before the taskqueue is
reclaimed.
While I'm here:
- Add two new macros, TQ_ASSERT_LOCKED and TQ_ASSERT_UNLOCKED, and use them
in appropriate locations.
- Fix taskqueue.9 to mention taskqueue_start_threads(), which is a required
interface for all consumers of taskqueue(9).
Reviewed by: kib (all), eadler (taskqueue.9), brd (taskqueue.9)
Approved by: ken (mentor)
Sponsored by: Spectra Logic
MFC after: 1 month
2013-03-23 15:11:53 +00:00
|
|
|
.Ft int
|
|
|
|
.Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "const char *name" "..."
|
2014-05-25 02:45:26 +00:00
|
|
|
.Ft int
|
2019-10-17 06:58:07 +00:00
|
|
|
.Fo taskqueue_start_threads_cpuset
|
|
|
|
.Fa "struct taskqueue **tqp" "int count" "int pri" "cpuset_t *mask"
|
|
|
|
.Fa "const char *name" "..."
|
|
|
|
.Fc
|
|
|
|
.Ft int
|
|
|
|
.Fo taskqueue_start_threads_in_proc
|
|
|
|
.Fa "struct taskqueue **tqp" "int count" "int pri" "struct proc *proc"
|
2014-05-25 02:45:26 +00:00
|
|
|
.Fa "const char *name" "..."
|
|
|
|
.Fc
|
Extend taskqueue(9) to enable per-taskqueue callbacks.
The scope of these callbacks is primarily to support actions that affect the
taskqueue's thread environments. They are entirely optional, and
consequently are introduced as a new API: taskqueue_set_callback().
This interface allows the caller to specify that a taskqueue requires a
callback and optional context pointer for a given callback type.
The callback types included in this commit can be used to register a
constructor and destructor for thread-local storage using osd(9). This
allows a particular taskqueue to define that its threads require a specific
type of TLS, without the need for a specially-orchestrated task-based
mechanism for startup and shutdown in order to accomplish it.
Two callback types are supported at this point:
- TASKQUEUE_CALLBACK_TYPE_INIT, called by every thread when it starts, prior
to processing any tasks.
- TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, called by every thread when it exits,
after it has processed its last task but before the taskqueue is
reclaimed.
While I'm here:
- Add two new macros, TQ_ASSERT_LOCKED and TQ_ASSERT_UNLOCKED, and use them
in appropriate locations.
- Fix taskqueue.9 to mention taskqueue_start_threads(), which is a required
interface for all consumers of taskqueue(9).
Reviewed by: kib (all), eadler (taskqueue.9), brd (taskqueue.9)
Approved by: ken (mentor)
Sponsored by: Spectra Logic
MFC after: 1 month
2013-03-23 15:11:53 +00:00
|
|
|
.Ft void
|
|
|
|
.Fn taskqueue_set_callback "struct taskqueue *queue" "enum taskqueue_callback_type cb_type" "taskqueue_callback_fn callback" "void *context"
|
2000-05-28 16:53:50 +00:00
|
|
|
.Ft void
|
|
|
|
.Fn taskqueue_free "struct taskqueue *queue"
|
|
|
|
.Ft int
|
|
|
|
.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task"
|
2004-01-02 07:23:40 +00:00
|
|
|
.Ft int
|
2011-04-26 11:43:57 +00:00
|
|
|
.Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks"
|
|
|
|
.Ft int
|
2017-07-31 00:54:50 +00:00
|
|
|
.Fn taskqueue_enqueue_timeout_sbt "struct taskqueue *queue" "struct timeout_task *timeout_task" "sbintime_t sbt" "sbintime_t pr" "int flags"
|
|
|
|
.Ft int
|
2010-11-08 20:56:31 +00:00
|
|
|
.Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp"
|
2011-04-26 11:43:57 +00:00
|
|
|
.Ft int
|
|
|
|
.Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp"
|
2000-05-28 16:53:50 +00:00
|
|
|
.Ft void
|
2005-05-19 18:31:42 +00:00
|
|
|
.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
|
2011-04-26 11:43:57 +00:00
|
|
|
.Ft void
|
|
|
|
.Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task"
|
2014-02-14 15:03:55 +00:00
|
|
|
.Ft void
|
|
|
|
.Fn taskqueue_drain_all "struct taskqueue *queue"
|
|
|
|
.Ft void
|
2018-11-21 17:18:27 +00:00
|
|
|
.Fn taskqueue_quiesce "struct taskqueue *queue"
|
|
|
|
.Ft void
|
2014-02-14 15:03:55 +00:00
|
|
|
.Fn taskqueue_block "struct taskqueue *queue"
|
|
|
|
.Ft void
|
|
|
|
.Fn taskqueue_unblock "struct taskqueue *queue"
|
2009-08-17 09:01:20 +00:00
|
|
|
.Ft int
|
|
|
|
.Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
|
2010-10-12 18:36:03 +00:00
|
|
|
.Ft void
|
2010-10-13 22:59:04 +00:00
|
|
|
.Fn taskqueue_run "struct taskqueue *queue"
|
2011-04-26 11:43:57 +00:00
|
|
|
.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context"
|
2011-12-19 18:55:13 +00:00
|
|
|
.Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context"
|
2000-05-28 16:53:50 +00:00
|
|
|
.Fn TASKQUEUE_DECLARE "name"
|
2001-12-26 23:14:04 +00:00
|
|
|
.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
|
2008-06-13 19:35:17 +00:00
|
|
|
.Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init"
|
2004-08-08 02:37:22 +00:00
|
|
|
.Fn TASKQUEUE_DEFINE_THREAD "name"
|
2008-06-13 19:35:17 +00:00
|
|
|
.Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
|
2011-04-26 11:43:57 +00:00
|
|
|
.Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context"
|
2000-05-28 16:53:50 +00:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
These functions provide a simple interface for asynchronous execution
|
|
|
|
of code.
|
|
|
|
.Pp
|
|
|
|
The function
|
|
|
|
.Fn taskqueue_create
|
|
|
|
is used to create new queues.
|
|
|
|
The arguments to
|
|
|
|
.Fn taskqueue_create
|
2005-05-01 02:12:44 +00:00
|
|
|
include a name that should be unique,
|
2000-05-28 16:53:50 +00:00
|
|
|
a set of
|
|
|
|
.Xr malloc 9
|
2005-05-01 02:12:44 +00:00
|
|
|
flags that specify whether the call to
|
2000-05-28 16:53:50 +00:00
|
|
|
.Fn malloc
|
2005-05-01 02:12:44 +00:00
|
|
|
is allowed to sleep,
|
|
|
|
a function that is called from
|
2000-05-28 16:53:50 +00:00
|
|
|
.Fn taskqueue_enqueue
|
2005-05-01 02:12:44 +00:00
|
|
|
when a task is added to the queue,
|
|
|
|
and a pointer to the memory location where the identity of the
|
|
|
|
thread that services the queue is recorded.
|
2000-05-28 16:53:50 +00:00
|
|
|
.\" XXX The rest of the sentence gets lots in relation to the first part.
|
2005-05-01 02:12:44 +00:00
|
|
|
The function called from
|
|
|
|
.Fn taskqueue_enqueue
|
|
|
|
must arrange for the queue to be processed
|
2000-05-28 16:53:50 +00:00
|
|
|
(for instance by scheduling a software interrupt or waking a kernel
|
|
|
|
thread).
|
2005-05-01 02:12:44 +00:00
|
|
|
The memory location where the thread identity is recorded is used
|
|
|
|
to signal the service thread(s) to terminate--when this value is set to
|
|
|
|
zero and the thread is signaled it will terminate.
|
2012-03-29 05:02:12 +00:00
|
|
|
If the queue is intended for use in fast interrupt handlers
|
|
|
|
.Fn taskqueue_create_fast
|
2008-06-13 19:35:17 +00:00
|
|
|
should be used in place of
|
|
|
|
.Fn taskqueue_create .
|
2000-05-28 16:53:50 +00:00
|
|
|
.Pp
|
|
|
|
The function
|
|
|
|
.Fn taskqueue_free
|
2009-08-18 13:55:48 +00:00
|
|
|
should be used to free the memory used by the queue.
|
2005-05-01 02:12:44 +00:00
|
|
|
Any tasks that are on the queue will be executed at this time after
|
|
|
|
which the thread servicing the queue will be signaled that it should exit.
|
2000-05-28 16:53:50 +00:00
|
|
|
.Pp
|
Extend taskqueue(9) to enable per-taskqueue callbacks.
The scope of these callbacks is primarily to support actions that affect the
taskqueue's thread environments. They are entirely optional, and
consequently are introduced as a new API: taskqueue_set_callback().
This interface allows the caller to specify that a taskqueue requires a
callback and optional context pointer for a given callback type.
The callback types included in this commit can be used to register a
constructor and destructor for thread-local storage using osd(9). This
allows a particular taskqueue to define that its threads require a specific
type of TLS, without the need for a specially-orchestrated task-based
mechanism for startup and shutdown in order to accomplish it.
Two callback types are supported at this point:
- TASKQUEUE_CALLBACK_TYPE_INIT, called by every thread when it starts, prior
to processing any tasks.
- TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, called by every thread when it exits,
after it has processed its last task but before the taskqueue is
reclaimed.
While I'm here:
- Add two new macros, TQ_ASSERT_LOCKED and TQ_ASSERT_UNLOCKED, and use them
in appropriate locations.
- Fix taskqueue.9 to mention taskqueue_start_threads(), which is a required
interface for all consumers of taskqueue(9).
Reviewed by: kib (all), eadler (taskqueue.9), brd (taskqueue.9)
Approved by: ken (mentor)
Sponsored by: Spectra Logic
MFC after: 1 month
2013-03-23 15:11:53 +00:00
|
|
|
Once a taskqueue has been created, its threads should be started using
|
2019-10-17 06:58:07 +00:00
|
|
|
.Fn taskqueue_start_threads ,
|
|
|
|
.Fn taskqueue_start_threads_cpuset
|
2014-05-25 02:45:26 +00:00
|
|
|
or
|
2019-10-17 06:58:07 +00:00
|
|
|
.Fn taskqueue_start_threads_in_proc .
|
|
|
|
.Fn taskqueue_start_threads_cpuset
|
|
|
|
takes a
|
|
|
|
.Va cpuset
|
|
|
|
argument which will cause the threads which are started for the taskqueue
|
|
|
|
to be restricted to run on the given CPUs.
|
|
|
|
.Fn taskqueue_start_threads_in_proc
|
2014-05-25 02:45:26 +00:00
|
|
|
takes a
|
2019-10-17 06:58:07 +00:00
|
|
|
.Va proc
|
2014-05-25 02:45:26 +00:00
|
|
|
argument which will cause the threads which are started for the taskqueue
|
2019-10-17 06:58:07 +00:00
|
|
|
to be assigned to the given kernel process.
|
Extend taskqueue(9) to enable per-taskqueue callbacks.
The scope of these callbacks is primarily to support actions that affect the
taskqueue's thread environments. They are entirely optional, and
consequently are introduced as a new API: taskqueue_set_callback().
This interface allows the caller to specify that a taskqueue requires a
callback and optional context pointer for a given callback type.
The callback types included in this commit can be used to register a
constructor and destructor for thread-local storage using osd(9). This
allows a particular taskqueue to define that its threads require a specific
type of TLS, without the need for a specially-orchestrated task-based
mechanism for startup and shutdown in order to accomplish it.
Two callback types are supported at this point:
- TASKQUEUE_CALLBACK_TYPE_INIT, called by every thread when it starts, prior
to processing any tasks.
- TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, called by every thread when it exits,
after it has processed its last task but before the taskqueue is
reclaimed.
While I'm here:
- Add two new macros, TQ_ASSERT_LOCKED and TQ_ASSERT_UNLOCKED, and use them
in appropriate locations.
- Fix taskqueue.9 to mention taskqueue_start_threads(), which is a required
interface for all consumers of taskqueue(9).
Reviewed by: kib (all), eadler (taskqueue.9), brd (taskqueue.9)
Approved by: ken (mentor)
Sponsored by: Spectra Logic
MFC after: 1 month
2013-03-23 15:11:53 +00:00
|
|
|
Callbacks may optionally be registered using
|
|
|
|
.Fn taskqueue_set_callback .
|
|
|
|
Currently, callbacks may be registered for the following purposes:
|
|
|
|
.Bl -tag -width TASKQUEUE_CALLBACK_TYPE_SHUTDOWN
|
|
|
|
.It Dv TASKQUEUE_CALLBACK_TYPE_INIT
|
|
|
|
This callback is called by every thread in the taskqueue, before it executes
|
|
|
|
any tasks.
|
|
|
|
This callback must be set before the taskqueue's threads are started.
|
|
|
|
.It Dv TASKQUEUE_CALLBACK_TYPE_SHUTDOWN
|
|
|
|
This callback is called by every thread in the taskqueue, after it executes
|
|
|
|
its last task.
|
|
|
|
This callback will always be called before the taskqueue structure is
|
|
|
|
reclaimed.
|
|
|
|
.El
|
|
|
|
.Pp
|
2000-05-28 16:53:50 +00:00
|
|
|
To add a task to the list of tasks queued on a taskqueue, call
|
|
|
|
.Fn taskqueue_enqueue
|
|
|
|
with pointers to the queue and task.
|
|
|
|
If the task's
|
|
|
|
.Va ta_pending
|
|
|
|
field is non-zero,
|
|
|
|
then it is simply incremented to reflect the number of times the task
|
2011-09-15 08:42:06 +00:00
|
|
|
was enqueued, up to a cap of USHRT_MAX.
|
2000-05-28 16:53:50 +00:00
|
|
|
Otherwise,
|
|
|
|
the task is added to the list before the first task which has a lower
|
|
|
|
.Va ta_priority
|
|
|
|
value or at the end of the list if no tasks have a lower priority.
|
|
|
|
Enqueueing a task does not perform any memory allocation which makes
|
|
|
|
it suitable for calling from an interrupt handler.
|
|
|
|
This function will return
|
2000-11-22 16:11:48 +00:00
|
|
|
.Er EPIPE
|
2000-05-28 16:53:50 +00:00
|
|
|
if the queue is being freed.
|
|
|
|
.Pp
|
|
|
|
When a task is executed,
|
|
|
|
first it is removed from the queue,
|
|
|
|
the value of
|
|
|
|
.Va ta_pending
|
|
|
|
is recorded and then the field is zeroed.
|
|
|
|
The function
|
|
|
|
.Va ta_func
|
|
|
|
from the task structure is called with the value of the field
|
|
|
|
.Va ta_context
|
|
|
|
as its first argument
|
|
|
|
and the value of
|
|
|
|
.Va ta_pending
|
|
|
|
as its second argument.
|
2007-07-09 06:24:10 +00:00
|
|
|
After the function
|
|
|
|
.Va ta_func
|
|
|
|
returns,
|
|
|
|
.Xr wakeup 9
|
|
|
|
is called on the task pointer passed to
|
|
|
|
.Fn taskqueue_enqueue .
|
2000-05-28 16:53:50 +00:00
|
|
|
.Pp
|
2005-06-15 13:31:23 +00:00
|
|
|
The
|
2011-04-26 11:43:57 +00:00
|
|
|
.Fn taskqueue_enqueue_timeout
|
2017-07-31 00:54:50 +00:00
|
|
|
function is used to schedule the enqueue after the specified number of
|
2011-04-26 11:43:57 +00:00
|
|
|
.Va ticks .
|
2017-07-31 00:54:50 +00:00
|
|
|
The
|
|
|
|
.Fn taskqueue_enqueue_timeout_sbt
|
|
|
|
function provides finer control over the scheduling based on
|
|
|
|
.Va sbt ,
|
|
|
|
.Va pr ,
|
|
|
|
and
|
|
|
|
.Va flags ,
|
|
|
|
as detailed in
|
2020-06-07 09:17:57 +00:00
|
|
|
.Xr callout 9 .
|
2011-04-26 11:43:57 +00:00
|
|
|
Only non-fast task queues can be used for
|
|
|
|
.Va timeout_task
|
|
|
|
scheduling.
|
2012-12-04 00:32:12 +00:00
|
|
|
If the
|
|
|
|
.Va ticks
|
|
|
|
argument is negative, the already scheduled enqueueing is not re-scheduled.
|
2012-12-04 14:07:17 +00:00
|
|
|
Otherwise, the task is scheduled for enqueueing in the future,
|
2012-12-04 00:32:12 +00:00
|
|
|
after the absolute value of
|
|
|
|
.Va ticks
|
|
|
|
is passed.
|
2016-10-03 12:48:55 +00:00
|
|
|
This function returns -1 if the task is being drained.
|
|
|
|
Otherwise, the number of pending calls is returned.
|
2011-04-26 11:43:57 +00:00
|
|
|
.Pp
|
|
|
|
The
|
2010-11-08 20:56:31 +00:00
|
|
|
.Fn taskqueue_cancel
|
|
|
|
function is used to cancel a task.
|
|
|
|
The
|
|
|
|
.Va ta_pending
|
|
|
|
count is cleared, and the old value returned in the reference
|
|
|
|
parameter
|
|
|
|
.Fa pendp ,
|
2012-05-20 16:43:47 +00:00
|
|
|
if it is
|
|
|
|
.Pf non- Dv NULL .
|
2010-11-08 20:56:31 +00:00
|
|
|
If the task is currently running,
|
|
|
|
.Dv EBUSY
|
|
|
|
is returned, otherwise 0.
|
|
|
|
To implement a blocking
|
|
|
|
.Fn taskqueue_cancel
|
|
|
|
that waits for a running task to finish, it could look like:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
while (taskqueue_cancel(tq, task, NULL) != 0)
|
|
|
|
taskqueue_drain(tq, task);
|
|
|
|
.Ed
|
|
|
|
.Pp
|
|
|
|
Note that, as with
|
|
|
|
.Fn taskqueue_drain ,
|
|
|
|
the caller is responsible for ensuring that the task is not re-enqueued
|
|
|
|
after being canceled.
|
|
|
|
.Pp
|
2011-04-26 11:43:57 +00:00
|
|
|
Similarly, the
|
|
|
|
.Fn taskqueue_cancel_timeout
|
|
|
|
function is used to cancel the scheduled task execution.
|
|
|
|
.Pp
|
2010-11-08 20:56:31 +00:00
|
|
|
The
|
2005-05-19 18:31:42 +00:00
|
|
|
.Fn taskqueue_drain
|
2011-04-26 11:43:57 +00:00
|
|
|
function is used to wait for the task to finish, and
|
|
|
|
the
|
|
|
|
.Fn taskqueue_drain_timeout
|
|
|
|
function is used to wait for the scheduled task to finish.
|
2005-05-19 18:31:42 +00:00
|
|
|
There is no guarantee that the task will not be
|
|
|
|
enqueued after call to
|
|
|
|
.Fn taskqueue_drain .
|
2014-02-14 15:03:55 +00:00
|
|
|
If the caller wants to put the task into a known state,
|
|
|
|
then before calling
|
|
|
|
.Fn taskqueue_drain
|
|
|
|
the caller should use out-of-band means to ensure that the task
|
|
|
|
would not be enqueued.
|
|
|
|
For example, if the task is enqueued by an interrupt filter, then
|
|
|
|
the interrupt could be disabled.
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Fn taskqueue_drain_all
|
|
|
|
function is used to wait for all pending and running tasks that
|
|
|
|
are enqueued on the taskqueue to finish.
|
2015-01-04 19:55:44 +00:00
|
|
|
Tasks posted to the taskqueue after
|
2014-02-14 15:03:55 +00:00
|
|
|
.Fn taskqueue_drain_all
|
2015-01-04 19:55:44 +00:00
|
|
|
begins processing,
|
2015-06-18 16:29:11 +00:00
|
|
|
including pending enqueues scheduled by a previous call to
|
2015-01-04 19:55:44 +00:00
|
|
|
.Fn taskqueue_enqueue_timeout ,
|
|
|
|
do not extend the wait time of
|
|
|
|
.Fn taskqueue_drain_all
|
2015-06-18 16:29:11 +00:00
|
|
|
and may complete after
|
2015-01-04 19:55:44 +00:00
|
|
|
.Fn taskqueue_drain_all
|
|
|
|
returns.
|
2018-11-21 17:18:27 +00:00
|
|
|
The
|
|
|
|
.Fn taskqueue_quiesce
|
|
|
|
function is used to wait for the queue to become empty and for all
|
|
|
|
running tasks to finish.
|
|
|
|
To avoid blocking indefinitely, the caller must ensure by some mechanism
|
|
|
|
that tasks will eventually stop being posted to the queue.
|
2014-02-14 15:03:55 +00:00
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Fn taskqueue_block
|
|
|
|
function blocks the taskqueue.
|
|
|
|
It prevents any enqueued but not running tasks from being executed.
|
|
|
|
Future calls to
|
|
|
|
.Fn taskqueue_enqueue
|
|
|
|
will enqueue tasks, but the tasks will not be run until
|
|
|
|
.Fn taskqueue_unblock
|
|
|
|
is called.
|
|
|
|
Please note that
|
|
|
|
.Fn taskqueue_block
|
|
|
|
does not wait for any currently running tasks to finish.
|
|
|
|
Thus, the
|
|
|
|
.Fn taskqueue_block
|
|
|
|
does not provide a guarantee that
|
|
|
|
.Fn taskqueue_run
|
|
|
|
is not running after
|
|
|
|
.Fn taskqueue_block
|
|
|
|
returns, but it does provide a guarantee that
|
|
|
|
.Fn taskqueue_run
|
|
|
|
will not be called again
|
|
|
|
until
|
|
|
|
.Fn taskqueue_unblock
|
|
|
|
is called.
|
|
|
|
If the caller requires a guarantee that
|
|
|
|
.Fn taskqueue_run
|
|
|
|
is not running, then this must be arranged by the caller.
|
|
|
|
Note that if
|
|
|
|
.Fn taskqueue_drain
|
|
|
|
is called on a task that is enqueued on a taskqueue that is blocked by
|
|
|
|
.Fn taskqueue_block ,
|
|
|
|
then
|
|
|
|
.Fn taskqueue_drain
|
|
|
|
can not return until the taskqueue is unblocked.
|
|
|
|
This can result in a deadlock if the thread blocked in
|
|
|
|
.Fn taskqueue_drain
|
|
|
|
is the thread that is supposed to call
|
|
|
|
.Fn taskqueue_unblock .
|
|
|
|
Thus, use of
|
|
|
|
.Fn taskqueue_drain
|
|
|
|
after
|
|
|
|
.Fn taskqueue_block
|
|
|
|
is discouraged, because the state of the task can not be known in advance.
|
|
|
|
The same caveat applies to
|
|
|
|
.Fn taskqueue_drain_all .
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Fn taskqueue_unblock
|
|
|
|
function unblocks the previously blocked taskqueue.
|
|
|
|
All enqueued tasks can be run after this call.
|
2005-05-19 18:31:42 +00:00
|
|
|
.Pp
|
2009-08-17 09:01:20 +00:00
|
|
|
The
|
|
|
|
.Fn taskqueue_member
|
|
|
|
function returns
|
|
|
|
.No 1
|
2009-08-17 10:20:22 +00:00
|
|
|
if the given thread
|
2009-08-17 09:01:20 +00:00
|
|
|
.Fa td
|
2010-07-31 10:01:15 +00:00
|
|
|
is part of the given taskqueue
|
2009-08-17 09:01:20 +00:00
|
|
|
.Fa queue
|
|
|
|
and
|
|
|
|
.No 0
|
|
|
|
otherwise.
|
|
|
|
.Pp
|
2010-10-12 18:36:03 +00:00
|
|
|
The
|
|
|
|
.Fn taskqueue_run
|
|
|
|
function will run all pending tasks in the specified
|
|
|
|
.Fa queue .
|
|
|
|
Normally this function is only used internally.
|
|
|
|
.Pp
|
2000-05-28 16:53:50 +00:00
|
|
|
A convenience macro,
|
|
|
|
.Fn TASK_INIT "task" "priority" "func" "context"
|
|
|
|
is provided to initialise a
|
|
|
|
.Va task
|
|
|
|
structure.
|
2011-12-19 18:55:13 +00:00
|
|
|
The
|
|
|
|
.Fn TASK_INITIALIZER
|
|
|
|
macro generates an initializer for a task structure.
|
2011-04-26 11:43:57 +00:00
|
|
|
A macro
|
|
|
|
.Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context"
|
2011-12-19 18:55:13 +00:00
|
|
|
initializes the
|
|
|
|
.Va timeout_task
|
|
|
|
structure.
|
2000-05-28 16:53:50 +00:00
|
|
|
The values of
|
|
|
|
.Va priority ,
|
|
|
|
.Va func ,
|
|
|
|
and
|
|
|
|
.Va context
|
|
|
|
are simply copied into the task structure fields and the
|
|
|
|
.Va ta_pending
|
|
|
|
field is cleared.
|
|
|
|
.Pp
|
2008-06-13 19:35:17 +00:00
|
|
|
Five macros
|
2004-08-08 02:37:22 +00:00
|
|
|
.Fn TASKQUEUE_DECLARE "name" ,
|
|
|
|
.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" ,
|
2008-06-13 19:35:17 +00:00
|
|
|
.Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" ,
|
2000-05-28 16:53:50 +00:00
|
|
|
and
|
2004-08-08 02:37:22 +00:00
|
|
|
.Fn TASKQUEUE_DEFINE_THREAD "name"
|
2008-06-13 19:35:17 +00:00
|
|
|
.Fn TASKQUEUE_FAST_DEFINE_THREAD "name"
|
2004-08-08 02:37:22 +00:00
|
|
|
are used to declare a reference to a global queue, to define the
|
2005-01-12 21:48:25 +00:00
|
|
|
implementation of the queue, and declare a queue that uses its own thread.
|
2000-05-28 16:53:50 +00:00
|
|
|
The
|
|
|
|
.Fn TASKQUEUE_DEFINE
|
|
|
|
macro arranges to call
|
|
|
|
.Fn taskqueue_create
|
|
|
|
with the values of its
|
|
|
|
.Va name ,
|
|
|
|
.Va enqueue
|
|
|
|
and
|
|
|
|
.Va context
|
|
|
|
arguments during system initialisation.
|
|
|
|
After calling
|
|
|
|
.Fn taskqueue_create ,
|
|
|
|
the
|
|
|
|
.Va init
|
|
|
|
argument to the macro is executed as a C statement,
|
|
|
|
allowing any further initialisation to be performed
|
2017-03-19 01:24:18 +00:00
|
|
|
(such as registering an interrupt handler, etc.).
|
2000-05-28 16:53:50 +00:00
|
|
|
.Pp
|
2004-08-08 02:37:22 +00:00
|
|
|
The
|
|
|
|
.Fn TASKQUEUE_DEFINE_THREAD
|
2005-01-12 21:48:25 +00:00
|
|
|
macro defines a new taskqueue with its own kernel thread to serve tasks.
|
|
|
|
The variable
|
2004-08-08 02:37:22 +00:00
|
|
|
.Vt struct taskqueue *taskqueue_name
|
|
|
|
is used to enqueue tasks onto the queue.
|
2008-06-13 19:35:17 +00:00
|
|
|
.Pp
|
|
|
|
.Fn TASKQUEUE_FAST_DEFINE
|
2012-03-29 05:02:12 +00:00
|
|
|
and
|
2008-06-13 19:35:17 +00:00
|
|
|
.Fn TASKQUEUE_FAST_DEFINE_THREAD
|
2012-03-29 05:02:12 +00:00
|
|
|
act just like
|
2008-06-13 19:35:17 +00:00
|
|
|
.Fn TASKQUEUE_DEFINE
|
|
|
|
and
|
|
|
|
.Fn TASKQUEUE_DEFINE_THREAD
|
|
|
|
respectively but taskqueue is created with
|
|
|
|
.Fn taskqueue_create_fast .
|
2005-04-19 16:23:00 +00:00
|
|
|
.Ss Predefined Task Queues
|
|
|
|
The system provides four global taskqueues,
|
|
|
|
.Va taskqueue_fast ,
|
2000-05-28 16:53:50 +00:00
|
|
|
.Va taskqueue_swi ,
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
.Va taskqueue_swi_giant ,
|
2004-07-02 19:07:33 +00:00
|
|
|
and
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
.Va taskqueue_thread .
|
2005-04-19 16:23:00 +00:00
|
|
|
The
|
|
|
|
.Va taskqueue_fast
|
|
|
|
queue is for swi handlers dispatched from fast interrupt handlers,
|
|
|
|
where sleep mutexes cannot be used.
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
The swi taskqueues are run via a software interrupt mechanism.
|
2005-04-19 16:23:00 +00:00
|
|
|
The
|
|
|
|
.Va taskqueue_swi
|
|
|
|
queue runs without the protection of the
|
|
|
|
.Va Giant
|
|
|
|
kernel lock, and the
|
|
|
|
.Va taskqueue_swi_giant
|
|
|
|
queue runs with the protection of the
|
|
|
|
.Va Giant
|
|
|
|
kernel lock.
|
|
|
|
The thread taskqueue
|
|
|
|
.Va taskqueue_thread
|
|
|
|
runs in a kernel thread context, and tasks run from this thread do
|
|
|
|
not run under the
|
|
|
|
.Va Giant
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
kernel lock.
|
2005-04-19 16:23:00 +00:00
|
|
|
If the caller wants to run under
|
|
|
|
.Va Giant ,
|
|
|
|
he should explicitly acquire and release
|
|
|
|
.Va Giant
|
|
|
|
in his taskqueue handler routine.
|
2004-06-16 08:33:57 +00:00
|
|
|
.Pp
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
To use these queues,
|
2000-05-28 16:53:50 +00:00
|
|
|
call
|
|
|
|
.Fn taskqueue_enqueue
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
with the value of the global taskqueue variable for the queue you wish to
|
2016-03-01 17:47:32 +00:00
|
|
|
use.
|
2000-05-28 16:53:50 +00:00
|
|
|
.Pp
|
2003-09-03 05:35:37 +00:00
|
|
|
The software interrupt queues can be used,
|
2000-05-28 16:53:50 +00:00
|
|
|
for instance, for implementing interrupt handlers which must perform a
|
|
|
|
significant amount of processing in the handler.
|
|
|
|
The hardware interrupt handler would perform minimal processing of the
|
|
|
|
interrupt and then enqueue a task to finish the work.
|
|
|
|
This reduces to a minimum
|
|
|
|
the amount of time spent with interrupts disabled.
|
Move dynamic sysctl(8) variable creation for the cd(4) and da(4) drivers
out of cdregister() and daregister(), which are run from interrupt context.
The sysctl code does blocking mallocs (M_WAITOK), which causes problems
if malloc(9) actually needs to sleep.
The eventual fix for this issue will involve moving the CAM probe process
inside a kernel thread. For now, though, I have fixed the issue by moving
dynamic sysctl variable creation for these two drivers to a task queue
running in a kernel thread.
The existing task queues (taskqueue_swi and taskqueue_swi_giant) run in
software interrupt handlers, which wouldn't fix the problem at hand. So I
have created a new task queue, taskqueue_thread, that runs inside a kernel
thread. (It also runs outside of Giant -- clients must explicitly acquire
and release Giant in their taskqueue functions.)
scsi_cd.c: Remove sysctl variable creation code from cdregister(), and
move it to a new function, cdsysctlinit(). Queue
cdsysctlinit() to the taskqueue_thread taskqueue once we
have fully registered the cd(4) driver instance.
scsi_da.c: Remove sysctl variable creation code from daregister(), and
move it to move it to a new function, dasysctlinit().
Queue dasysctlinit() to the taskqueue_thread taskqueue once
we have fully registered the da(4) instance.
taskqueue.h: Declare the new taskqueue_thread taskqueue, update some
comments.
subr_taskqueue.c:
Create the new kernel thread taskqueue. This taskqueue
runs outside of Giant, so any functions queued to it would
need to explicitly acquire/release Giant if they need it.
cd.4: Update the cd(4) man page to talk about the minimum command
size sysctl/loader tunable. Also note that the changer
variables are available as loader tunables as well.
da.4: Update the da(4) man page to cover the retry_count,
default_timeout and minimum_cmd_size sysctl variables/loader
tunables. Remove references to /dev/r???, they aren't used
any longer.
cd.9: Update the cd(9) man page to describe the CD_Q_10_BYTE_ONLY
quirk.
taskqueue.9: Update the taskqueue(9) man page to describe the new thread
task queue, and the taskqueue_swi_giant queue.
MFC after: 3 days
2003-09-03 04:46:28 +00:00
|
|
|
.Pp
|
|
|
|
The thread queue can be used, for instance, by interrupt level routines
|
|
|
|
that need to call kernel functions that do things that can only be done
|
|
|
|
from a thread context.
|
|
|
|
(e.g., call malloc with the M_WAITOK flag.)
|
2005-05-01 02:12:44 +00:00
|
|
|
.Pp
|
|
|
|
Note that tasks queued on shared taskqueues such as
|
|
|
|
.Va taskqueue_swi
|
|
|
|
may be delayed an indeterminate amount of time before execution.
|
|
|
|
If queueing delays cannot be tolerated then a private taskqueue should
|
|
|
|
be created with a dedicated processing thread.
|
2005-04-15 14:46:59 +00:00
|
|
|
.Sh SEE ALSO
|
2020-06-07 09:17:57 +00:00
|
|
|
.Xr callout 9 ,
|
2005-04-15 14:46:59 +00:00
|
|
|
.Xr ithread 9 ,
|
|
|
|
.Xr kthread 9 ,
|
|
|
|
.Xr swi 9
|
2000-05-28 16:53:50 +00:00
|
|
|
.Sh HISTORY
|
|
|
|
This interface first appeared in
|
|
|
|
.Fx 5.0 .
|
2011-04-26 11:43:57 +00:00
|
|
|
There is a similar facility called work_queue in the Linux kernel.
|
2000-05-28 16:53:50 +00:00
|
|
|
.Sh AUTHORS
|
2005-06-28 20:15:19 +00:00
|
|
|
This manual page was written by
|
2000-05-28 16:53:50 +00:00
|
|
|
.An Doug Rabson .
|