Guard

[crop2000]

You said that you are not interested in using a Guard that utilizes drop to publish a Buffer. Would you be interested in a PR that provides this in addition to the current interface? based on this experiment: https://github.com/crop2000/triple-buffer

[HadrienG2]

Back in the day, the concern that made me avoid the guard pattern is that its UX can be surprising : you get something that looks and feels like a member accessor, so you may end up expecting it to behave like a member accessor (e.g. if you call it twice in a row without interference from the other thread then you may expect to get the same input buffer contents), yet that is not the case. Such surprises may lead to bugs, when people do not read the docs carefully.

So given that I already had "easy to use" covered with write(), and that input_buffer() + publish() can cover a few extra obscure use cases beyond what a guard easily allows (e.g. incrementally building a Vec using input_buffer().push_back() before publishing), I thought a non-guard design might be more appropriate.

But I think you are right that if we have both a simple member accessor and a method that returns a guard, that is less of a concern. All we need to do then is make sure we pick a distinctive name for the method that returns a guard, which highlights strongly enough that these two methods do not do the same thing. For example, we could name the method that returns a guard start_publish() and the returned type PublishGuard, and that should hopefully highlight strongly enough that the new method with the guard is all about eventually publishing a buffer update.

[crop2000]

I realized that i prefer the naming i chose before: fn guarded_input_buffer() -> InputGuard .
To me it feels that this is the name that describes what is happening most closely.

[HadrienG2]

I am not 100% satisfied with this naming because "guarded" is uncommon in Rust method names and "Guard" in a type name does not express anything more than "does something nontrivial on Drop". Let me explain why that is a problem first and then propose an alternative.

---

Picture yourself someone who is unfamiliar with triple_buffer and reads through a third-party codebase that uses this feature. When they see code that uses a guarded_input_buffer() method, all the name tells them is that the output has a nontrivial Drop (assuming they are familiar with the guard pattern, but I think that's fair as that pattern is introduced early on in Rust courses).

To know more about what happens on Drop, they will likely need to check the triple_buffer documentation. If they are not lucky enough to use an IDE that provides easy access to docs on hover (e.g. if they are reviewing a PR on GitHub), this may require an undesirable break out of their code-reading mental flow: figure out that this is from triple_buffer, open docs.rs, look up triple_buffer, find the right type, read the docs, finally go back to reading code and try to get back to where they were...

FWIW I agree that my previous fn start_publish() -> PublishGuard naming proposal has the reverse problem: it tells you that you can use the output to publish something, and hopefully you guess that it publishes on Drop in the absence of an explicit publish action. But without checking the docs, you have no idea what you can do with the output type before Drop, i.e. that you can use it to access the input buffer. Unless you figure it out from the surrounding code doing derefs, but that's arguably hard as Deref is magic.

I suspect that was your issue with this initial name proposal of mine, am I right?

---

Here is an alternate name proposal that attempts to express both "you can access the input buffer with this" and "this will publish on Drop" while keeping the wording concise: fn input_buffer_publisher() -> InputPublishGuard.

Here's how I hope this naming would work out in the mind of unfamiliar readers:

• "This method has input_buffer in the name, so it can be used to do something to the input buffer."
• "This method has publisher in the name, so the output object somehow must allow publishing the input buffer to the outside world if used in some way."
• (If reader has seen before that there is another method called input_buffer()) "Actually, the name sounds closely related to the input_buffer() method, so most likely I can use it to access the input buffer like with that other method. But I can also use it to publish the input buffer."
• "Wait, I see that the user only uses the output of input_buffer_publisher() to access the input buffer. Huh, that's interesting. Did they forget to call the publish method?"
• Then, depending on the IDE style...
  • Default VSCode/RustRover configuration where types are always shown: "Oh, right, the output type has Guard in its name, so it does something on Drop. Most likely that's when the publishing happens."
  • Default SublimeText/GitHub WebUI where types are shown on hover: "Let me hover that and get a link to the docs or impl... oh, right, it's named Guard, it must publish on Drop."
  • No IDE functionality: They may or may not figure it out depending on how familiar they are with the guard pattern. But in the worst case, there are always docs to help them :)

---

On a semi-unrelated note, I started a review of your PR #37, but it is soft-blocked on resolving this naming discussion, otherwise I am going to repeat it in the PR and we're going to end up discussing the same topic in two different places.

Do you want me to only post a subset of the review that does not discuss the naming, knowing that I'll also want the naming discussion to be resolved before merging the PR and tagging a release? Or do you want to finish this discussion first, which will enable me to post a PR review with the final chosen naming everywhere?

[crop2000]

Thanks for laying out the different implications of possible names, i couldn't really put that into words. I like the new naming suggestions. I think i should update the PR accordingly. if you have comments on other aspects i am happy to hear them and i would react to them while updating the naming.

[HadrienG2]

Thanks for your contribution !

It's been a while since I tagged a release, so at some point in the coming weeks (pending spare time availability) I'm going to tag a minor release that includes this feature and also begins addressing #30.