man9: Add an smr(9) manual page

[markj]

Summary

Also update the UMA manual page to mention its SMR-enabled
functionality. Details of its usage are provided in the SMR manual
page.

Sponsored by: The FreeBSD Foundation

[olce]

share/man/man9/smr.9

117–119

Remove formatting, "read section" introduced earlier.

219

The ordering of steps is of paramount importance here. Maybe should we insist even more on it?

260

[olce]

To ease things, I've uploaded a new diff for the whole review that includes proposed changes:

D38108-oc.diff12 KBDownload

.

[markj]

Incorporate review feedback.

[markj]

In D38108#865859, @olce.freebsd_certner.fr wrote:

Hi Mark,

Thanks for doing this.

I find the text of already high quality, so I have only minor suggestions you might want to consider.

Regards.

Thank you very much for the feedback and patch. I incorporated all of it except the "concurrent" -> "concurrently" changes, where I rewrote the sentences instead.

share/man/man9/smr.9

89

I rewrote the sentence to be a bit less awkward: "... allows readers and writers to access the data structure concurrently."

219

I think the level of detail here is probably ok given that most developers won't have to use this part of the interface, but if you have further suggestions I'd be willing to incorporate them. Or is there some specific detail that should be included here?

[olce]

Thanks. I have two further nitpicks. Otherwise, LGTM.

share/man/man9/smr.9

91

Typo.

92

Removed this conjunction I had introduced since the property of entering immediately is not a consequence of concurrent accesses strictly speaking.

219

I just wanted to point out that incrementing the write sequence number must absolutely happen after unlink. The switch to "After" is probably enough.

[olce]

I attached a diff to smr.9 only applying to your latest revision:

share_man_man9_smr.9.diff476 BDownload

.

[markj]

More review feedback.

[mhorne]

I think it would be quite useful to add a short introductory paragraph to locking(9) that describes SMR, and a pointer back to this new page. Obviously, this is a follow-up.

Ideally all synchronization primitives should get a high-level description in locking(9), whether they are lockless or not. Notably, we are missing epoch(9).

[markj]

Update locking.9 as well.

[markj]

In D38108#872018, @mhorne wrote:

I think it would be quite useful to add a short introductory paragraph to locking(9) that describes SMR, and a pointer back to this new page. Obviously, this is a follow-up.

Ideally all synchronization primitives should get a high-level description in locking(9), whether they are lockless or not. Notably, we are missing epoch(9).

I added such a paragraph. epoch and SMR are morally quite similar (long-term they should really be unified) so I mentioned both. I didn't update the interactions table though since that gets rather complicated...

[mhorne]

In D38108#872103, @markj wrote:

In D38108#872018, @mhorne wrote:

I think it would be quite useful to add a short introductory paragraph to locking(9) that describes SMR, and a pointer back to this new page. Obviously, this is a follow-up.

Ideally all synchronization primitives should get a high-level description in locking(9), whether they are lockless or not. Notably, we are missing epoch(9).

I added such a paragraph. epoch and SMR are morally quite similar (long-term they should really be unified) so I mentioned both. I didn't update the interactions table though since that gets rather complicated...

Thank you! I think that is fine about the interaction table, it should probably remain limited to locks only.

share/man/man9/smr.9

42–48

There is no description or MLINK for these two. Is that intended?

234

"smr_poll() is a non-blocking information ..." ???

[markj]

• Add missing MLINKS.
• Fix a typo.

[mhorne]

I am unfamiliar with SMR details, but the main document reads sensibly to me.

[kib]

I think a note along the following lines is useful or even needed.

SMR does not provide safety for readers alone, and users of SMR must use some lock-less algorithm for accessing and modifying the data structure. SMR only provides a variant of the helper to implement safe memory reclamations, for lock-less algorithms.

[pauamma_gundo.com]

share/man/man9/locking.9

439–443 ↗

(On Diff #116441)

Is this still true?

share/man/man9/smr.9

2

SPDX license ID should be in new files. See https://docs.freebsd.org/en/articles/license-guide/#pref-license .

30

Bump on commit

share/man/man9/zone.9

28

Bump on commit.

[markj]

In D38108#872356, @kib wrote:

I think a note along the following lines is useful or even needed.

SMR does not provide safety for readers alone, and users of SMR must use some lock-less algorithm for accessing and modifying the data structure. SMR only provides a variant of the helper to implement safe memory reclamations, for lock-less algorithms.

Yes, I agree. In fact there is more to write about this topic, I did not mention the macros in smr_types.h. At some point those macros should be documented, but I think they aren't used widely enough yet and might be subject to change. So I postponed it for now.

share/man/man9/locking.9

439–443 ↗

(On Diff #116441)

No. That section is nigh useless so I removed it.

[markj]

Handle reviewer notes.

[kib]

Do we want to proclaim a memory model semantic for smr* functions? For instance, the current implementation of smr_enter() has full seq cst semantic, while smr_exit()/smr_lazy_exit() has release. On the other hand, smr_lazy_enter() seems to be relaxed. Do we allow consumers to rely on that, on require user code to handle ordering on its own?

[markj]

In D38108#873501, @kib wrote:

Do we want to proclaim a memory model semantic for smr* functions? For instance, the current implementation of smr_enter() has full seq cst semantic, while smr_exit()/smr_lazy_exit() has release. On the other hand, smr_lazy_enter() seems to be relaxed. Do we allow consumers to rely on that, on require user code to handle ordering on its own?

I think it would be useful to note that smr_enter()/exit() have acquire and release semantics, respectively. The fact that smr_enter() has stronger semantics is an implementation detail that shouldn't be relied upon, I believe.

I didn't document smr_lazy_enter() yet, so won't mention it for now.

[markj]

Note ordering semantics for smr_enter/exit.

[kib]

share/man/man9/smr.9

104

But SMR does not provide a synchronization, it is a substrate to help build the algorithm.

161

What does it mean 'in general'. Can callers rely on the fence always being there, or sometimes it is absent? Also, do we want to guarantee full sc or just an acquire semantic?

163

[gbe]

LGTM from manpages

Three small suggestions for locking.9, but these are more than optional.

Thanks for the work on this manual page.

share/man/man9/locking.9

152 ↗

(On Diff #117214)

Maybe this could be lower case, .Xr smr 9

158 ↗

(On Diff #117214)

Maybe this could be lower case, .Xr smr 9

172 ↗

(On Diff #117214)

Maybe this could be lower case, .Xr smr 9

[markj]

share/man/man9/smr.9

104

I tried to reword the sentence to make this more clear.

161

I simply removed this sentence, since I added a "memory barriers" section.

But yes, we don't want to guarantee SC I think, so I documented smr_enter() as having acquire semantics.

[markj]

• consistently xref smr 9 instead of SMR 9
• move discussion of fences to a separate section
• try to make it clear that SMR is just a component of a lockfree data structure implementation

[pauamma_gundo.com]

Grammar and markup LGTM. Everything else is above my head.

[kib]

share/man/man9/smr.9

86

148

The language is vague, it is not clear if the switching not permitted and consumers must make an action to disable it, or critical_enter() is called for them.

246

259

I would add a sentence that current implementation provides stronger fencing but we do not guarantee that, and it should be not relied upon.

273

275

[markj]

Handle kib's notes.