Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 17 Jan 2014 16:34:57 +0200
From:      Andriy Gapon <avg@FreeBSD.org>
To:        "Justin T. Gibbs" <gibbs@scsiguy.com>
Cc:        svn-src-head@FreeBSD.org, svn-src-all@FreeBSD.org, src-committers@FreeBSD.org
Subject:   Re: svn commit: r258713 - in head/sys: kern sys
Message-ID:  <52D93F91.502@FreeBSD.org>
In-Reply-To: <3784C560-3648-4E03-93DA-9A60E3AC401D@scsiguy.com>
References:  <201311281856.rASIuZu8059699@svn.freebsd.org> <3784C560-3648-4E03-93DA-9A60E3AC401D@scsiguy.com>

next in thread | previous in thread | raw e-mail | index | archive | help
on 30/11/2013 08:46 Justin T. Gibbs said the following:
> Man page update?

I came up with the following update that
- adds taskqueue_drain_all documentation
- extends taskqueue_drain description
- adds description for previously undocumented taskqueue_block /
taskqueue_unblock, including a warning on taskqueue_block + taskqueue_drain
combination

All reviews and suggestions are welcome.  Both for content and language.

diff --git a/share/man/man9/taskqueue.9 b/share/man/man9/taskqueue.9
index 5f6131a..4db3d7a 100644
--- a/share/man/man9/taskqueue.9
+++ b/share/man/man9/taskqueue.9
@@ -86,6 +86,12 @@ struct timeout_task;
 .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task"
 .Ft void
 .Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task
*timeout_task"
+.Ft void
+.Fn taskqueue_drain_all "struct taskqueue *queue"
+.Ft void
+.Fn taskqueue_block "struct taskqueue *queue"
+.Ft void
+.Fn taskqueue_unblock "struct taskqueue *queue"
 .Ft int
 .Fn taskqueue_member "struct taskqueue *queue" "struct thread *td"
 .Ft void
@@ -255,6 +261,74 @@ function is used to wait for the scheduled task to finish.
 There is no guarantee that the task will not be
 enqueued after call to
 .Fn taskqueue_drain .
+Because the caller typically would use
+.Fn taskqueue_drain
+to put the task into a known state, then the caller should use
+out-of-band means to ensure, before calling
+.Fn taskqueue_drain ,
+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 the pending and running tasks that
+are enqueued on the taskqueue to finish.
+The caller must arrange that the tasks are not re-enqueued.
+Note that
+.Fn taskqueue_drain_all
+currently does not handle tasks with delayed enqueueing.
+.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 a thread that is supposed to call
+.Fn taskqueue_unblock .
+Thus, use of
+.Fn taskqueue_drain
+after
+.Fn taskqueue_block
+is discouraged, because a state of the task can not be known in advance.
+The same 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.
 .Pp
 The
 .Fn taskqueue_member


-- 
Andriy Gapon



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?52D93F91.502>