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.

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

API Docs: sync #29377

Closed
steveklabnik opened this Issue Oct 26, 2015 · 18 comments

Comments

Projects
None yet
9 participants
@steveklabnik
Member

steveklabnik commented Oct 26, 2015

Part of #29329

http://doc.rust-lang.org/std/sync/

Here's what needs to be done to close out this issue:

  • the module-level documentation is very small. It should explain what the module is for in more detail, with some examples.
  • std::sync::atomic could use links to the types it references.
  • std::sync::atomic::fence has very... dry docs that aren't very helpful. And there's no examples.
  • ATOMIC_*_INIT (link is just to BOOL but all of them) could use examples.
  • Atomic* (link is to Bool but all of them) are mostly fine, but could use links to other types and some beefing up generally.
  • Barrier needs a bunch of types linked.
  • BarrierWaitResult should explain its relationship with Barrier and link to it.
  • Condvar needs examples on its methods.
  • Once needs to link to ONCE_INIT.
  • PoisonError needs examples.
  • RwLock needs examples, links to types, and a comparison between it and Mutex.
  • WaitTimeoutResult should link to the method that creates it.
  • TryLockError needs to link to the function that creates it.
  • ONCE_INIT needs a link to Once and some examples.
  • LockResult needs links.
  • TryLockResult needs links.
  • Weak could do a much better job of explaining itself.
  • std::sync::mspc needs a lot of links. The docs are good but a bit jargon-heavy, expanding those would be nice.
  • IntoIter needs more links and to explain how you get one.
  • Iter is the same.
  • Receiver needs links, examples, and more explanation of what it is.
  • RecvError needs to link to recv.
  • SendError needs links.
  • Sender has the same issues as Receiver.
  • SyncSender has the same as Sender.
  • TryIter needs to link to how to create one.
  • RecvTimeoutError needs to link to recv_timeout.
  • TryRecvError needs to link to try_recv
  • TrySendError needs to link to try_send.
  • channel has almost no docs and it's the focus of this module!
  • sync_channel should point to channel and then tell how it's different.
@iuliuv

This comment has been minimized.

iuliuv commented Jan 11, 2016

Possible inconsistency in the Rust documentation about channels:

https://doc.rust-lang.org/std/sync/mpsc/fn.sync_channel.html
Function std::sync::mpsc::sync_channel
"As with asynchronous channels, all senders will panic in send if the Receiver has been destroyed"

https://doc.rust-lang.org/std/sync/mpsc/struct.SyncSender.html
Struct std::sync::mpsc::SyncSender:
fn send(&self, t: T) -> Result<(), SendError>
"This function will never panic, but it may return Err if the Receiver has disconnected and is no longer able to receive information."

@kmcallister

This comment has been minimized.

Contributor

kmcallister commented Sep 19, 2016

I'm working on updating the Arc docs to more closely match the refined Rc docs from #36571.

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 8, 2017

I am happy to mentor anyone who wants to tackle this issue.

@projektir

This comment has been minimized.

Contributor

projektir commented Mar 26, 2017

@steveklabnik for all the ones that need links, are you talking about for example the types wrapped in <code> tags, such as Sender under the std::sync::mpsc::Receiver page? Is it safe to say that as general rule every type under a <code> tag should link to the page for that type? Is there other linking on these pages you would expect to see?

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 27, 2017

Is it safe to say that as general rule every type under a <code> tag should link to the page for that type?

Yes, exactly. Note that sometimes there is a bug here; that is, certain kinds of docs get rendered on two pages and so the links won't work. I don't think that's an issue here, but our tools will catch those cases, so you shouldn't worry about it too much, but figured it'd be worth a mention.

Is there other linking on these pages you would expect to see?

That's pretty much it, just the stuff that's in <code> already.

@projektir

This comment has been minimized.

Contributor

projektir commented Mar 27, 2017

Someone looks to have fixed up Barrier on nightly, btw.

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 27, 2017

