Differential D19596 Diff 55118 share/man/man9/VOP_INACTIVE.9

Changeset View

Standalone View

share/man/man9/VOP_INACTIVE.9

	Show All 22 Lines
	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,			.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY			.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT			.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF			.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.			.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd July 27, 2014			.Dd March 15, 2019
	.Dt VOP_INACTIVE 9			.Dt VOP_INACTIVE 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm VOP_INACTIVE ,			.Nm VOP_INACTIVE ,
	.Nm VOP_RECLAIM			.Nm VOP_RECLAIM
	.Nd reclaim file system resources for a vnode			.Nd reclaim file system resources for a vnode
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/param.h			.In sys/param.h
	.In sys/vnode.h			.In sys/vnode.h
	.Ft int			.Ft int
	.Fn VOP_INACTIVE "struct vnode vp" "struct thread td"			.Fn VOP_INACTIVE "struct vnode vp" "struct thread td"
	.Ft int			.Ft int
	.Fn VOP_RECLAIM "struct vnode vp" "struct thread td"			.Fn VOP_RECLAIM "struct vnode vp" "struct thread td"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The arguments are:			The arguments are:
	.Bl -tag -width 2n			.Bl -tag -width 2n
	.It Fa vp			.It Fa vp
	The vnode being reclaimed.			The vnode being reclaimed.
	.El			.El
	.Pp			.Pp
	.Fn VOP_INACTIVE			.Fn VOP_INACTIVE
	is called when the kernel is no longer using the vnode.			is usually called when the kernel is no longer using the vnode.
				However, there is no guarantee that it will be called at all, for example if
				the last reference was dropped while the vnode lock could not be upgraded
				to exclusive without sleeping.
				cemUnsubmitted Not Done Inline Actions 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. cem: This seems a little less clear than before; it could be interpreted as "may be called sometimes…
	This may be			This may be
	because the reference count reaches zero or it may be that the			because the reference count reaches zero or it may be that the
	file system is being forcibly unmounted while there are open files.			file system is being forcibly unmounted while there are open files.
	It can be used to reclaim space for			It can be used to reclaim space on the last close of an
	.Sq open but deleted			.Sq open but deleted
	files.			file.
	.Pp			.Pp
	.Fn VOP_RECLAIM			.Fn VOP_RECLAIM
				kibUnsubmitted Not Done Inline Actions 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. kib: I do not know what unclean unmounts are. It is not guaranteed to be called because e.g. it…
				cemUnsubmitted Not Done Inline Actions @kib, which path would a VOP_INACTIVE() caller only hold a shared lock? cem: @kib, which path would a VOP_INACTIVE() caller only hold a shared lock?
				cemUnsubmitted Not Done Inline Actions 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: Oh, vput/vunref may have a failed lock upgrade. But they still set VI_OWEINACT, so eventually…
				kibUnsubmitted Not Done Inline Actions 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. kib: The vnode could be vref-ed while VI_OWEINACT is set, and then if the lock mode is shared, it is…
				cemUnsubmitted Not Done Inline Actions 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. cem: > The vnode could be vref-ed while VI_OWEINACT is set, and then if the lock mode is shared, it…
				kibUnsubmitted Not Done Inline Actions 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. kib: VOP_INACTIVE() gerald is to be called on each v_usecount 1->0 transition. This is not…
				cemUnsubmitted Done Inline Actions 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: Hm, can you clarify this sentence? It's called as part of vgonel() even during forced umount.
				asomersAuthorUnsubmitted Done Inline Actions I meant things like power loss, crash, etc. The filesystem musn't rely exclusively on VOP_INACTIVE to reclaim space in such cases. asomers: I meant things like power loss, crash, etc. The filesystem musn't rely exclusively on…
				cemUnsubmitted Not Done Inline Actions 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. cem: We generally only document API guarantees with the understanding that they only apply if power…
				kibUnsubmitted Not Done Inline Actions 'while the vnode lock could not be upgraded to exclusive without sleeping'. kib: 'while the vnode lock could not be upgraded to exclusive without sleeping'.
	is called when a vnode is being reused for a different file system.			is called when a vnode is being reused for a different file system.
	Any file system specific resources associated with the vnode should be			Any file system specific resources associated with the vnode should be
	freed.			freed.
	.Sh LOCKS			.Sh LOCKS
	For both			For both
	.Fn VOP_INACTIVE			.Fn VOP_INACTIVE
	and			and
	.Fn VOP_RECLAIM ,			.Fn VOP_RECLAIM ,
	Show All 9 Lines