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>