Date: Fri, 24 Jan 2014 10:48:47 +0000 From: Veronica Yuen <veronicayeun1@gmail.com> To: www@freebsd.org Subject: www.freebsd.org Message-ID: <089e013cb8d6455f3504f0b51a6f@google.com>
next in thread | raw e-mail | index | archive | help
PGRpdiBkaXI9Imx0ciI+PHA+SGksPC9wPjxkaXY+PHA+SSB3YW50ZWQgdG8gc2VuZCB5b3UgYSBx dWljayBub3RlLiBXaXRoIGEgIA0KZmV3IHNpbXBsZSBjaGFuZ2VzIHRvIG1ha2UgeW91ciBzaXRl IG1vcmUgU0VPLWZyaWVuZGx5IEmSbSBzdXJlIHlvdSBjYW4gIA0KY29udmVydCBtb3JlIHZpc2l0 b3JzIGludG8gbGVhZHMgYW5kIGdldCBpdCBwbGFjZWQgaGlnaGVyIGluIHRoZSBvcmdhbmljICAN CnNlYXJjaCByZXN1bHRzLCBmb3Iga2V5d29yZHMgdGhhdCBtYXR0ZXIgdG8geW91IHRoZSBtb3N0 LjwvcD4NCg0KDQo8L2Rpdj48ZGl2PjxwPldlIGFyZSBhIExvY2FsIGJhc2VkIGNvbXBhbnkgd2l0 aCBncmVhdCBpbi1ob3VzZSB0ZWNobmljYWwgIA0KdGVhbSB3aG8gcmVhbGx5IGtub3cgdGhlaXIg c3R1ZmYgYWJvdXQgc2VhcmNoIGVuZ2luZSAgDQpvcHRpbWl6YXRpb24uoDwvcD48L2Rpdj48cD5X b3VsZCB5b3UgbGlrZSBhIGJpdCBtb3JlIGluZm9ybWF0aW9uIGFib3V0IGhvdyAgDQp0byBnaXZl IHlvdXIgd2Vic2l0ZSBhIGJvb3N0IHdpdGggYmV0dGVyIFNFTz88L3A+DQoNCg0KPHA+QmVzdCBy ZWdhcmRzLDwvcD48cD48c3BhbiBzdHlsZT0iZm9udC1mYW1pbHk6JiMzOTtib29rICANCmFudGlx dWEmIzM5OyxwYWxhdGlubztjb2xvcjpyZ2IoMTM2LDEzNiwxMzYpIj48Zm9udCBzaXplPSI0Ij5W ZXJvbmljYSAgDQpZdWVuPC9mb250Pjxicj48c3BhbiAgDQpzdHlsZT0iY29sb3I6cmdiKDAsMCww KTtmb250LWZhbWlseTphcmlhbCxoZWx2ZXRpY2Esc2Fucy1zZXJpZjtmb250LXNpemU6eHgtc21h bGwiPlNFTy9XRUIgIA0KU3BlY2lhbGlzdDwvc3Bhbj48L3NwYW4+PC9wPg0KDQoNCjx0YWJsZSBz dHlsZT0ibWFyZ2luLWxlZnQ6YXV0bzttYXJnaW4tcmlnaHQ6YXV0byIgIA0KYm9yZGVyPSIwIj48 dGJvZHk+PHRyPjx0ZD6goKCgoKCgoKCgPC90ZD48dGQgIA0Kc3R5bGU9ImJhY2tncm91bmQtY29s b3I6cmdiKDcyLDExNCwyMzMpIj48Yj6gPC9iPqA8c3BhbiAgDQpzdHlsZT0iZm9udC1mYW1pbHk6 JiMzOTt0aW1lcyBuZXcgIA0Kcm9tYW4mIzM5Oyx0aW1lcztmb250LXNpemU6bGFyZ2U7Y29sb3I6 cmdiKDI1NSwyNTUsMjU1KSI+Uzwvc3Bhbj48Yj6goDwvYj48L3RkPg0KDQoNCjx0ZCBzdHlsZT0i YmFja2dyb3VuZC1jb2xvcjpyZ2IoMjU1LDAsNTEpIj6gPHNwYW4gIA0Kc3R5bGU9ImZvbnQtZmFt aWx5OiYjMzk7dGltZXMgbmV3IHJvbWFuJiMzOTssdGltZXM7Zm9udC1zaXplOmxhcmdlIj48c3Bh biAgDQpzdHlsZT0iZm9udC1zaXplOngtbGFyZ2U7Y29sb3I6cmdiKDI1NSwyNTUsMjU1KSI+RTwv c3Bhbj6gPC9zcGFuPjwvdGQ+PHRkICANCnN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOnJnYigxMDEs MjM1LDE5KSI+DQoNCg0KPHNwYW4gc3R5bGU9ImZvbnQtc2l6ZTpsYXJnZTtjb2xvcjpyZ2IoMjU1 LDI1NSwyNTUpO2ZvbnQtZmFtaWx5OiYjMzk7dGltZXMgIA0KbmV3IHJvbWFuJiMzOTssdGltZXMi PqBPoDwvc3Bhbj48L3RkPjx0ZCAgDQpzdHlsZT0idGV4dC1hbGlnbjpjZW50ZXIiPqCgoCCgIKAg oCCgPC90ZD48L3RyPjx0cj48dGQgY29sc3Bhbj0iNSIgIA0Kc3R5bGU9ImJhY2tncm91bmQtY29s b3I6cmdiKDAsMCwwKTt0ZXh0LWFsaWduOmNlbnRlciI+DQoNCg0KPGI+PHNwYW4gIA0Kc3R5bGU9 ImZvbnQtZmFtaWx5OnRhaG9tYSxhcmlhbCxoZWx2ZXRpY2Esc2Fucy1zZXJpZjtjb2xvcjpyZ2Io MjU1LDI1NSwyNTUpIj5TZWFyY2ggIA0KRW5naW5lIE9wdGltaXphdGlvbjwvc3Bhbj48L2I+PC90 ZD48L3RyPjwvdGJvZHk+PC90YWJsZT48cCAgDQpzdHlsZT0idGV4dC1hbGlnbjpjZW50ZXIiPjxz cGFuICANCnN0eWxlPSJmb250LWZhbWlseTphcmlhbCxoZWx2ZXRpY2Esc2Fucy1zZXJpZjtmb250 LXNpemU6eHgtc21hbGw7Y29sb3I6cmdiKDEzNiwxMzYsMTM2KSI+V2UgIA0KcmVzcGVjdCB5b3Vy IHByaXZhY3kgYW5kIHdhbnQgdG8gbWFrZSBzdXJlIHlvdSBhcmUgYXdhcmUgb2YgYSBmZXcgdGhp bmdzLiAgDQpCeSByZXBseWluZyB0byB0aGlzIGVtYWlsLCB5b3UgYXV0aG9yaXplIG91ciBIb25n IEtvbmcgYWZmaWxpYXRlcyB0aGF0IGNhbiAgDQpoZWxwIHdpdGggeW91ciBwcm9qZWN0IHRvIGNh bGwgeW91IGF0IHRoZSBudW1iZXIgeW91IHByb3ZpZGVkLCBhbmQgeW91ICANCnVuZGVyc3RhbmQg dGhhdCB0aGV5IG1heSB1c2UgYXV0b21hdGVkIHBob25lIHRlY2hub2xvZ3kgdG8gY2FsbCB5b3Uu IEF0IG5vICANCnRpbWUgYXJlIHlvdSByZXF1aXJlZCB0byBtYWtlIGEgcHVyY2hhc2UuPC9zcGFu PjwvcD4NCg0KDQo8ZGl2IHN0eWxlPSJ0ZXh0LWFsaWduOmNlbnRlciI+PHNwYW4gIA0Kc3R5bGU9 ImZvbnQtZmFtaWx5OmFyaWFsLGhlbHZldGljYSxzYW5zLXNlcmlmO2ZvbnQtc2l6ZTp4eC1zbWFs bDtjb2xvcjpyZ2IoMTM2LDEzNiwxMzYpIj5VbnN1YnNjcmliZTwvc3Bhbj48L2Rpdj48L2Rpdj4N Cg== From owner-freebsd-doc@FreeBSD.ORG Fri Jan 24 14:16:37 2014 Return-Path: <owner-freebsd-doc@FreeBSD.ORG> Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 0A63917D; Fri, 24 Jan 2014 14:16:37 +0000 (UTC) Received: from citadel.icyb.net.ua (citadel.icyb.net.ua [212.40.38.140]) by mx1.freebsd.org (Postfix) with ESMTP id 39092112B; Fri, 24 Jan 2014 14:16:35 +0000 (UTC) Received: from porto.starpoint.kiev.ua (porto-e.starpoint.kiev.ua [212.40.38.100]) by citadel.icyb.net.ua (8.8.8p3/ICyb-2.3exp) with ESMTP id QAA11609; Fri, 24 Jan 2014 16:16:34 +0200 (EET) (envelope-from avg@FreeBSD.org) Received: from localhost ([127.0.0.1]) by porto.starpoint.kiev.ua with esmtp (Exim 4.34 (FreeBSD)) id 1W6hYg-0006By-1Q; Fri, 24 Jan 2014 16:16:34 +0200 Message-ID: <52E27589.8050302@FreeBSD.org> Date: Fri, 24 Jan 2014 16:15:37 +0200 From: Andriy Gapon <avg@FreeBSD.org> User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:24.0) Gecko/20100101 Thunderbird/24.2.0 MIME-Version: 1.0 To: doc@FreeBSD.org Subject: taskqueue(9) manual page update References: <52D93F91.502@FreeBSD.org> In-Reply-To: <52D93F91.502@FreeBSD.org> X-Enigmail-Version: 1.6 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit Cc: hackers@FreeBSD.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Documentation project <freebsd-doc.freebsd.org> List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-doc>, <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe> List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc/>; List-Post: <mailto:freebsd-doc@freebsd.org> List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help> List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>, <mailto:freebsd-doc-request@freebsd.org?subject=subscribe> X-List-Received-Date: Fri, 24 Jan 2014 14:16:37 -0000 [I intended to change the subject line and forgot, so this is a dupe.] 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 <avg@FreeBSD.org> To: Justin T. Gibbs <gibbs@scsiguy.com> 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 +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?089e013cb8d6455f3504f0b51a6f>