Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation about lifetimes to thread::scope. #94763

Merged
merged 1 commit into from
Mar 10, 2022
Merged

Add documentation about lifetimes to thread::scope. #94763

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions library/std/src/thread/scoped.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,24 @@ impl ScopeData {
/// a.push(4);
/// assert_eq!(x, a.len());
/// ```
///
/// # Lifetimes
///
/// Scoped threads involve two lifetimes: `'scope` and `'env`.
///
/// The `'scope` lifetime represents the lifetime of the scope itself.
/// That is: the time during which new scoped threads may be spawned,
/// and also the time during which they might still be running.
/// Once this lifetime ends, all scoped threads are joined.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// Once this lifetime ends, all scoped threads are joined.
/// By design, this lifetime only ends once all the scoped threads have been joined.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I care about this one because that's the right ordering: 'scope by very definition, outlives the Scope and Packet instances, so the right property is rather "once the scoped threads are all joined, this lifetime may end", hence my suggestion

/// This lifetime starts within the `scope` function, before `f` (the argument to `scope`) starts.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit weird to speak of the beginning of a lifetime, it's not really something that comes up in practice or is important. But I guess it's okay for the sake of explaining stuff:

Suggested change
/// This lifetime starts within the `scope` function, before `f` (the argument to `scope`) starts.
/// This lifetime "starts" within the `scope` function, before `f` (the argument to `scope`) is called.

/// It ends after `f` returns and all scoped threads have been joined, but before `scope` returns.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// It ends after `f` returns and all scoped threads have been joined, but before `scope` returns.
/// It ends after `f` returns and all scoped threads have been joined, but before `scope` returns[^hrtb].
///
/// [^hrtb]: a property of higher-order (`for<'scope>`) lifetimes.

///
/// The `'env` lifetime represents the lifetime of whatever is borrowed by the scoped threads.
/// This lifetime must outlast the call to `scope`, and thus cannot be smaller than `'scope`.
/// It can be as small as the call to `scope`, meaning that anything that outlives this call,
/// such as local variables defined right before the scope, can be borrowed by the scoped threads.
///
/// The `'env: 'scope` bound is part of the definition of the `Scope` type.
#[track_caller]
pub fn scope<'env, F, T>(f: F) -> T
where
Expand Down