From nobody Fri Oct 2 12:21:53 2026 Received: from mail-yw1-f174.google.com (mail-yw1-f174.google.com [209.85.128.174]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id CF128330307 for ; Fri, 31 Jul 2026 21:53:14 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.174 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1785534796; cv=none; b=F5M+rEhp5nf7w+BzL8uA+gQW+NfVXgDk+csEXIcY367awyPWpXSd0juZ48g1o4ZVfD53ujMWoCvfds+d39Sc4/N5iqa3dq0N8ujTgZHzzAcFIWhnu4Qh17OkD3P/Gy8XYebFisEyY0/j6UVDBO/WuKvBlnieHJBEZT+wksT5sDA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1785534796; c=relaxed/simple; bh=j5vpS8ZEODJmkH/N+ljLcRw6uVdYRS1WWkB7Xvoio/o=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=bOQR632Fd3vA016XodYcXUUZNXu389c9xEMF67FyCEtDhc799Ze78MlywO2igbXoTyFCEfPHxRn5N6ounrlYuSojD5/sCeRvmMwxFq0VrUtyynEHMi/rG/zE4MA8AhLMTaQh8VjsIIb1ltz9IhSqq/PmbtDCvuzoj9yBFNU07vA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Ki4BveLT; arc=none smtp.client-ip=209.85.128.174 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Ki4BveLT" Received: by mail-yw1-f174.google.com with SMTP id 00721157ae682-81e83f1f15aso18337947b3.1 for ; Fri, 31 Jul 2026 14:53:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1785534794; x=1786139594; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to:content-type; bh=uv3ZuG/t2LPu91C3JVFaNglVqECVmJkRCcb3rg36a4g=; b=Ki4BveLTO0C/tOPMyqQffo8wBi+yLqonrhm0CElW5BbcsheZCCyGTRHpWpk2MRJpgo BifWyLTml+w5/Z8dvj+WegSGuevMsiD0Usnt5dTANp5VfBv/XTjDgw/62IXxwIB6MRBI Dyy8ijtKILDV0913rkPh6v223DixQpL4M7TQwfJJ/nVrwLWOKEnClghg3fqwlBR1OgFL Z5kQM+5vQHHmdpOleJMKVm5Df12mVaQG91/LlFsiGhkYFyp9+RK6CAImhzPCbH8MiOs9 54lU+xoZQ3DnwCvlhlWQjFWY7BVX1n2qWkWz5IMmjV7HC/EcD0QpyUm2wTJ3GFWh3N9p dbKg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1785534794; x=1786139594; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to:content-type; bh=uv3ZuG/t2LPu91C3JVFaNglVqECVmJkRCcb3rg36a4g=; b=oXd5Sfz6PXrTUEWwL3xnW1/NyduaQl+icJtJGpMkwOOg6iXHxSwngv5pyLtNrtCW5y fsShAcbEpzCqpSNMRvIqGrvYtdwZqZfjukXEF5AU0Y2ecBuQJ8yWvcgc7USIvlBxu0lS 9WPR7m++oP29W1mcgELmiZ6mefbTxLJSn8l8DdrROPLpZrIHKnrDcVbEymsKxn2qkFmq vk1zy4qEDNZFcLYO7OtHqaI+YJ+MDdsicPS4s5/RMkQwjk4difwZ8rE/FakyiXEqyJuv CufoZrPzujyuVMOaTC1YwJAUL91md6r6yOo3ltkjSAs5Zozq51IrdFAQHZUB+TR+FErN tJRg== X-Forwarded-Encrypted: i=1; AHgh+RpaD48Hj+Jgpz3ujjZhwdLMeeuNS+IHiuUfVxJDIxeTd2NCmwmM850E+nashoV2rAZDE7I1LuZ4uiSnhY4=@vger.kernel.org X-Gm-Message-State: AOJu0Yw1t0wWChEXPGNIY0xwkxQeGxCc8N6XGI27al9va62mq4xeUxse fc/qc+7uRZk87rGWQsPzlAYeFHhwfsdUxUi07e0/Ksv6B32Zbs0oAWJ6 X-Gm-Gg: AR+sD11umyx0/leVEzR7JBMXlHdu7dhBojlbkQdj1cO1hVl9exmNinbrdOx/vYWZp0b bw1mDdISXzJrQHakmeiB59AoU0HtCLyjygw9u87UhV+vqkv8ZIiWXgbMdGAxcJNGVUUATeAn32i qJJUVMshstGe/wAfC8h1q9ZHCC5F/o6hCm/WSTBZWZwwpOOZZM9O5LsFD0U3dBr8Lw0A/+IundM trjPXIt7gNNX5SaCuZfoIjuh/UXY07G8cJC7LSy7DkDlcbA/JjjYR4AasctYnzC2DxXTf04L37B xTpDAIR033ifYmHluts+I3CariieEiw3itNqtBoF5OAYgSF3jBB3yjU9OfFxTD99HtIdQrTO/q0 h9odLBZoxt6ws5qSeKTe0W3cjoODaJ3YlT7I0pMLUzbzVwP4fwPmP+HtTPk7sRYS5zytyGyNuGz vS/sUV/+ntlfJfa1wAW8uidRG2eDQrLAEs6vyrWs6KNk8ajSRx2LkuqUXBLeCcxiICfiQHjdYhs bOIoRVmERv10bhYCYCVIeWyQUQkC60jELrNIqd2jxIjN2lf4F9MPTJGCACz/puJ X-Received: by 2002:a05:690c:698b:b0:7dc:3d2b:2e94 with SMTP id 00721157ae682-81fcbc4bc89mr33794727b3.13.1785534793695; Fri, 31 Jul 2026 14:53:13 -0700 (PDT) Received: from pop-os.tail4f8d5c.ts.net ([2800:810:473:6eb:bc9d:6ed6:1f62:1459]) by smtp.gmail.com with ESMTPSA id 00721157ae682-81fccf610a0sm14439107b3.14.2026.07.31.14.53.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 31 Jul 2026 14:53:13 -0700 (PDT) From: Juan Patricio Marchetto To: Miguel Ojeda Cc: Gary Guo , Boqun Feng , =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross , Danilo Krummrich , Daniel Almeida , Tamir Duberstein , Alexandre Courbot , =?UTF-8?q?Onur=20=C3=96zkan?= , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Juan Patricio Marchetto Subject: [PATCH v3] rust: rbtree: document peek_next() on the immutable cursor Date: Fri, 31 Jul 2026 18:51:56 -0300 Message-ID: <20260731215157.2801197-1-juanpatriciomarchetto@gmail.com> X-Mailer: git-send-email 2.43.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The immutable Cursor has a single example, covering cursor_front() and current(). Its peek_next() has none: the only worked example of peeking belongs to CursorMut. That leaves the most common reason to hold an immutable cursor undocumented. cursor_lower_bound() stops on an exact match, so a caller looking for the first key strictly greater than the one it supplied has to peek past it. When the key was absent the cursor already holds the answer, and peeking there returns its successor instead, skipping an element. Document both branches, and the case where the looked-up key is the largest in the tree and has no successor. Assisted-by: Claude:claude-opus-5 Signed-off-by: Juan Patricio Marchetto --- Notes: v3: - Move the example from the Cursor type documentation onto Cursor::peek_next(), adding an "# Examples" heading and adapting the intro sentence to the new context (Gary Guo). - Reformat the doctest import to the kernel vertical import style (Sashiko review of v2). - Verified with rust_doctests_kernel under ARCH=3Dum: 321/321. =20 v2: v1 documented only the exact-match branch, so the idiom as written skipped an element whenever the looked-up key was absent. The example n= ow covers both branches and uses a four-element tree so the skipped element is visible. Reported by the Sashiko review of v1. =20 v2: https://lore.kernel.org/r/20260729023420.1323906-1-juanpatriciomarc= hetto@gmail.com v1: https://lore.kernel.org/r/20260729014344.1244809-1-juanpatriciomarc= hetto@gmail.com rust/kernel/rbtree.rs | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/rust/kernel/rbtree.rs b/rust/kernel/rbtree.rs index 6fbd579d4a4..42f946a9bd0 100644 --- a/rust/kernel/rbtree.rs +++ b/rust/kernel/rbtree.rs @@ -856,6 +856,47 @@ pub fn peek_prev(&self) -> Option<(&K, &V)> { } =20 /// Access the next node without moving the cursor. + /// + /// # Examples + /// + /// Peeking completes a lookup for the first key strictly greater than= a given + /// one. [`RBTree::cursor_lower_bound`] stops on an exact match, so th= e peek is + /// needed only when the key was present: when it was absent the curso= r already + /// holds the answer, and peeking there skips an element instead. + /// + /// ``` + /// use kernel::{ + /// alloc::flags, + /// rbtree::RBTree, // + /// }; + /// + /// // Create a new tree. + /// let mut tree =3D RBTree::new(); + /// + /// // Insert four elements. + /// tree.try_create_and_insert(10, 100, flags::GFP_KERNEL)?; + /// tree.try_create_and_insert(20, 200, flags::GFP_KERNEL)?; + /// tree.try_create_and_insert(30, 300, flags::GFP_KERNEL)?; + /// tree.try_create_and_insert(40, 400, flags::GFP_KERNEL)?; + /// + /// // 20 is present, so the cursor stops on the key the caller alread= y has and the + /// // successor is one peek away. + /// let cursor =3D tree.cursor_lower_bound(&20).unwrap(); + /// assert_eq!(cursor.current(), (&20, &200)); + /// assert_eq!(cursor.peek_next().unwrap(), (&30, &300)); + /// + /// // 25 is absent, so the cursor already sits on the answer. Peeking= from here + /// // returns 40 and skips 30. + /// let cursor =3D tree.cursor_lower_bound(&25).unwrap(); + /// assert_eq!(cursor.current(), (&30, &300)); + /// assert_eq!(cursor.peek_next().unwrap(), (&40, &400)); + /// + /// // The largest key has no successor. + /// let cursor =3D tree.cursor_lower_bound(&40).unwrap(); + /// assert!(cursor.peek_next().is_none()); + /// + /// # Ok::<(), Error>(()) + /// ``` pub fn peek_next(&self) -> Option<(&K, &V)> { self.peek(Direction::Next) } base-commit: dc59e4fea9d83f03bad6bddf3fa2e52491777482 --=20 2.43.0