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 CE37EC36010 for ; Sat, 5 Apr 2025 15:23:55 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 851946B0005; Sat, 5 Apr 2025 11:23:54 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 7FEAF6B0007; Sat, 5 Apr 2025 11:23:54 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 6C6A46B0008; Sat, 5 Apr 2025 11:23:54 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 491866B0005 for ; Sat, 5 Apr 2025 11:23:54 -0400 (EDT) Received: from smtpin04.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay10.hostedemail.com (Postfix) with ESMTP id 7AB91C1301 for ; Sat, 5 Apr 2025 15:23:54 +0000 (UTC) X-FDA: 83300360388.04.C216462 Received: from mail-pl1-f175.google.com (mail-pl1-f175.google.com [209.85.214.175]) by imf10.hostedemail.com (Postfix) with ESMTP id 8B8C4C0006 for ; Sat, 5 Apr 2025 15:23:52 +0000 (UTC) Authentication-Results: imf10.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=C5FZkcSM; spf=pass (imf10.hostedemail.com: domain of miguel.ojeda.sandonis@gmail.com designates 209.85.214.175 as permitted sender) smtp.mailfrom=miguel.ojeda.sandonis@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1743866632; 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:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=bRltu7iwQQEMx4zzV+XyJNaqulGjEr9JTBPg2eBuL3o=; b=Bb5upaAWbV01I2vWLUFE2epCdEtJ0lJ9+iLILp4h3cng6lx9rCJM0DRpQRzW/NgdPdk2DD Nb2iFt5cFvnVG4hF4+eqeqMlxRTsFMr5vw242UCsxholnVlIN1XWIkYa4Ga6JCmfINCQAq 9zk7szqHkJGw//qC79SG64HT3UmW/Ys= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1743866632; a=rsa-sha256; cv=none; b=ozfn2K7sFLfJqjd5l1m8NvzsuKf5Z87sSTSs3KF1IwYfDUfGOiINzwaeGuzfSIJ8fMDTcE NRvjnRX1wb7eh3yHKl4R9zqgmrkA9F/qGSBZQ9Z29Xz8MSHaIXoGf6qTdtEQ+K84E4C+q0 aKiix6YLHLZQpssAm3gIGneqVqW+8mw= ARC-Authentication-Results: i=1; imf10.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=C5FZkcSM; spf=pass (imf10.hostedemail.com: domain of miguel.ojeda.sandonis@gmail.com designates 209.85.214.175 as permitted sender) smtp.mailfrom=miguel.ojeda.sandonis@gmail.com; dmarc=pass (policy=none) header.from=gmail.com Received: by mail-pl1-f175.google.com with SMTP id d9443c01a7336-2241c95619eso4898265ad.0 for ; Sat, 05 Apr 2025 08:23:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1743866631; x=1744471431; darn=kvack.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=bRltu7iwQQEMx4zzV+XyJNaqulGjEr9JTBPg2eBuL3o=; b=C5FZkcSMTCh/WnMhgduexYVamgIksDPRULWU9XXR2eBLgA7fLcuXFPyR4WpcAXThYB zNCpHSO1IrOgB/pUvijh8dsI0heAIVximyTkqpKUiiVePFa9UAOduqPvgsFFIb4s10b5 0pocVWesyjbaJxXcxRZj+l8zLurQgG8SXBtUgk+D4AsFIxT9QBTvLlVCpE9Trga3jXqc SofMdgjY+hZRON/Q4CwhqCfYcZH3BXCIo0M44Ij8Cz5QrIubvDiu4NRhKJE4SD6wr4sl xbREJDAsZi+3CKlnFvVcNDMnNrFy3T2IF/56AlcOAu5NRyKW4UHDdW1QG5+dOAFye0oj 8dXw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1743866631; x=1744471431; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bRltu7iwQQEMx4zzV+XyJNaqulGjEr9JTBPg2eBuL3o=; b=iMVkRywSpOdv3+X31vx0ld6mWRT8nY+wIGM8PQE+ezuE88lhb5APvHBW/LcAEudi26 zzGOWhihCMTghz5TbkIkTaQvSAJ2dFnKVmcJeDBjEDJs8Y0t5KVIjXCWOuK2eGaCyPax 9vDzeWl06nQQXX+ogo84TvArdWHfvTzethYpWxtIWoE18Ju/FNwj9kN6ltwbUhWasrW1 8jcowtsGaPg4LqOjt3Pu3eiXt3fafFUkT+BNTqhHjSgljLiHqF5jEIb+NnhgnM0bOWsW 0m3mFXePeZ/iFNQtSpGUn3chJGJKpttE37+aMJdzk3/4Q2X/K7ijdAV+bjJkLwd3+K2A HMWw== X-Forwarded-Encrypted: i=1; AJvYcCWwEk4cF/qAgf8uuDcU2vzhlvsq9bLWmL7fQ1KF8bTYv30ZXEh7HP74RYn3Tvr2yrlmwhkmf/xSiQ==@kvack.org X-Gm-Message-State: AOJu0YxsO7Xxo4GGmcwpEv1yo4Ru8pYeERAFwKlqHdAJSSYZ24eHzat3 5+43tMWvGI+p5eRGb2KHgtRXG2Qh7sdeMgTBLDLQzTuxlZWt9G5P5Ul8hZ8fw9IfIVRaRFxaxTE msJge9pENreL24zJAvscJJC8STaQ= X-Gm-Gg: ASbGnctZYnbaOTCZ06SuTrqAWSnL0EVymTRmxGBRELrRocAAClJT/YAri976enxkDf1 cAqdhHzkFAJWdahciCLCQr4EzW6nhuNAR2aZQITcKxEkVbfNzWuMtHQBpgCjvlRdZUexSJb9pLS GZWrETCO5CV0uIK6oEvmOZgcqDgg== X-Google-Smtp-Source: AGHT+IG02F1EM+jBAh7+YGsjjgJ/ng6qTMmdY+6UCuGCifhdh8H/1SI0yMOAMSol1NtPmovBbTjwNezofBfaUFEGB6c= X-Received: by 2002:a17:903:904:b0:224:18fd:6e09 with SMTP id d9443c01a7336-22a89ebc4aamr37537595ad.0.1743866631372; Sat, 05 Apr 2025 08:23:51 -0700 (PDT) MIME-Version: 1.0 References: <20250405060154.1550858-1-andrewjballance@gmail.com> <20250405060154.1550858-3-andrewjballance@gmail.com> In-Reply-To: <20250405060154.1550858-3-andrewjballance@gmail.com> From: Miguel Ojeda Date: Sat, 5 Apr 2025 17:23:39 +0200 X-Gm-Features: ATxdqUHgh0DIJx3Sa3HDUPPTedxcX6iWeq7MdDPNHgUdrwBRYxBKgjXPFMNrLBw Message-ID: Subject: Re: [RFC PATCH 2/2] rust: add maple tree abstractions To: Andrew Ballance Cc: Liam.Howlett@oracle.com, ojeda@kernel.org, alex.gaynor@gmail.com, boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com, benno.lossin@proton.me, a.hindborg@kernel.org, aliceryhl@google.com, tmgross@umich.edu, dakr@kernel.org, akpm@linux-foundation.org, gregkh@linuxfoundation.org, wedsonaf@gmail.com, brauner@kernel.org, dingxiangfei2009@gmail.com, linux-kernel@vger.kernel.org, maple-tree@lists.infradead.org, linux-mm@kvack.org, rust-for-linux@vger.kernel.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Stat-Signature: x48erqei3co8i665fkt9h1btkeaf1kmn X-Rspam-User: X-Rspamd-Queue-Id: 8B8C4C0006 X-Rspamd-Server: rspam08 X-HE-Tag: 1743866632-879579 X-HE-Meta: U2FsdGVkX19kNY2yVLQFbIFWcTCJ4ENCCZLffUHV+COyswp91dqPxbWkIBoG/6HQ+0hdD/nyn0xG3w7+26Y5dSKcYjo1j15tikdBDZlsaM6U6DCtVTHlYwOLocGfd7PPsE0BfPPeTaN9T+YvNuRorfdzVrT7aRCxUEekI5XRiR3dIN7zNri5IvdzZ5OQlklVX/5QR+dIhzLq88KMFH/w9+fptUyDqBqWe9SSTcu6ZeHJPyKR/UFsl/R1dOUEAeKUGIB1YhIYUQC6Bhu8NKaNsGelAGcsfFs9tEgV5p2lSRN72xRMiMXIGKOVC7d9BV9psiF4ONMXYMRiPAoyjQLUc1dpU2NcLzIX2IQSmI5ApoFb2JrJqtMsXn7W7aZS/j3k7M08c3x5XII/q9rjZ98G/MtbUrXIGKnBh/Dtp0krlEWmKml6OkN1sg5M4j11kCnVQbxiLWuYBqqsqI2IAO1pvDWuHdRi6BilMpN0UT2l/8NHctLBwSm1DizgIUBg0+xMwJHnI9BNX6rIE6Gm5GqQVbfkLNiyZ0e24gkBswySVbBUSa05aJ9LXZ4v+9Das8KV0/CS0miNW3SiBySkooEyLwR8TmvwMP2C77PQaWHs4VSk1oe0vQuiA0T8JIH1eGJwscjaOIKaReZrbmzstjvL8KPeDS68l34awMZtdJQNCQ+DWewPN8yd5LP/qzuqd+8Pj6Ea2oJ5yZARFogoWmCR+c9PU8NuQqs7Abvp5vmbB1ehM36Ca/TQ5BV7CYXtC2nNcECd+p42dolza52NQJNX/4imzLrT1wOhm26jCUks5jFnF3lWr6hBAF20WE6UoDTlpEcYF6wn+ZXpmkyJiExMtcKu3LtysafNIF9UGZGC0VYF6UUk/A3jUul/E4xu8OQH5TAJeoxHjlfLwa7fibxElBiuiSPk+Os9CTcLhBVoWDtYxpb2CbgrT4Y8U+s9EOcnTJxW1HecDRP+Q0KkwWb vdqFr9+r 5EE+s5dk6wepn5U2dOL9RZnLi3NvVQogZ4l+Djk5I9dGJrvHFPtTPSVCmxJ84bNQX8CAwXWHppqkMzFwUU5kJyW9iZpb2VDGdtNRJVcpKY6RectTjr6oAzjAki3kVsqdHm1TnCpw+3cwdniK0ZNLxKdFhH2Kmpl+mhZYGdTxxLW4C2cfYect/7cFcauNO11v6DHYuNmDchURazP7ryLc0QJ3wU4eQ0Zu3CiWRYoeecMyA+wA7O1k4jSlobaelqC4XK6roCqMUc3avOOVSKXtLD8ROLPXzP+0NZLDptaMb23B1P8jtxO3r1j/eSRTn7QQygDxyhhFkbm/eH8WzUa2S96HRB+2wAxJjK8Z7TM91uaHAhMn+4DdYshZF9jXsLp3bEppbjQA0zrh4KbPuE+SeL435b5dwuGnCxLsRQgjyiTup/AkzBo0ELxqbl+3iCyQskB2SHO1haCYxdYdEebaj2gRsWg== X-Bogosity: Unsure, tests=bogofilter, spamicity=0.499928, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: Hi Andrew, Some doc-related notes for future submissions... I hope this helps. On Sat, Apr 5, 2025 at 8:03=E2=80=AFAM Andrew Ballance wrote: > > +#include > + > + Nit: double newline. > +//! # Examples > +//! ``` There should be an empty doc line between these. > +// TODO and missing features > +// - the C version suports external locking this only supports the inter= nal spinlock (Multiple instances) Typo -- you may want to use e.g. `checkpatch.pl` with `--codespell`. > +// SAFETY: > +// we cannot derefrence any pointers without holding the spinlock becaus= e > +// all returned pointers are guaranteed to have been inserted by the use= r > +// but the pointers are not guaranteed to be still be valid > +// another thread may have already removed and dropped the pointers > +// so to safely deref the returned pointers the user must > +// have exclusive write access to the `MapleTree` > +// or rcu_read_lock() is held and updater side uses a synchronize_rcu() `SAFETY` comments are intended to go attached to an `unsafe` block or implementation, explaining why they satisfy the requirements. Clippy should be warning here, but it doesn't likely due to this Clippy issue I just filed: https://github.com/rust-lang/rust-clippy/issues/14554 (plus other three I filed while looking into this one). > +/// A `MapleTree` is a tree like data structure that is optimized for st= oring (Multiple instances) Please use intra-doc links wherever they work. > +// # Invariants (Multiple instances) Please make this section part of the docs. We may change how we document private invariants in the future (or we may expose private fields so that it is clearer) -- for the moment, please add a note if you really want users to never rely on a particular invariant. > + /// creates a new `MapleTree` with the specified `flags` (Multiple instances) Please follow the usual style, e.g. Markdown and intra-doc links where possible, start with uppercase, period at the end of sentences, etc. > + // SAFETY: > + // - mt is valid because of ffi_init > + // - maple_tree contains a lock which should be pinned (Multiple instances) Please format with Markdown in comments. > + /// helper for internal use. > + /// returns an iterator through the maple tree > + /// # Safety (Multiple instances) Newlines are needed here -- `rustdoc` uses the first paragraph as the "short description", too. > +#[derive(Clone, Copy, PartialEq)] > +/// flags to be used with [`MapleTree::new`]. We write attributes below the documentation. > + if ptr.is_null() { > + return None; > + } > + // SAFETY: We typically leave a newline after a loop or a branch. Thanks for the patch! Cheers, Miguel