From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id DCC8AC77B7F for ; Tue, 16 May 2023 22:47:59 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 75AA5280001; Tue, 16 May 2023 18:47:59 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 70B4F900003; Tue, 16 May 2023 18:47:59 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 5D3E8280001; Tue, 16 May 2023 18:47:59 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 4C2D1900003 for ; Tue, 16 May 2023 18:47:59 -0400 (EDT) Received: from smtpin13.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id 1BBB2A01F8 for ; Tue, 16 May 2023 22:47:59 +0000 (UTC) X-FDA: 80797607478.13.F1B54B3 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) by imf02.hostedemail.com (Postfix) with ESMTP id 2AA468000A for ; Tue, 16 May 2023 22:47:56 +0000 (UTC) Authentication-Results: imf02.hostedemail.com; dkim=pass header.d=linutronix.de header.s=2020 header.b=YFYIkcto; dkim=pass header.d=linutronix.de header.s=2020e header.b=nsnm3oFC; spf=pass (imf02.hostedemail.com: domain of tglx@linutronix.de designates 193.142.43.55 as permitted sender) smtp.mailfrom=tglx@linutronix.de; dmarc=pass (policy=none) header.from=linutronix.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1684277277; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=BtkrSYxnuRq6fiYCIde637D8KY4d2NVOuzHNW7z0qFg=; b=xp5F4d++19XNmfZCeAiTp2YggMmRmRgz9MOROvKTNFD+iaz699VUGljlpo8WV5KSXSVI+j 6YIZ2FgTZ31nDGnGzRKv86/6Q9qMHUh6ffDKLOFMjYDsW6QRbhlPDcAnnKncaX1kR7Kq8X IoRyl7oxmNLQWa2qdivOlT9g1kL5HYg= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1684277277; a=rsa-sha256; cv=none; b=3wSycI1bLyXII9KPqeCM1emGOjuRaFvH8iBs6FQf5aLOPcUPJY+kkePKSQu4UdTv3XWbIy jHu2/d1s+2IOYHlDRNTYvZ3KYY6kaPET0hCb3JCNLGrtE17qa/jq2O54jvUs6w8lyt7huT XzOp0nXO0yqXNqZMVid8siTxTY8OzRM= ARC-Authentication-Results: i=1; imf02.hostedemail.com; dkim=pass header.d=linutronix.de header.s=2020 header.b=YFYIkcto; dkim=pass header.d=linutronix.de header.s=2020e header.b=nsnm3oFC; spf=pass (imf02.hostedemail.com: domain of tglx@linutronix.de designates 193.142.43.55 as permitted sender) smtp.mailfrom=tglx@linutronix.de; dmarc=pass (policy=none) header.from=linutronix.de From: Thomas Gleixner DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1684277274; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=BtkrSYxnuRq6fiYCIde637D8KY4d2NVOuzHNW7z0qFg=; b=YFYIkcto9cPds9qu96Ubj5+T/w+4IEqS9GqLheJM3JbElVLAh7rNwB/NGbGMN0uqwjNMV3 gmJuyQ5pdbswYubgo332tN7gA8Qf6e4WGIIh0OskJ4P+egADvoNKvWfFwIfPI3JrGxyZOV fmUdF5DEBgGHrVV/x/VhpZR65p0eTNElsIe9unk7WFqMC8RyQ09kaV41A/ZJBGaSeS2Z0M KA83fx7LJl7ryiDa6h67QclG2E0YY/sdJZZ9c2kRwTN6XhbCpmMEzlJ82FcThDuGva2jnc U91IH+Qjc2Ia7VIWBqUUjrXVj9TdPf1R1cXCKLTueYnwWy4sEN3+IvzgGxC6Nw== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1684277274; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=BtkrSYxnuRq6fiYCIde637D8KY4d2NVOuzHNW7z0qFg=; b=nsnm3oFCOawHhI4D325r12isohSzO7y7xFjeebthE/ujyb8RB6nsbKoGoDRm/ZyDN73O3t Ot00+4+38JbvFVDQ== To: "Liam R. Howlett" Cc: LKML , Matthew Wilcox , linux-mm@kvack.org, Shanker Donthineni Subject: Re: your mail In-Reply-To: <20230515192708.sypitem5hzycdois@revolver> References: <87mt2cxb7y.ffs@tglx> <20230515192708.sypitem5hzycdois@revolver> Date: Wed, 17 May 2023 00:47:53 +0200 Message-ID: <875y8r7v1i.ffs@tglx> MIME-Version: 1.0 Content-Type: text/plain X-Rspamd-Queue-Id: 2AA468000A X-Rspam-User: X-Rspamd-Server: rspam06 X-Stat-Signature: 6bkaostbhtu18i3brjzdeai8zjrpu1nr X-HE-Tag: 1684277276-851133 X-HE-Meta: U2FsdGVkX1+WKbApm7RNxSeV+BDrIFHEbPjUvglUoh3ZPckQXXvY3xbfv2YREs7yvxh7GjvHklLvmpaE8yRlcPvcQRx5i7ediaMdZTXNKZ0ho9u59qLdBYbQdzLBWNKO86QKu3uJX8uPQJojLhhAaovWsi+tU1BXGbVXAjrn92HVk4XP4IarH44cwTNMgE1FHmn00u+cKCfWGIG2Qaz726ATv1flOAJmPYUFxnnTTzZJY4ofmHsTcmlJux/RlziVtn0PxPfeGpQc3mlwWMYcCQcZp+Qp+PzJCIlRROgdQLFkI2xgPRv4NfiFUeI1xLIEhkvXyLMZ6R6jJfkTG7Cf9B8bntMiryqro9H0vTad6q9vCyzfm/GlbPJ2c/p78rcXOPmdfhmewJ8djbs6DChRe1K9vjJLVURG/6lMzBCUhYY57aKS8XngmQ/X9pJc5HZAKBCIichQYgFjc7HnSsLvL13PPHI4KNZ4D/RHCbb1X6q3xwGlmx6DqVQCOpoYjjV2MW918/NnnVRQb0Zd9WpPTWquzeN3ZoxSZho/T8SKrz4G9/F64K6ko1SXEs+j2aBAfg9UUVdDjd16vBlrzP4oIBcyEx0RotxBNorD1D+gKmKK0TKZrC4rB27k7iBrTB4x7IRy5sp0wK83WXrJWxV6WZAZMFvhtU6xqDhlWxL9Ug+fSHYouI1s3z8Why7I8A9gkZrujgkco/HQGByUOHYotUGqgRrbd9G9EFnOOg2jzlh7XVkJzitGELr+f0Tan/AOQmd/gIB/0NWBbV9hIMuPLe5nwuSiMaTUrLi90OPSmIWL/mH4VgVrZz5DyCHGjPXyjjWFwK30HmgcVu2B/rxeQi4LELyZ8Nv3HcWb0cnWx2y72IMiVcB7vnWkMpOntW9DGowwvmpDLfPQhvwGynVDrZdVec7AAX9wezODxRBLer9eh/L58qAiytKzdaZS2FnL+XyZsxMGUdLC28n0Z9M h7fzzz6m w0B7t9OQ344aY7yTdSl2ADEQY6h9Wcud7zXufgF2Owwkg0s8= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: On Mon, May 15 2023 at 15:27, Liam R. Howlett wrote: > * Thomas Gleixner [230510 15:01]: >> The documentation of mt_next() claims that it starts the search at the >> provided index. That's incorrect as it starts the search after the provided >> index. >> >> The documentation of mt_find() is slightly confusing. "Handles locking" is >> not really helpful as it does not explain how the "locking" works. > > More locking notes can be found in Documentation/core-api/maple_tree.rst > which lists mt_find() under the "Takes RCU read lock" list. I'm okay > with duplicating the comment of taking the RCU read lock in here. Without a reference to the actual locking documentation such comments are not super helpful. >> Fix similar issues for mt_find_after() and mt_prev(). >> >> Remove the completely confusing and pointless "Note: Will not return the >> zero entry." comment from mt_for_each() and document @__index correctly. > > The zero entry concept is an advanced API concept which allows you to > store something that cannot be seen by the mt_* family of users, so it > will not be returned and, instead, it will return NULL. Think of it as > a reservation for an entry that isn't fully initialized. Perhaps it > should read "Will not return the XA_ZERO_ENTRY" ? >> >> - * >> - * Note: Will not return the zero entry. > > This function "will not return the zero entry", meaning it will return > NULL if xa_is_zero(entry). If I understand correctly, this translates to: This iterator skips entries, which have been reserved for future use but have not yet been fully initialized. Right? >> @@ -6487,9 +6493,14 @@ EXPORT_SYMBOL(mtree_destroy); >> * mt_find() - Search from the start up until an entry is found. >> * @mt: The maple tree >> * @index: Pointer which contains the start location of the search >> - * @max: The maximum value to check >> + * @max: The maximum value of the search range >> + * >> + * Takes RCU read lock internally to protect the search, which does not >> + * protect the returned pointer after dropping RCU read lock. >> * >> - * Handles locking. @index will be incremented to one beyond the range. >> + * In case that an entry is found @index contains the index of the found >> + * entry plus one, so it can be used as iterator index to find the next >> + * entry. > > What about: > "In case that an entry is found @index contains the last index of the > found entry plus one" Still confusing to the casual reader like me :) "In case that an entry is found @index is updated to point to the next possible entry independent whether the found entry is occupying a single index or a range if indices." Hmm? Thanks, tglx