From patchwork Fri Nov 29 14:58:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alice Ryhl X-Patchwork-Id: 13888760 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 E7F0FD729E1 for ; Fri, 29 Nov 2024 14:58:46 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 5E3C76B0083; Fri, 29 Nov 2024 09:58:46 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 5944B6B0085; Fri, 29 Nov 2024 09:58:46 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 4346C6B0088; Fri, 29 Nov 2024 09:58:46 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0014.hostedemail.com [216.40.44.14]) by kanga.kvack.org (Postfix) with ESMTP id 21B4C6B0083 for ; Fri, 29 Nov 2024 09:58:46 -0500 (EST) Received: from smtpin10.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id B8F6F16018D for ; Fri, 29 Nov 2024 14:58:45 +0000 (UTC) X-FDA: 82839439158.10.6466172 Received: from mail-wr1-f73.google.com (mail-wr1-f73.google.com [209.85.221.73]) by imf15.hostedemail.com (Postfix) with ESMTP id 5BED1A001F for ; Fri, 29 Nov 2024 14:58:35 +0000 (UTC) Authentication-Results: imf15.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=hrXaczVU; spf=pass (imf15.hostedemail.com: domain of 3otZJZwkKCLcXifZboveidlldib.Zljifkru-jjhsXZh.lod@flex--aliceryhl.bounces.google.com designates 209.85.221.73 as permitted sender) smtp.mailfrom=3otZJZwkKCLcXifZboveidlldib.Zljifkru-jjhsXZh.lod@flex--aliceryhl.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1732892320; 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: references:dkim-signature; bh=qOHv5KJ3NWzGHishhKL1KBW7zLhmn2iCzmFqlAygBdg=; b=JDWUPxB1NSNFGbj8VyqQ1w6hyUsg0RrF4lBTRypphQ9fpkgjNEy9I+EG3fGkg60EA91nuM ynxukrldlgHJlHiryvnyTQ9Drnk9GNQGBZHnDHFQUuB48AJfBClpi7bHvinfUBaZqyLc4g f7kg+x7FJNcDkEb5zBRWCF5aJrGZVeM= ARC-Authentication-Results: i=1; imf15.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=hrXaczVU; spf=pass (imf15.hostedemail.com: domain of 3otZJZwkKCLcXifZboveidlldib.Zljifkru-jjhsXZh.lod@flex--aliceryhl.bounces.google.com designates 209.85.221.73 as permitted sender) smtp.mailfrom=3otZJZwkKCLcXifZboveidlldib.Zljifkru-jjhsXZh.lod@flex--aliceryhl.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1732892320; a=rsa-sha256; cv=none; b=UsHLqyrF+tfvugWSDVj41AjpnjsU0vhNvj2O0y0CmcZhn1y3MozB0odGAPqjDE/pLFvzIL 11mQq3YRY3l5O4uolU84WwEatY67yo+Mm9wRgGo67xwFkh6Ns9+MSMjJkiUkOVu7yMGVcs 4hMyen2/wqgvlpqaW+koWPUpqEQegY4= Received: by mail-wr1-f73.google.com with SMTP id ffacd0b85a97d-38243a4ba7cso1072982f8f.1 for ; Fri, 29 Nov 2024 06:58:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1732892322; x=1733497122; darn=kvack.org; h=cc:to:from:subject:message-id:mime-version:date:from:to:cc:subject :date:message-id:reply-to; bh=qOHv5KJ3NWzGHishhKL1KBW7zLhmn2iCzmFqlAygBdg=; b=hrXaczVUWCmmXsqFoPYZaFkZUAJ4IAi2G5RE+PLc1iFiI4BVdubWydohUxIz6jsHgf x9sN4Oh7u0qwCU7nZhhsZQ52Q9E9UTLbkIjpwvzwMdJ/RVrJsJtOgZtYSms+qV80FDbK FYt8evYDXM7p17m+ncpncLlNPpVwmOocJx21gc6dhmZ54z7tbKQAHNAK9tHsYKmV4KVP oiyvQkcd8VP7zHi0lYkeo5c5jh+8ROoTfi5at3FwLE9kFBNbWf+za0voy85Mo8ybJCcZ SNdjVxCn3O356meHCnbH8e+c+SNnn7z0G0A/w533DyEvu+oBiIHHEa0Qgh5izxYf8LCo XjDw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1732892322; x=1733497122; h=cc:to:from:subject:message-id:mime-version:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=qOHv5KJ3NWzGHishhKL1KBW7zLhmn2iCzmFqlAygBdg=; b=mQMJv5b+ma9p/bpxWiUsUMMNaXPiiv2GIupRBslSe61FYlVVuZ7IFsHT8ip3fV6Rn/ jbtECijzA8N9ZqVxIRoV+AzpTS4FyUNAWsJXoPgO0O5rCFiskQWANpBcI2xNx74QH45Y HAxBSNLhLnCuGF/dJnAvg5dR1551pjwtIYDMB2PYEHciV/vDvJ7zdpQW8IIhsJqib3Wx xP5KcCuyv8OtqwzGt0NJ78oaR8MUQc1UBCtmNjeGFXbDeKeDao8mpfeKKueSG6Y5Yi+3 A4pWtnf0IHcL19g3qZANnot7Tm3c64qYjyf5pp+rSCk7Fqdj1ecomX9qGtzLEd429gSj dmwA== X-Forwarded-Encrypted: i=1; AJvYcCV2LVjJKCRhl5QjKE562TaQdS0tXk6RadEt7qO0yLIhdgugG6GJwIfO83ukKBu/M1D79tGrPtur+Q==@kvack.org X-Gm-Message-State: AOJu0YzKoP7XusPkjZ4kNyyxz25yF4QPoGZBJLO3j7x2R9ftuqTBPUIl cWye/ywv3GF8AnMTFAA+xO//79auCatd/qrG3+PT72F8RauMxKUzYsJ27Ra1EnlGQDW1fEf01wD ZkYf3ZoAMP0s2VA== X-Google-Smtp-Source: AGHT+IEyGbf9icNVbiYCIgs6htIdvZ9baEHisAIn3VQNzAuguzrtl+kYarEDYcZgbQkeYhcN0YyYlv3eE3N1PGk= X-Received: from wrfn11.prod.google.com ([2002:a5d:588b:0:b0:385:cfa6:7962]) (user=aliceryhl job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6000:1446:b0:382:3f31:f3b9 with SMTP id ffacd0b85a97d-385c6ef3a96mr10849321f8f.56.1732892322433; Fri, 29 Nov 2024 06:58:42 -0800 (PST) Date: Fri, 29 Nov 2024 14:58:25 +0000 Mime-Version: 1.0 X-B4-Tracking: v=1; b=H4sIAJHWSWcC/32NQQ7CIBBFr9LMWoyDtaAr72Ea0sBASWhpQImm6 d3FHsDl+8l7f4VMyVOGW7NCouKzj3MFfmhAj8PsiHlTGfiJt4hcsuDzU4X0UhNN2ikTdWZGnDt CI3EQFqq5JLL+vVcffeWxOjF99pOCv/V/ryBDJqi9dPIqpG3p7mJ0gY46TtBv2/YFlPSsfLcAA AA= X-Developer-Key: i=aliceryhl@google.com; a=openpgp; fpr=49F6C1FAA74960F43A5B86A1EE7A392FDE96209F X-Developer-Signature: v=1; a=openpgp-sha256; l=5443; i=aliceryhl@google.com; h=from:subject:message-id; bh=CBop+YSCCMMojpmFezdrCbqe9ataCIhn+PD0qvGky5Y=; b=owEBbQKS/ZANAwAKAQRYvu5YxjlGAcsmYgBnSdaSIG9cS9LiAmjD0wAKIgh8j9clODX4rm3ma 4Bz/GkIar2JAjMEAAEKAB0WIQSDkqKUTWQHCvFIvbIEWL7uWMY5RgUCZ0nWkgAKCRAEWL7uWMY5 RtIYEACJO3wXaKlE0GOOBUsa1kCSaVp3F41zps55VKJizS6PXnfYGpbzKxsFUXayFq73uZ8hTVe Xv3QzlD7M0CD1kWkVEfU2AdnHtsDHlWhk5P4IbL64coA9qrhYaB/A3BC9V8yQbs4N3yk5HnT0D3 8JBebttOkvm2+5naJYryI4cRpFfrmheZrVDYYsrYqEkeSJ93I9YNQ9TbjQQknTFL0EPWSRfRbnr 27ZtoiqgkOdgZ+MVfja3l+bhfvYMRnZfGs081g8wgwnNHWV1wMQeSwmK1KLLOw7yXR1Fa4DuBaK 6PP1obG/edfrPntJmPxyCq1qL4Kh0CSARcOO8DGUKOZ/1GKWXhDgcjDwSG12Tpos38Wvw3zEhow kyF6zOp5Vhfn0l+qShziyYRZa9g8WidPT/ssSvPVRXr/WEioc85AAxrsJAxBOh6vGAHan4CzZFF JyLUcr7cW6oQWkiITqTS3RKvvrZhCli6rRw22K/VLuBfF52zM5kAZrzOGi4FQS8REhvR8DMfUWD Iu73g0XaEBYNKxLQalu3w5NIIWx9G2Blo05treMi1uOBJF8FUW0hUtEPX1VOMuWCSAIwHP5Nnk0 JeCPsW1JkEJwr5qkGi5si6oYNuJNRIkAjHy9wQGDIonJvZCkQFytCID3n/D6Pz6J4RLVT7u377i vD0YBEGWfQ2/WXw== X-Mailer: b4 0.13.0 Message-ID: <20241129-list_lru_memcg_docs-v2-1-e285ff1c481b@google.com> Subject: [PATCH v2] list_lru: expand list_lru_add() docs with info about sublists From: Alice Ryhl To: Dave Chinner , Andrew Morton , Matthew Wilcox Cc: Johannes Weiner , Nhat Pham , Qi Zheng , Roman Gushchin , Muchun Song , Michal Hocko , Shakeel Butt , linux-mm@kvack.org, cgroups@vger.kernel.org, linux-kernel@vger.kernel.org, Dave Chinner , Alice Ryhl X-Rspamd-Queue-Id: 5BED1A001F X-Stat-Signature: oj6ew3y5eo6rhdxqa3yzxd5ao7b8bixa X-Rspam-User: X-Rspamd-Server: rspam11 X-HE-Tag: 1732892315-761871 X-HE-Meta: U2FsdGVkX1/AIyzJ6UdUawz53EVQ/bwths9IjfN8Fwaxi+7nChat5YJ41VmpWTLxPTjzOP04hjZhkn+rFaFzVbhlz41PNGt6gjd3aiWV6E9Cg1vQdbVprb1LMAfsvrjxkNSHbXbjj0EAJf9cccXpFVgUIsD8PgsP1t/rW8C0sOG3wotuUUiL3NdQYpGyzqx3bE9iM0sVZJRiMtL5n81kR9mbzPNjns1Sz64SAaqSOSR6Z6OQ7EEsMuDX+ckZIJ7eizwm4Sf7Vl8xhfSJbsSeQCgCeubhZJGrbOfQPB11De4f53P/v35NqZQ+m0R2Ev3lzK92DweoHJj/7DgCuwI6jjhwCDl0CFqocjDSimsf639PXNh5uSREOzFFV2n7kg7X23LXXqkdQYkyZfuLEW6rgTdNBX4lCfehijrK3z7lQRa+HUH0z2SPA9QjsJi5tfgD3RhoSIS8Yaps3jBxX8UltFCuW+2g5dCbgB2nRYBeSoyMVWA4Eo/tnlBMT4B6YFH/08SUCYn2IgRpzrdFjZsTO0NBOrCfpq01yuMISK57dJT6ob6KUIldhxCkIbTN4OBnbEWbWdaozhxbKJUslbPdgL90O7jHHRPSuDyCorpFW/pInANRdSZ9xvgOgXgUEepCUT2gIXVSyw/m6XKiEVP+vJnP57d1A1d8u0XOegOFA/c111a5Hp0Z0OFh78bbKfW4h3q6OUiqVc3CHTlpgSvH2A0rzoUBaplhO/Or58A4K4MGJSPtWKVDBOcDRQsqTg9GtKDnO6np6gbPbYtBBLMlDvIiZ8C3lLIHRBI0QPp+gl7CugwB4aSm3aviNfk+YHwahZ6OkpfKGrPk3h7I4+Wb5bxWEWu1Q/enMx5w8tkFSLQBTaNl0FweDHeP7sT3ac8K+ufYy7duSrF5dZ85r7qeiAQbl+MqSHJu7yqwbjjYQbO9Z/iImASTyp8X5XDZbUZPV0BsPlCMdE4PcVKvnXi xOXkY/aV SfeLWTl5/5Vy1dq9gnem4wHs94NvOiLjJ3o8V3UiEmFICnwo2rjUzAuSIiQ+F3oGkt7xxlG9sLhC98Dp+d7XYXTveC8GXzag1AbWel+txCxjq7pOekmyH3ZV79etfUPIqGG9e1Cabo9q2ky+R4dQyXtHtdehtX7HtCpLLp1iqk+0BN0uF6xvRw+WDWTbd0D6/0vh2gE4RkgDHCPtAjZwBBQcCGKOj6z3BIV2Mb/yqAAAVkQFoHSA6ePDtLjvuRo7n44gh6Hd71kGrlGyb+2nCrz6KAYRABaPPFGV7b5fzbBBC6WRNRhvbyFuRUrsnxuDbU7CLxmxPYc4jF2Xi+SWD+wf7X0D57qbc9lJuga+QMyWMFXosv4mUJklgjfztJCLmmKn3XiiF1kXzVWhMrGos7/BkeFOWDBpxz8ODK138i8oe5GlR6qufRX1Sp7Vf6M0gIuUntZFsKUPH69Nl2TDkBhjt8qzHbTAbGO6SfuJn+03LskZ5lUNOqy52U4tc0DP4dyRiOuowVbzxvDMTMa/tGWn0b3A+d5et2ueWpNZxIR4lYTqMSOZijz0xNCkVIC7lnYS6IMNuSivfzuTAh1HaU/Web0MK0fPHXwPbq2tOMFFjxturMR5ylZJnZGiiPxda6ZXj/QXs+42XMCcOw99cqHuRJxz3CITAGNS2 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: List-Subscribe: List-Unsubscribe: The documentation for list_lru_add() and list_lru_del() has not been updated since lru lists were originally introduced by commit a38e40824844 ("list: add a new LRU list type"). Back then, list_lru stored all of the items in a single list, but the implementation has since been expanded to use many sublists internally. Thus, update the docs to mention that the requirements about not using the item with several lists at the same time also applies not using different sublists. Also mention that list_lru items are reparented when the memcg is deleted as discussed on the LKML [1]. Also fix incorrect use of 'Return value:' which should be 'Return:'. Link: https://lore.kernel.org/all/Z0eXrllVhRI9Ag5b@dread.disaster.area/ [1] Reviewed-by: Dave Chinner Signed-off-by: Alice Ryhl --- Changes in v2: - Don't reword "if the list was updated". - Update 'Return value:' to 'Return:' on list_lru_*_obj() functions. - Link to v1: https://lore.kernel.org/r/20241128-list_lru_memcg_docs-v1-1-7e4568978f4e@google.com --- include/linux/list_lru.h | 44 +++++++++++++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 11 deletions(-) --- base-commit: 7af08b57bcb9ebf78675c50069c54125c0a8b795 change-id: 20241128-list_lru_memcg_docs-d736e1d81a7f Best regards, diff --git a/include/linux/list_lru.h b/include/linux/list_lru.h index 05c166811f6b..fe739d35a864 100644 --- a/include/linux/list_lru.h +++ b/include/linux/list_lru.h @@ -91,13 +91,24 @@ void memcg_reparent_list_lrus(struct mem_cgroup *memcg, struct mem_cgroup *paren * @memcg: the cgroup of the sublist to add the item to. * * If the element is already part of a list, this function returns doing - * nothing. Therefore the caller does not need to keep state about whether or - * not the element already belongs in the list and is allowed to lazy update - * it. Note however that this is valid for *a* list, not *this* list. If - * the caller organize itself in a way that elements can be in more than - * one type of list, it is up to the caller to fully remove the item from - * the previous list (with list_lru_del() for instance) before moving it - * to @lru. + * nothing. This means that it is not necessary to keep state about whether or + * not the element already belongs in the list. That said, this logic only + * works if the item is in *this* list. If the item might be in some other + * list, then you cannot rely on this check and you must remove it from the + * other list before trying to insert it. + * + * The lru list consists of many sublists internally; the @nid and @memcg + * parameters are used to determine which sublist to insert the item into. + * It's important to use the right value of @nid and @memcg when deleting the + * item, since it might otherwise get deleted from the wrong sublist. + * + * This also applies when attempting to insert the item multiple times - if + * the item is currently in one sublist and you call list_lru_add() again, you + * must pass the right @nid and @memcg parameters so that the same sublist is + * used. + * + * You must ensure that the memcg is not freed during this call (e.g., with + * rcu or by taking a css refcnt). * * Return: true if the list was updated, false otherwise */ @@ -113,7 +124,7 @@ bool list_lru_add(struct list_lru *lru, struct list_head *item, int nid, * memcg of the sublist is determined by @item list_head. This assumption is * valid for slab objects LRU such as dentries, inodes, etc. * - * Return value: true if the list was updated, false otherwise + * Return: true if the list was updated, false otherwise */ bool list_lru_add_obj(struct list_lru *lru, struct list_head *item); @@ -125,8 +136,19 @@ bool list_lru_add_obj(struct list_lru *lru, struct list_head *item); * @memcg: the cgroup of the sublist to delete the item from. * * This function works analogously as list_lru_add() in terms of list - * manipulation. The comments about an element already pertaining to - * a list are also valid for list_lru_del(). + * manipulation. + * + * The comments in list_lru_add() about an element already being in a list are + * also valid for list_lru_del(), that is, you can delete an item that has + * already been removed or never been added. However, if the item is in a + * list, it must be in *this* list, and you must pass the right value of @nid + * and @memcg so that the right sublist is used. + * + * You must ensure that the memcg is not freed during this call (e.g., with + * rcu or by taking a css refcnt). When a memcg is deleted, list_lru entries + * are automatically moved to the parent memcg. This is done in a race-free + * way, so during deletion of an memcg both the old and new memcg will resolve + * to the same sublist internally. * * Return: true if the list was updated, false otherwise */ @@ -142,7 +164,7 @@ bool list_lru_del(struct list_lru *lru, struct list_head *item, int nid, * memcg of the sublist is determined by @item list_head. This assumption is * valid for slab objects LRU such as dentries, inodes, etc. * - * Return value: true if the list was updated, false otherwise. + * Return: true if the list was updated, false otherwise. */ bool list_lru_del_obj(struct list_lru *lru, struct list_head *item);