From owner-freebsd-hackers@FreeBSD.ORG Fri Jan 24 20:56:58 2014 Return-Path: Delivered-To: hackers@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 89C91C72; Fri, 24 Jan 2014 20:56:58 +0000 (UTC) Received: from dmz-mailsec-scanner-8.mit.edu (dmz-mailsec-scanner-8.mit.edu [18.7.68.37]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id C1E3B17B2; Fri, 24 Jan 2014 20:56:57 +0000 (UTC) X-AuditID: 12074425-f79906d000000cf9-2f-52e2d2651911 Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) (using TLS with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP id 82.38.03321.562D2E25; Fri, 24 Jan 2014 15:51:49 -0500 (EST) Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id s0OKpmWZ002727; Fri, 24 Jan 2014 15:51:49 -0500 Received: from multics.mit.edu (system-low-sipb.mit.edu [18.187.2.37]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id s0OKpkN8009934 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Fri, 24 Jan 2014 15:51:48 -0500 Received: (from kaduk@localhost) by multics.mit.edu (8.12.9.20060308) id s0OKpk3B017448; Fri, 24 Jan 2014 15:51:46 -0500 (EST) Date: Fri, 24 Jan 2014 15:51:46 -0500 (EST) From: Benjamin Kaduk X-X-Sender: kaduk@multics.mit.edu To: Andriy Gapon Subject: Re: Fwd: Re: svn commit: r258713 - in head/sys: kern sys In-Reply-To: <52E21F94.5000104@FreeBSD.org> Message-ID: References: <52D93F91.502@FreeBSD.org> <52E21F94.5000104@FreeBSD.org> User-Agent: Alpine 1.10 (GSO 962 2008-03-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrBIsWRmVeSWpSXmKPExsUixG6nrpt66VGQwZt1MhaTXnWyW0z9uJPV YsOCQgdmjxmf5rMEMEZx2aSk5mSWpRbp2yVwZdz7dIS5YKZmxYsu+wbGnYpdjJwcEgImEvNu 9bFB2GISF+6tB7K5OIQEZjNJ/Hr4H8rZyChx8kEzM4RziEli+62frBBOA6PEoVOnmUD6WQS0 JT6cmMEMYrMJqEk83tvMCjFXUWLzqUlgcREBJYnHS7+wgNjMAhoSe5r2gNnCAo4Sl6/dA6vh BJrTsGcmWC8vUHzKq11g9wkJuEr823sKbJeogI7E6v1TWCBqBCVOznwCNdNS4tyf62wTGIVm IUnNQpJawMi0ilE2JbdKNzcxM6c4NVm3ODkxLy+1SNdCLzezRC81pXQTIziAXVR3ME44pHSI UYCDUYmHd0bgwyAh1sSy4srcQ4ySHExKorxqpx8FCfEl5adUZiQWZ8QXleakFh9ilOBgVhLh nbsZKMebklhZlVqUD5OS5mBREue9xWEfJCSQnliSmp2aWpBaBJOV4eBQkuA9fhGoUbAoNT21 Ii0zpwQhzcTBCTKcB2j4A5Aa3uKCxNzizHSI/ClGRSlx3nsgCQGQREZpHlwvLMG8YhQHekWY 9yRIFQ8wOcF1vwIazAQ0eMXZByCDSxIRUlINjPJHtVx/3PwRtyliSiTnGSPHiVpcy0xPV4je LOPa8kabJ/ZV0drpN99dT78c+voCi8mdidcOqN/dk9FzyNEnTmFqxQq+fbL/rOa97yhKcEvo 5dkn+XbJ6bM2u2c8rHJf1BkzNfKOIUPKx2OttR/rw/gaM1qXXre9FlkUeePvxqr45EWKDctm 7VdiKc5INNRiLipOBAC7wmdFCwMAAA== Cc: hackers@freebsd.org, doc@freebsd.org X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 24 Jan 2014 20:56:58 -0000 On Fri, 24 Jan 2014, Andriy Gapon wrote: > > I would like to commit the following manual page update. > Could you please review it? > Thank you very much! > > -------- Original Message -------- > Message-ID: <52D93F91.502@FreeBSD.org> > Date: Fri, 17 Jan 2014 16:34:57 +0200 > From: Andriy Gapon > To: Justin T. Gibbs > CC: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org > Subject: Re: svn commit: r258713 - in head/sys: kern sys > References: <201311281856.rASIuZu8059699@svn.freebsd.org> > <3784C560-3648-4E03-93DA-9A60E3AC401D@scsiguy.com> > In-Reply-To: <3784C560-3648-4E03-93DA-9A60E3AC401D@scsiguy.com> > > 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 This "then" is a bit odd, I think the sentence is better without it. > +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. I would prefer "cannot" as a single word here, though I don't think our style guide says anything about this case. > +This can result in a deadlock if the thread blocked in > +.Fn taskqueue_drain > +is a thread that is supposed to call Is s/a/the/ correct? That is, by my reading, if the thread blocked in taskqueue_drain is only one of several that could call taskqueue_unblock, the other threads would still (eventually) do so and there is no deadlock. So the risk of deadlock would (only?) be if there is only one thread that is supposed to call taskqueue_unblock. > +.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. s/ a / the / here is needed, though, I am certain. > +The same applies to I would put another noun here, as "same caveat" or "same warning" or something like that. -Ben > +.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 > > > _______________________________________________ > freebsd-doc@freebsd.org mailing list > http://lists.freebsd.org/mailman/listinfo/freebsd-doc > To unsubscribe, send any mail to "freebsd-doc-unsubscribe@freebsd.org" >