Mail Archives: djgpp-workers/2003/05/01/12:23:53
> Date: Wed, 30 Apr 2003 22:10:33 -0400
> From: CBFalconer <cbfalconer AT yahoo DOT com>
> >
> > Also, please produce the diffs like this:
> >
> > diff -c malloc.txh nmalloc.txh
> >
> > Note the "-c" switch--it's very important.
>
> Sigh. I guess I have been too used to being chief honcho :-) Try
> this.
Thanks. Here are my comments:
> ! The size of the currently available top portion of the memory
> ! assigned by sbrk. Sometimes known as 'slop'.
Please change the last sentence into this:
Sometimes known as @dfn{slop}.
(In general, whenever you introduce some new term, it is advisable to
put it into @dfn{}. That causes the term to be typeset in a special
typeface which makes it stand out.
> ! @table @asis
> @item Level 0
> ! The memory allocation functions behave as they do if
> ! @code{malloc_debug} was never called. Only passive checks are
> ! allowed, including malloc_verify, mallocmap, and malldbgdumpfile
Please put all function names, such as malloc_verify,
malldbgdumpfile, etc., in @code{}.
> ! (to set the output file). In particular mallsethook() is
Please don't append "()" to a name of a function to signal that it's a
function; instead, say "@code{mallsethook}". "mallsethook()" looks
like a call to a function with no arguments, which is not what you
meant here.
> ! This function prints a map of the heap storage to the selected
> ! dumpfile. (See malldbgdumpfile).
A cross-reference to another function's description is written like
this:
(@xref{malldbgdumpfile}.)
@xref takes care of producing the leading "See " string in any format
that needs it. It also sets up a hypertext link to the appropriate
node of the manual, unlike the plain text you used.
> ! #include <malldbg.h> /* on non-DJGPP systems */
>
> ! M_HOOKFN mallsethook(enum m_hook_kind which,
> ! M_HOOKFN newhook);
> @end example
>
> @subheading Description
>
> ! These hooks are provided for building custom @code{malloc}
> ! debugging packages.
The original text said "These hooks" because there was a list of
hooks before that. In your modified version, there's no list, so
"These" looks awkward. I'd suggest to change the text to say
something like this:
Several hooks are provided for building custom ...
> Each callback is only called if it
> ! is non- AT code{NULL}; by default, all of them are initialized to a
> @code{NULL} value.
Is the above still true in your implementation?
> + The actual hook to be set is described by the following
> + constants, enumerated in stdlib.h:
> +
> + malloc_HK = 0 on entry to malloc
> + malloc_fail_HK when malloc fails
> + free_HK on entry to free
> + free_null_HK when free is called with a NULL pointer
> + realloc_HK on entry to realloc
> + realloc_exit_HK when realloc exits.
> + HKCOUNT The first invalid value for a hook descriptor.
This will produce badly formatted output, since both `makeinfo' and
TeX collapse multiple whitespace characters and refill text. If you
want the spaces to be preserved, surround this block with
@example DOT DOT AT end example. Better yet, use a @table, like this:
@table @code{}
@item malloc_HK
on entry to malloc
@item malloc_fail_HK
when malloc fails
@item free_HK
on entry to free
@item free_null_HK
when free is called with a NULL pointer
@item realloc_HK
on entry to realloc
@item realloc_exit_HK
when realloc exits
@item HKCOUNT
@end @table
> + and each ``callback'' function is described by:
> +
> + typedef void (*M_HOOKFN)(size_t sz, void *ptr);
> +
Any block of code should be surrounded by @example DOT DOT AT end example.
> + in stdlib.h.
File names, such as `stdlib.h', should be in @file{}.
Also, whenever a line that starts a paragraph, like the one above, is
a continuation of the last line of the previous paragraph, precede it
with @noindent, to prevent `makeinfo' and TeX from indenting the line.
So the above fragment should be written thusly:
and each ``callback'' function is described by:
@example
typedef void (*M_HOOKFN)(size_t sz, void *ptr);
@end example
@nondent
in @file{stdlib.h}.
> + Note that in some cases the parameters supplied to
> + the ``callback'' function will be meaningless, in which case
> + they will be zero or NULL as appropriate.
In addition to function names, please also put any other symbols,
such as ``NULL'' in @code{}.
> + The callback function
> + must NOT call any of malloc, free, or realloc.
Please do not use caps for emphasis, as Texinfo has better means for
doing that: either @emph{} (which typesets as italics) or @strong{}
(which typesets as bold).
> + For access to the internal storage of the malloc arena, see the
> + _sysmalloc() call and the _sysinfo struct.
Struct names, such as ``_sysinfo'', are also symbols, so please put
them in @code{}.
> ! This function allows diverting the output of the malldbg package
> ! to any suitable text file. By default the package uses stderr.
``stderr'' is a symbol, so should be in @code{}.
> ! The ohead value is not useful in the present
> ! implementation.
Please put ``ohead'' and other struct members in @code{}.
Last but not least, thanks for working on this.
- Raw text -