From patchwork Thu Nov 28 12:12:11 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alice Ryhl X-Patchwork-Id: 13887967 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 E7F64D69102 for ; Thu, 28 Nov 2024 12:12:32 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 5722C6B0088; Thu, 28 Nov 2024 07:12:32 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 521B06B0089; Thu, 28 Nov 2024 07:12:32 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 3EA1C6B008C; Thu, 28 Nov 2024 07:12:32 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 1F12A6B0088 for ; Thu, 28 Nov 2024 07:12:32 -0500 (EST) Received: from smtpin26.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay05.hostedemail.com (Postfix) with ESMTP id 89D874134D for ; Thu, 28 Nov 2024 12:12:31 +0000 (UTC) X-FDA: 82835391492.26.CD860AF Received: from mail-wr1-f73.google.com (mail-wr1-f73.google.com [209.85.221.73]) by imf17.hostedemail.com (Postfix) with ESMTP id 5D4F940006 for ; Thu, 28 Nov 2024 12:12:24 +0000 (UTC) Authentication-Results: imf17.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=gHQEJNVZ; spf=pass (imf17.hostedemail.com: domain of 3LF5IZwkKCEsnyvpr4Buyt11tyr.p1zyv07A-zzx8npx.14t@flex--aliceryhl.bounces.google.com designates 209.85.221.73 as permitted sender) smtp.mailfrom=3LF5IZwkKCEsnyvpr4Buyt11tyr.p1zyv07A-zzx8npx.14t@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=1732795946; 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=xv9Mnsqw0yP552va4yFfmGxxYoQFMLmXfy+o8MwyuvI=; b=eFTi7h2hAd5mT5rFuVJMf1LaPLPq4FQK/u8vtk0wkTB18biAqmMzUVukq1k5/AdmA5WV5v DVetZJiIMsrZtoeR7awUuAieRNvfoenLH+jlTjTz0bkPWKRkPgFwQpDtrxa7PkD8SXxoQF MoCIxcU/WcoSBX+TwNzuexVYmzuLw50= ARC-Authentication-Results: i=1; imf17.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=gHQEJNVZ; spf=pass (imf17.hostedemail.com: domain of 3LF5IZwkKCEsnyvpr4Buyt11tyr.p1zyv07A-zzx8npx.14t@flex--aliceryhl.bounces.google.com designates 209.85.221.73 as permitted sender) smtp.mailfrom=3LF5IZwkKCEsnyvpr4Buyt11tyr.p1zyv07A-zzx8npx.14t@flex--aliceryhl.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1732795946; a=rsa-sha256; cv=none; b=ddyPgyPzN2i+Yvu/AMmkTn992rw4VN4IsMIPp6wem0+bPNNw9MfmdTHWZ9qKdwJlV/mEHc a65jfTyETiLVLRWelzEY0yHzeI8PvvLvDTr6X8r1R9jPnZTwl9kZeBfmx9udqzbgHR2hLR n/kreOsFvaa9Qu0wcL8ohftrp/gqiSk= Received: by mail-wr1-f73.google.com with SMTP id ffacd0b85a97d-3825a721afaso466161f8f.0 for ; Thu, 28 Nov 2024 04:12:29 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1732795948; x=1733400748; darn=kvack.org; h=cc:to:from:subject:message-id:mime-version:date:from:to:cc:subject :date:message-id:reply-to; bh=xv9Mnsqw0yP552va4yFfmGxxYoQFMLmXfy+o8MwyuvI=; b=gHQEJNVZGnqaNo+nv2NPOjn3/Bg4Zqx8w9BvS8EqlnrnoqnmdWD7o7ilzoRZb5Xh/l g43FzigphZtf9tAvu+XqIknViS2jYJsB+DZ/qIiKCF+5BYhYpG+VyLaf+k8hsXWk74q7 DS+ahPInLoGWIZBVWQeCzDpE6a5Zs6MN4v8Eqd+gMESNA/AQdu5bDzAbRRuLNcH/w2V5 HaIGFEymD0QtGmPFf6HQt6TPkCMoixMFdnLB2sUdwpifduiNDcgFFl2Zi4ggsRQ0p9qh oJVttNxEHytiH0craIwOLAlj1kMwiPXbU799hMN+5UyWa5OtxRIqqqS9ZaZ3nCiaO3mp joOw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1732795948; x=1733400748; h=cc:to:from:subject:message-id:mime-version:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=xv9Mnsqw0yP552va4yFfmGxxYoQFMLmXfy+o8MwyuvI=; b=cGf6uTm4v2PWrGNAYRU0aN+Il8rN+k/420VD3d0awnuYJ8in9vnlV7eMOKfjbfpZ58 EMJtHf/L0cH2xGIiPNq12mlGxzHmTlcSfSRq4L/HrxqndDN8SfL2lk0gBfpcsjIAHy8t dIxEiR5sUsoewaK8FJZRfojF05+qeejzjoXflsOodk4of8cugkn+xum/1JVlOvnRlGjn elKhNWAqhHFg4sJmuweI0WUOtQyLpUQsjQ4Tam9IVfOY5Jj73HXP+RqHOVL9POvWpGEH Ead0mo1/3NAhAwucJFQwzDCbgeQI0HN2LkDAL5Ns/HeKaUQLvHTSk1VPXFrHZwrNfTi1 Xfrw== X-Forwarded-Encrypted: i=1; AJvYcCUUVvEfdIzbAWRRPrVG9Evz/FrKqZkrtmZYTTsFvdmV/pjLrja4Vqp8C6KdqbwEZqTuNMvdj2d66w==@kvack.org X-Gm-Message-State: AOJu0YxDuUWUNxe+WZnfFXzqH6lelIfQrMd/SguVhsspoKVpLZqbV/Ti NxGvLAI9oeo74pmItbFobj/xODMfLEZmkFiGyNfqru11PcI0yl+s7lYbDD81DHxY9qz48OeSFkV Hkt+bxjyBwp23Xw== X-Google-Smtp-Source: AGHT+IE8+KYnkF58GMuTj0VAu4E6cZL1TCWj/R8Fz3NdRbDJvaqchxbrbwH7siNgqYgBqqkBkJUSkwuvPxhg4xI= X-Received: from wmpk41.prod.google.com ([2002:a05:600c:829:b0:434:a2fb:effe]) (user=aliceryhl job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6000:1543:b0:382:4f6e:a57a with SMTP id ffacd0b85a97d-385c6edc83emr6304046f8f.54.1732795948065; Thu, 28 Nov 2024 04:12:28 -0800 (PST) Date: Thu, 28 Nov 2024 12:12:11 +0000 Mime-Version: 1.0 X-B4-Tracking: v=1; b=H4sIABpeSGcC/x3MSwqAMAwA0atI1hZMFSteRaRIG2vAH42KIN7d4 vItZh4QikwCbfZApIuFtzUB8wzcNKyBFPtk0IWuEHWjZpbDzvG0Cy0uWL85Ud6UNaFvcDAjpHK PNPL9X7v+fT/wu1jwZQAAAA== X-Developer-Key: i=aliceryhl@google.com; a=openpgp; fpr=49F6C1FAA74960F43A5B86A1EE7A392FDE96209F X-Developer-Signature: v=1; a=openpgp-sha256; l=5452; i=aliceryhl@google.com; h=from:subject:message-id; bh=/LGrZOzJI+6kS93veQaIwzlwY/GP+eS2PE8NhODdl4Q=; b=owEBbQKS/ZANAwAKAQRYvu5YxjlGAcsmYgBnSF4idTCr3X7DVYiatk5PpMqpcyL1UCi/4Liig TTZhVH50k6JAjMEAAEKAB0WIQSDkqKUTWQHCvFIvbIEWL7uWMY5RgUCZ0heIgAKCRAEWL7uWMY5 RlfoEAC2nrOfgVrSgeKaMotPVEFfEs1t+E8RZVYdgNMXJlR9wKJeRs/IhzKbfMPKaJaxHkDfK6u ZShkjb6U/pHHXN8N3ZnpC1xTj1rnlEhny0ocAfqDVNNZyygvGlc1ZcpxlKq6LCndOYQ0s/Dv1fB KKOlQV0yB7p5k1wA7Phun42TnzLBPZwz664FT+92i04GYq5j6nMQJe0l8jDnO8PqYgVhBYbIeMz pQKbJZeMhsYQ4T1iDlSPYIPgRZ/VBCAiBsNtQzEMmUjD14Rcia5uZszmKK/ogQXt+HYnAAWSlkb D52cTuFqsvGsFzUG7wPgoXYs0SvOVCWNRsGHqXsFYM2a2ayv/KionikvwCQlhvAKB7bi2jMC/x5 QiYLRoQGPt/S4ih1zHj56BUc8Xa+jwgdtz5txJhQ6uUkFFcK15LkeOousMyWJQiWizccZpAnZTo r96pEaZKPbSGOr/aPCDIpX0cyYxaW5iajzkYR1bBlDz4RD9Nb1FHcfjebYqJpFxZHKxRF6Ausax iKQKah8XTF25idJ9cmT7TD3WzLTnI402VrO+2jYH2vgXAUHYup1R5FZBitPcShJLDfAj+QNTX4y LezjQ7WkYc+mxHnTgAzNEcUR3PlEgpgsSpH8o5Vkpo9uld9MOjLkkpvZnHrfBE4msertzBYHWpa bPXky9OsM8tPadQ== X-Mailer: b4 0.13.0 Message-ID: <20241128-list_lru_memcg_docs-v1-1-7e4568978f4e@google.com> Subject: [PATCH] list_lru: expand list_lru_add() docs with info about sublists From: Alice Ryhl To: Dave Chinner , Andrew Morton 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, Alice Ryhl X-Rspamd-Queue-Id: 5D4F940006 X-Stat-Signature: eha7r8eab8q6emwhhzgmtuc41e8nnrhz X-Rspam-User: X-Rspamd-Server: rspam11 X-HE-Tag: 1732795944-432928 X-HE-Meta: U2FsdGVkX1+Vm5kQ+8Emm6wJRYbizjQk1duFm3DBCAGZpBdUR9F9TG6fl2aaKpCn79qb+Em4NFG9vngUZeXRj4XRin7qGqLrgYCTjmP69ght0KhvSUY1QpCJK6IVuDpZqph0Im2pjdndLwEwLDofj6TcVoDgl+9WYfhcPM5bSu+/7dfLdx1r4vCxXKyW9UZukibGtombhGGaaHam5Vx8nJA+c+6sTnnBgB/8dLPDqcpxqjxB3KZ0p8svEjXaRYaWs6UmUgEmGRgEJ9O8u8udmkhcF1gVHOA2YWBvQzF+D8UqtMofcXzj1d7tGf0SKQ1SW082yoDhfWqpnvRd0RqODl98RuS+l81nVtZRPdLQTWz8ZEs+J+cZl3aAEPeNoQGu0NwiZb4nVCz8QzVNEChAmGFEHefJ32t2vx1JSZwRhq4CvjRvg9H9P6/DvLhodPdbUntAcAwEGpWlfdOVNmjU/uW4FVxUXDcKkiImKHhZBmjqxAUGX8hC6wEYl4caiuFi0+a6GqF6nZNTgM0mofMu8wcJKFmqcQ4NmxZ0Gqz54J8pN5XtzMUdAZZ/LSYczZkEDo6uPeCuyrJg8sZhA7XO55/DnPV75bhh+I3GmAOtJjcYq4D/9/OJ06JOSTxdsY7w8jbpIexl3oYatOTmsAlVtlKlYi/jq0HgOIMWO/w8oxNu8eFkMtGLLidkkrHoiPnvs+Dfs+jtutnY1gqpFbTjwh7Ngh9MVtVsU6YVqKP5P9bXqfYPxw6FrN5hBrg/dyoKn5WEUXlp0R65e9pD75kpS88eHITZAlMAXu1psFwQqRvaEiHznPuCY7NLDK5S2IgsdT3xvJDIvqV5728ztLoWbEH0MldGKUodaj9RYUAtXAddEtK+y2YSXy8KXBxxj0/yBO8b0lxk5P/mkU1248bYYV/Wo9porfFtsF3FBtR3MJ0MYX5wUK6RzFmcxlDw6km80ibMU2bkbdgKkjvDA4i u/Vc2Tif N7uBArVvohhcrQ1D9h/2h1fK9mnlbcaSO3yLxXQ0tbLe8XsS2JFn0YznWAJ4ieA45hQKfG9Vr7Izj/lk/N5Ubuz/gBEPr8aOA0hP5Rv0sP0HCumxmHmJprA3NLyq+qEYhbzI9YGlPCy0j59kqivYJwCnqY2XyHuKFBVPqoQM12teZ64BUMs+TjIetJMR2jQpH5Ktrr/JUOoxxu1QIud9eVj2c3fYah35MBGCbTfwT1JqrX/VlVWGLR55EJO94lNGgtNRkg7uQbf70i/Jy3FidAIcYOrcSk4lTYZSo6wsfwvPiYgB4iajMDH/bq8M13SUtV+oJ2gtgu8mEq972MT/1UHpqkRb34SBUQyExX+BLx2aIXNqCgKOKkWJCNgGM7Y7kBzqwperVwhMbyjX+zBX9aqKUJfSRwmxMxNsGZVY7jQ4J6GnTD5QJminoOaSqd/10lJ3fsZI1Qa5c0LAZYCU8dRPjH4mNnv3WmrUKeNBEvL5i6zwphtayKbUeGpM6dwVRDftiQZFefv7H7HtlPzTdStCSs9hRZqVdh8q/1RsSAPUC7ODXuYYmkEplTfN+qVsBHSBevby+1VKVj9N1l/8Tqsm4QxMaQNq1ofTnCrfkpqXIxZJ7ea+ej5J6c6zoW8n83O+VM6t300uXa9I= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000001, 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]. Link: https://lore.kernel.org/all/Z0eXrllVhRI9Ag5b@dread.disaster.area/ [1] Signed-off-by: Alice Ryhl --- include/linux/list_lru.h | 48 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 13 deletions(-) --- base-commit: b86545e02e8c22fb89218f29d381fa8e8b91d815 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..d4fc967247ae 100644 --- a/include/linux/list_lru.h +++ b/include/linux/list_lru.h @@ -91,15 +91,26 @@ 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. * - * Return: true if the list was updated, false otherwise + * 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 value: true if the item was added, false otherwise */ bool list_lru_add(struct list_lru *lru, struct list_head *item, int nid, struct mem_cgroup *memcg); @@ -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 value: true if the item was added, false otherwise */ bool list_lru_add_obj(struct list_lru *lru, struct list_head *item); @@ -125,10 +136,21 @@ 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 + * Return value: true if the item was removed, false otherwise */ bool list_lru_del(struct list_lru *lru, struct list_head *item, int nid, struct mem_cgroup *memcg); @@ -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 value: true if the item was removed, false otherwise. */ bool list_lru_del_obj(struct list_lru *lru, struct list_head *item);