VOP_INACTIVE(9): clarify wording

[asomers]

Summary

VOP_INACTIVE(9): clarify wording

[kib]

I believe a note that VOP_INACTIVE() call is not guaranteed is also due.

[asomers]

Add note that there is no guarantee that VOP_INACTIVE will be called

[0mp]

ok from manpages

[kib]

share/man/man9/VOP_INACTIVE.9

61

I do not know what unclean unmounts are. It is not guaranteed to be called because e.g. it might be called while only owning a shared vnode lock, and non-sleeping upgrade failed due to other shared lockers.

[asomers]

Respond to kib's criticism

[cem]

share/man/man9/VOP_INACTIVE.9

53

This seems a little less clear than before; it could be interpreted as "may be called sometimes when the kernel is still using the vnode."

I might leave this sentence alone, but bring up your "no guarantee" sentence to follow directly after it.

60–61

Hm, can you clarify this sentence? It's called as part of vgonel() even during forced umount. So what is an unclean unmount in this context?

[cem]

share/man/man9/VOP_INACTIVE.9

61

@kib, which path would a VOP_INACTIVE() caller only hold a shared lock?

[asomers]

share/man/man9/VOP_INACTIVE.9

60–61

I meant things like power loss, crash, etc. The filesystem musn't rely exclusively on VOP_INACTIVE to reclaim space in such cases.

[cem]

share/man/man9/VOP_INACTIVE.9

61

Oh, vput/vunref may have a failed lock upgrade. But they still set VI_OWEINACT, so eventually the last other holder should invoke VOP_INACTIVE (or vgonel will).

[cem]

share/man/man9/VOP_INACTIVE.9

60–61

We generally only document API guarantees with the understanding that they only apply if power is consistent and the system does not crash. If we added boilerplate about power loss/crash to every API it would bloat the manuals excessively and make it more difficult to read relevant information.

I don't think there's any particular reason these APIs are different in that respect.

[kib]

share/man/man9/VOP_INACTIVE.9

61

The vnode could be vref-ed while VI_OWEINACT is set, and then if the lock mode is shared, it is still not inactivated. So no, there is no guarantee that vop_inactive necessary called before reclaim.

61

'while the vnode lock could not be upgraded to exclusive without sleeping'.

[asomers]

Use kib's preferred wording.

[cem]

share/man/man9/VOP_INACTIVE.9

61

The vnode could be vref-ed while VI_OWEINACT is set, and then if the lock mode is shared, it is still not inactivated. So no, there is no guarantee that vop_inactive necessary called before reclaim.

I don't follow. If it is vrefed, it gains a non-zero usecount and is marked VI_ACTIVE. In vgonel(), it will still be vinactive -> VOP_INACTIVE()ed before RECLAIM.

[kib]

share/man/man9/VOP_INACTIVE.9

61

VOP_INACTIVE() gerald is to be called on each v_usecount 1->0 transition. This is not guaranteed at least due to the shared locking.

The fact that we might be calling VOP_INACTIVE on next round of 1->0 transition or right before VOP_RECLAIM() call in vgonel() still does not satisfy the promise of calling VOP_INACTIVE on previous v_usecount zeroing.