Date: Sat, 15 Mar 2003 23:58:18 +1100 (EST) From: Bruce Evans <bde@zeta.org.au> To: Harti Brandt <brandt@fokus.fraunhofer.de> Cc: smp@FreeBSD.ORG, "" <jeff@FreeBSD.ORG> Subject: Re: malloc.9 locking section Message-ID: <20030315230514.A9013@gamplex.bde.org> In-Reply-To: <20030315123530.X45650@beagle.fokus.fraunhofer.de> References: <20030315123530.X45650@beagle.fokus.fraunhofer.de>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, 15 Mar 2003, Harti Brandt wrote:
> attached is a diff to malloc.9 that adds a section 'locking
> considerations' to the man page. I would like to receive comments about
>
> - whether this is altogether useful information to have in the man page
> - about the section name (Solaris calls this section 'CONTEXT')
> - about the section contents itself. I'm quite sure, that I got this
> partly wrong.
> - about the formatting (not beeing a mandoc expert)
> Index: malloc.9
> ===================================================================
> RCS file: /home/ncvs/src/share/man/man9/malloc.9,v
> retrieving revision 1.29
> diff -u -r1.29 malloc.9
> --- malloc.9 5 Feb 2003 14:00:46 -0000 1.29
> +++ malloc.9 15 Mar 2003 11:34:03 -0000
> @@ -230,6 +230,35 @@
> be used with
> .Xr mbuf 9
> routines as it will cause undesired results.
> +.Sh LOCKING CONSIDERATIONS
> +.Fn malloc ,
> +.Fn realloc
> +and
> +.Fn reallocf
> +may be called from threaded and fast interrupts handlers.
> +When called from fast interrupts
> +.Ar flag
> +must contain
> +.Dv M_NOWAIT .
These functions (like most (should be all) functions that aren't in
<machine/atomic.h> or <machine/cpufunc.h>) may NOT be called from fast
interrupt handlers. You may be confused by the bogus and broken check
of td_intr_nesting_level in malloc(). This is supposed to check that
normal interrupt handlers don't call malloc() with M_WAITOK, but has
rotted to only checking that fast interrupt handlers don't do this.
But fast interrupt handlers shouldn't even think of calling malloc().
> +When called from threaded interrupts
> +.Ar flag
> +should contain
s/should/must/
> +.Dv M_NOWAIT .
and not M_WAITOK (*).
> +.Pp
> +.Fn malloc ,
> +.Fn realloc
> +and
> +.Fn reallocf
> +must not be called with
> +.Dv M_WAIT
> +while a mutex other than Giant is held.
I think you mean M_WAITOK (M_WAIT is only for mbufs). It's confusing to
say "flag must contain M_NOWAIT" for ithreads and "must not be called
with M_WAITOK" while a mutex other than Giant is held. The requirements
are the same, and the conditions are almost the same too -- ithreads
might even be implemented using a mutex other than Giant to prevent
them being reentred, though in practice they use a different type of
locking.
> +Giant may or may not be held when
> +.Fn malloc ,
> +.Fn realloc ,
> +.Fn reallocf
> +or
> +.Fn free
> +are called.
This is redundant.
(*) The man page doesn't seem to say that exactly one of {M_NOWAIT,
M_WAITOK}, must be set, perhaps because it has rotted and still
essentially says that M_WAITOK is 0. Changes like the above should
be merged into the rotted bits to fix them and avoid redundancy. Here
are some of the rotted bits:
% Note that
% .Dv M_NOWAIT
% is defined to be 0, meaning that blocking operation is the default.
Nope. Clearly no one reads man section 9 manpages.
% Also note that
% .Dv M_NOWAIT
% is required when running in an interrupt context.
Still correct.
% .Pp
% Programmers should be careful not to confuse
% .Dv M_NOWAIT ,
% the
% .Fn malloc
% flag, with
% .Dv M_DONTWAIT ,
% an
% .Xr mbuf 9
% allocation flag, which is not a valid argument to
% .Fn malloc .
% .It Dv M_WAITOK
% Indicates that it is Ok to wait for resources. It is unconveniently
% defined as 0 so care should be taken never to compare against this value
% directly or try to AND it as a flag. The default operation is to block
% until the memory allocation succeeds.
Mostly rotted.
Bruce
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-smp" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030315230514.A9013>