Page MenuHomeFreeBSD

VOP_PATHCONF.9: add a LOCKS section
ClosedPublic

Authored by asomers on Dec 30 2020, 5:01 AM.

Details

Summary

MFC after: 2 weeks

Diff Detail

Repository
R10 FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

bjk added a subscriber: bjk.

I find it interesting that we have such a long history of a LOCKS section in VOP man pages, given that mdoc(7) includes a list of conventional manual sections, with note that "[t]hese sections should be used unless it's bsolutely necessary that custom sections be used."

Unrelatedly, I think I internalized from some discussion with kib years ago that the preferred way to document VFS locking requirements is with assertions in the code (or vnode_if.src), enforced via DEBUG_VFS_LOCKS.
Other documentation, whether in the form of function comments, man page entries, or otherwise, can become stale and are in some sense redundant.
But perhaps the long history of these sections also applies here :)

That said, the actual mechanics of the mdoc changes are fine.

I echo pretty much all that Benjamin said. It would be nice if there was some way to auto-generate VOP locking documentation requirements from vnode_if.src in some way.

This revision is now accepted and ready to land.Dec 30 2020, 8:44 PM
In D27842#622376, @jhb wrote:

I echo pretty much all that Benjamin said. It would be nice if there was some way to auto-generate VOP locking documentation requirements from vnode_if.src in some way.

Yeah. The other problem with using assertions to document the locking requirements is that the assertions only work for VOP callers. They don't help VOP implementors, like fusefs, to get it right.

This revision was automatically updated to reflect the committed changes.

Yeah. The other problem with using assertions to document the locking requirements is that the assertions only work for VOP callers. They don't help VOP implementors, like fusefs, to get it right.

I had assumed that everyone just looked at the annotations in vnode_if.src ... is there something else I should be doing?