Someone looks to have fixed up Barrier on nightly, btw.

Ah, I made these off of the stable links, I think :(

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 29, 2017

Rollup merge of rust-lang#40866 - projektir:once_docs, r=estebank
Adding linking for Once docs rust-lang#29377

Linking everything around `Once`, `ONCE_INIT`, and `OnceState`.

Technius added a commit to Technius/rust that referenced this issue Mar 31, 2017

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 31, 2017

Rollup merge of rust-lang#40871 - projektir:atomic_links, r=steveklabnik
Adding links for Atomics docs rust-lang#29377

r? @steveklabnik

This should be good for `std::sync::atomic`. The other pages still need more (examples, etc.).

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 31, 2017

Rollup merge of rust-lang#40871 - projektir:atomic_links, r=steveklabnik
Adding links for Atomics docs rust-lang#29377

r? @steveklabnik

This should be good for `std::sync::atomic`. The other pages still need more (examples, etc.).

Technius added a commit to Technius/rust that referenced this issue Apr 1, 2017

Add links and examples to std::sync::mpsc docs (rust-lang#29377)
This change adds links to to `Receiver`, `Iter`, `TryIter`, `IntoIter`,
`Sender`, `SyncSender`, `SendError`, `RecvError`, `TryRecvError`,
`RecvTimeoutError`, `TrySendError`, `Sender::send`, `SyncSender::send`,
`SyncSender::try_send`, `Receiver::recv`, `Receiver::recv_timeout`,
`Receiver::iter`, and `Receiver::try_iter`.

Examples added to `Receiver`, `Sender`, `Receiver::iter`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 3, 2017

Rollup merge of rust-lang#40977 - projektir:BarrierWaitResult_doc, r=…
…steveklabnik

Updating the description for BarrierWaitResult rust-lang#29377

Referencing `Barrier`, removing reference to `is_leader`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 3, 2017

Rollup merge of rust-lang#40977 - projektir:BarrierWaitResult_doc, r=…
…steveklabnik

Updating the description for BarrierWaitResult rust-lang#29377

Referencing `Barrier`, removing reference to `is_leader`.
@projektir

This comment has been minimized.

Contributor

projektir commented Apr 4, 2017

@steveklabnik can we check some boxes off to track progress and make it easier to see where we're at? 😄 Things that I believe can be marked off:

std::sync::atomic -> merged, but I could understand if you want more stuff here
Once -> merged
ONCE_INIT -> merged
WaitTimeoutResult -> looks good to me on nightly
LockResult -> has links on nightly
TryLockResult -> has links on nightly

Awaiting merge/approval:
BarrierWaitResult -> going to be merged, could as well be marked off I think
std::sync::mspc -> looks good, too, but waiting for approval

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Apr 4, 2017

@projektir done, thank you!

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 4, 2017

Rollup merge of rust-lang#40977 - projektir:BarrierWaitResult_doc, r=…
…steveklabnik

Updating the description for BarrierWaitResult rust-lang#29377

Referencing `Barrier`, removing reference to `is_leader`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 4, 2017

Rollup merge of rust-lang#40981 - Technius:master, r=steveklabnik
Add links and some examples to std::sync::mpsc docs

Addresses part of rust-lang#29377
r? @steveklabnik

I took a stab at adding links to the `std::sync::mpsc` docs, and I also wrote a few examples.

Edit: Whoops, typed in `?r` instead of `r?`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 4, 2017

Rollup merge of rust-lang#40977 - projektir:BarrierWaitResult_doc, r=…
…steveklabnik

Updating the description for BarrierWaitResult rust-lang#29377

Referencing `Barrier`, removing reference to `is_leader`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 4, 2017

Rollup merge of rust-lang#40981 - Technius:master, r=steveklabnik
Add links and some examples to std::sync::mpsc docs

Addresses part of rust-lang#29377
r? @steveklabnik

I took a stab at adding links to the `std::sync::mpsc` docs, and I also wrote a few examples.

Edit: Whoops, typed in `?r` instead of `r?`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 13, 2017

Rollup merge of rust-lang#41240 - projektir:weak_docs, r=alexcrichton
Updating docs for std::sync::Weak rust-lang#29377

I will duplicate these changes for [`std::rc::Weak`] if they are approved.

[`std::rc::Weak`]: https://doc.rust-lang.org/std/rc/struct.Weak.html

r? @jonathandturner

bors added a commit that referenced this issue Apr 13, 2017

Auto merge of #41240 - projektir:weak_docs, r=alexcrichton
Updating docs for std::sync::Weak #29377

I will duplicate these changes for [`std::rc::Weak`] if they are approved.

[`std::rc::Weak`]: https://doc.rust-lang.org/std/rc/struct.Weak.html

r? @jonathandturner

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 13, 2017

Rollup merge of rust-lang#41240 - projektir:weak_docs, r=alexcrichton
Updating docs for std::sync::Weak rust-lang#29377

I will duplicate these changes for [`std::rc::Weak`] if they are approved.

[`std::rc::Weak`]: https://doc.rust-lang.org/std/rc/struct.Weak.html

r? @jonathandturner

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 13, 2017

Rollup merge of rust-lang#41240 - projektir:weak_docs, r=alexcrichton
Updating docs for std::sync::Weak rust-lang#29377

I will duplicate these changes for [`std::rc::Weak`] if they are approved.

[`std::rc::Weak`]: https://doc.rust-lang.org/std/rc/struct.Weak.html

r? @jonathandturner

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 13, 2017

Rollup merge of rust-lang#41240 - projektir:weak_docs, r=alexcrichton
Updating docs for std::sync::Weak rust-lang#29377

I will duplicate these changes for [`std::rc::Weak`] if they are approved.

[`std::rc::Weak`]: https://doc.rust-lang.org/std/rc/struct.Weak.html

r? @jonathandturner
@durka

This comment has been minimized.

Contributor

durka commented Apr 13, 2017

Condvar has examples on its methods, but the ones for wait_* seem to contain race conditions.

WaitTimeoutResult::timed_out has an example that does not use the method (it is copied from the incorrect example for Condvar::wait_timeout).

@projektir

This comment has been minimized.

Contributor

projektir commented Apr 14, 2017

I think @GuillaumeGomez worked on the Condvar examples?

@GuillaumeGomez

This comment has been minimized.

Member

GuillaumeGomez commented Apr 21, 2017

It's very possible, I had issue with timeout stuff...

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 24, 2017

Rollup merge of rust-lang#41438 - projektir:mpsc_docs, r=alexcrichton
Adding links and examples for various mspc pages rust-lang#29377

Adding links and copying examples for the various Iterators; adding some extra stuff to `Sender`/`SyncSender`/`Receiver`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 24, 2017

Rollup merge of rust-lang#41438 - projektir:mpsc_docs, r=alexcrichton
Adding links and examples for various mspc pages rust-lang#29377

Adding links and copying examples for the various Iterators; adding some extra stuff to `Sender`/`SyncSender`/`Receiver`.

arielb1 added a commit to arielb1/rust that referenced this issue Apr 27, 2017

Rollup merge of rust-lang#41438 - projektir:mpsc_docs, r=steveklabnik
Adding links and examples for various mspc pages rust-lang#29377

Adding links and copying examples for the various Iterators; adding some extra stuff to `Sender`/`SyncSender`/`Receiver`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 27, 2017

Rollup merge of rust-lang#41438 - projektir:mpsc_docs, r=steveklabnik
Adding links and examples for various mspc pages rust-lang#29377

Adding links and copying examples for the various Iterators; adding some extra stuff to `Sender`/`SyncSender`/`Receiver`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 27, 2017

Rollup merge of rust-lang#41438 - projektir:mpsc_docs, r=steveklabnik
Adding links and examples for various mspc pages rust-lang#29377

Adding links and copying examples for the various Iterators; adding some extra stuff to `Sender`/`SyncSender`/`Receiver`.

frewsxcv added a commit to frewsxcv/rust that referenced this issue May 3, 2017

Rollup merge of rust-lang#41217 - topecongiro:docs/atomic-fence, r=st…
…eveklabnik

Update docs of 'fence'

This PR updates the docs for `std::sync::atomic::fence` with an example and a diagram.
Part of rust-lang#29377.
r? @steveklabnik
@gamazeps

This comment has been minimized.

Contributor

gamazeps commented May 13, 2017

@steveklabnik is the list of things to do in this module up to date ?

I was thinking on tackling this module once I am done with the thread module (probably on Monday).

If no one else is working on this I'll try to document the whole module for the next week (and maybe a little bit of the next one).

@GuillaumeGomez

This comment has been minimized.

Member

GuillaumeGomez commented May 13, 2017

@gamazeps: More or less. It still has a lot of places to improvement anyway so feel free to give it a try!

@projektir

This comment has been minimized.

Contributor

projektir commented May 15, 2017

@gamazeps so everything starting with Weak and going down should be done now, it's just not marked off.

I've been working on rewriting this page: std::sync::atomic: https://doc.rust-lang.org/std/sync/atomic/, but that relates more to this issue: #40306, and I have been distracted so it's going slow. I hope to get it done this week.

Atomic fence may be done, also, I've seen some PR's for it. But @steveklabnik would need to clarify.

So everything else should be up for grabs and of course nothing's stopping you from improving any given page further.

frewsxcv added a commit to frewsxcv/rust that referenced this issue Sep 23, 2017

Rollup merge of rust-lang#44778 - lucasem:master, r=estebank
std::sync::RwLock docs improvement

Addresses the `RwLock` part of rust-lang#29377.
r? @steveklabnik

Added examples, links to types, and a small comparison between RwLock and Mutex.
@lucasem

This comment has been minimized.

Contributor

lucasem commented Sep 23, 2017

@steveklabnik I completed the RwLock subtask with #44778

@lucasem

This comment has been minimized.

Contributor

lucasem commented Sep 25, 2017

@steveklabnik ditto for PoisonError and TryLockError.

What did you have in mind for changes to Atomic*?

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Sep 25, 2017

@lucasem thank you!

What did you have in mind for changes to Atomic*?

So I'm looking at them now, and they're pretty good. Mostly, there's a few types mentioned that don't have links, like how https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html doesn't have a link to https://doc.rust-lang.org/stable/std/primitive.bool.html

I wonder if we should point to the module documentation as well, like, add a sentence to each type saying

For more about the differences between atomic types and non-atomic types, please see the module-level documentation.

Thoughts?

Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue Sep 29, 2017

Rollup merge of rust-lang#44797 - lucasem:master, r=frewsxcv
docs improvement std::sync::{PoisonError, TryLockError}

Addresses the `PoisonError` and `TryLockError` parts of rust-lang#29377.
Adds examples and links.

r? @steveklabnik

Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue Sep 29, 2017

Rollup merge of rust-lang#44854 - lucasem:atomic-docs, r=steveklabnik
docs improvement sync::atomic::Atomic*

Addresses the `Atomic*` part of rust-lang#29377.
r? @steveklabnik

pietroalbini added a commit to pietroalbini/rust that referenced this issue Oct 5, 2018

Rollup merge of rust-lang#54078 - GabrielMajeri:expand-sync-docs, r=s…
…teveklabnik

Expand the documentation for the `std::sync` module

I've tried to expand the documentation for Rust's synchronization primitives. The module level documentation explains why synchronization is required when working with a multiprocessor system,
and then links to the appropiate structure in this module.

Fixes rust-lang#29377, since this should be the last item on the checklist (documentation for `Atomic*` was fixed in rust-lang#44854, but not ticked off the checklist).

@bors bors closed this in #54078 Oct 6, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment