project-base/server-skynet-source-3rd-jemalloc
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Change html manual encoding to UTF-8.

Browse Source 
This works around GitHub's broken automatic reformatting from ISO-8859-1
to UTF-8 when serving static html.

Remove <parameter/> from e.g. <function>malloc<parameter/></function>,
add a custom template that does not append parentheses, and manually
specify them, e.g. <function>malloc()</function>.  This works around
apparently broken XSL formatting that causes <code/> to be emitted in
html (rather than <code></code>, or better yet, nothing).
This commit is contained in:
Jason Evans 2016-09-12 16:12:15 -07:00
parent c716c1e531
commit d4ce47e7fb
3 changed files with 96 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/html.xsl.in
View File

@ -1,4 +1,5 @@
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="@XSLROOT@/html/docbook.xsl"/>
<xsl:import href="@abs_srcroot@doc/stylesheet.xsl"/>
<xsl:output method="xml" encoding="utf-8"/>
</xsl:stylesheet>

182
doc/jemalloc.xml.in
View File

@ -180,20 +180,20 @@
<refsect2>
<title>Standard API</title>
<para>The <function>malloc<parameter/></function> function allocates
<para>The <function>malloc()</function> function allocates
<parameter>size</parameter> bytes of uninitialized memory. The allocated
space is suitably aligned (after possible pointer coercion) for storage
of any type of object.</para>
<para>The <function>calloc<parameter/></function> function allocates
<para>The <function>calloc()</function> function allocates
space for <parameter>number</parameter> objects, each
<parameter>size</parameter> bytes in length. The result is identical to
calling <function>malloc<parameter/></function> with an argument of
calling <function>malloc()</function> with an argument of
<parameter>number</parameter> * <parameter>size</parameter>, with the
exception that the allocated memory is explicitly initialized to zero
bytes.</para>
<para>The <function>posix_memalign<parameter/></function> function
<para>The <function>posix_memalign()</function> function
allocates <parameter>size</parameter> bytes of memory such that the
allocation's base address is a multiple of
<parameter>alignment</parameter>, and returns the allocation in the value
@ -201,7 +201,7 @@
<parameter>alignment</parameter> must be a power of 2 at least as large as
<code language="C">sizeof(<type>void *</type>)</code>.</para>
<para>The <function>aligned_alloc<parameter/></function> function
<para>The <function>aligned_alloc()</function> function
allocates <parameter>size</parameter> bytes of memory such that the
allocation's base address is a multiple of
<parameter>alignment</parameter>. The requested
@ -209,7 +209,7 @@
undefined if <parameter>size</parameter> is not an integral multiple of
<parameter>alignment</parameter>.</para>
<para>The <function>realloc<parameter/></function> function changes the
<para>The <function>realloc()</function> function changes the
size of the previously allocated memory referenced by
<parameter>ptr</parameter> to <parameter>size</parameter> bytes. The
contents of the memory are unchanged up to the lesser of the new and old
@ -217,26 +217,26 @@
portion of the memory are undefined. Upon success, the memory referenced
by <parameter>ptr</parameter> is freed and a pointer to the newly
allocated memory is returned. Note that
<function>realloc<parameter/></function> may move the memory allocation,
<function>realloc()</function> may move the memory allocation,
resulting in a different return value than <parameter>ptr</parameter>.
If <parameter>ptr</parameter> is <constant>NULL</constant>, the
<function>realloc<parameter/></function> function behaves identically to
<function>malloc<parameter/></function> for the specified size.</para>
<function>realloc()</function> function behaves identically to
<function>malloc()</function> for the specified size.</para>
<para>The <function>free<parameter/></function> function causes the
<para>The <function>free()</function> function causes the
allocated memory referenced by <parameter>ptr</parameter> to be made
available for future allocations. If <parameter>ptr</parameter> is
<constant>NULL</constant>, no action occurs.</para>
</refsect2>
<refsect2>
<title>Non-standard API</title>
<para>The <function>mallocx<parameter/></function>,
<function>rallocx<parameter/></function>,
<function>xallocx<parameter/></function>,
<function>sallocx<parameter/></function>,
<function>dallocx<parameter/></function>,
<function>sdallocx<parameter/></function>, and
<function>nallocx<parameter/></function> functions all have a
<para>The <function>mallocx()</function>,
<function>rallocx()</function>,
<function>xallocx()</function>,
<function>sallocx()</function>,
<function>dallocx()</function>,
<function>sdallocx()</function>, and
<function>nallocx()</function> functions all have a
<parameter>flags</parameter> argument that can be used to specify
options. The functions only check the options that are contextually
relevant. Use bitwise or (<code language="C">|</code>) operations to
@ -307,19 +307,19 @@
</variablelist>
</para>
<para>The <function>mallocx<parameter/></function> function allocates at
<para>The <function>mallocx()</function> function allocates at
least <parameter>size</parameter> bytes of memory, and returns a pointer
to the base address of the allocation. Behavior is undefined if
<parameter>size</parameter> is <constant>0</constant>.</para>
<para>The <function>rallocx<parameter/></function> function resizes the
<para>The <function>rallocx()</function> function resizes the
allocation at <parameter>ptr</parameter> to be at least
<parameter>size</parameter> bytes, and returns a pointer to the base
address of the resulting allocation, which may or may not have moved from
its original location. Behavior is undefined if
<parameter>size</parameter> is <constant>0</constant>.</para>
<para>The <function>xallocx<parameter/></function> function resizes the
<para>The <function>xallocx()</function> function resizes the
allocation at <parameter>ptr</parameter> in place to be at least
<parameter>size</parameter> bytes, and returns the real size of the
allocation. If <parameter>extra</parameter> is non-zero, an attempt is
@ -332,32 +332,32 @@
language="C">(<parameter>size</parameter> + <parameter>extra</parameter>
&gt; <constant>SIZE_T_MAX</constant>)</code>.</para>
<para>The <function>sallocx<parameter/></function> function returns the
<para>The <function>sallocx()</function> function returns the
real size of the allocation at <parameter>ptr</parameter>.</para>
<para>The <function>dallocx<parameter/></function> function causes the
<para>The <function>dallocx()</function> function causes the
memory referenced by <parameter>ptr</parameter> to be made available for
future allocations.</para>
<para>The <function>sdallocx<parameter/></function> function is an
extension of <function>dallocx<parameter/></function> with a
<para>The <function>sdallocx()</function> function is an
extension of <function>dallocx()</function> with a
<parameter>size</parameter> parameter to allow the caller to pass in the
allocation size as an optimization. The minimum valid input size is the
original requested size of the allocation, and the maximum valid input
size is the corresponding value returned by
<function>nallocx<parameter/></function> or
<function>sallocx<parameter/></function>.</para>
<function>nallocx()</function> or
<function>sallocx()</function>.</para>
<para>The <function>nallocx<parameter/></function> function allocates no
<para>The <function>nallocx()</function> function allocates no
memory, but it performs the same size computation as the
<function>mallocx<parameter/></function> function, and returns the real
<function>mallocx()</function> function, and returns the real
size of the allocation that would result from the equivalent
<function>mallocx<parameter/></function> function call, or
<function>mallocx()</function> function call, or
<constant>0</constant> if the inputs exceed the maximum supported size
class and/or alignment. Behavior is undefined if
<parameter>size</parameter> is <constant>0</constant>.</para>
<para>The <function>mallctl<parameter/></function> function provides a
<para>The <function>mallctl()</function> function provides a
general interface for introspecting the memory allocator, as well as
setting modifiable parameters and triggering actions. The
period-separated <parameter>name</parameter> argument specifies a
@ -372,12 +372,12 @@
<parameter>newlen</parameter>; otherwise pass <constant>NULL</constant>
and <constant>0</constant>.</para>
<para>The <function>mallctlnametomib<parameter/></function> function
<para>The <function>mallctlnametomib()</function> function
provides a way to avoid repeated name lookups for applications that
repeatedly query the same portion of the namespace, by translating a name
to a &ldquo;Management Information Base&rdquo; (MIB) that can be passed
repeatedly to <function>mallctlbymib<parameter/></function>. Upon
successful return from <function>mallctlnametomib<parameter/></function>,
repeatedly to <function>mallctlbymib()</function>. Upon
successful return from <function>mallctlnametomib()</function>,
<parameter>mibp</parameter> contains an array of
<parameter>*miblenp</parameter> integers, where
<parameter>*miblenp</parameter> is the lesser of the number of components
@ -410,18 +410,18 @@ for (i = 0; i < nbins; i++) {
/* Do something with bin_size... */
}]]></programlisting></para>
<para>The <function>malloc_stats_print<parameter/></function> function
<para>The <function>malloc_stats_print()</function> function
writes human-readable summary statistics via the
<parameter>write_cb</parameter> callback function pointer and
<parameter>cbopaque</parameter> data passed to
<parameter>write_cb</parameter>, or
<function>malloc_message<parameter/></function> if
<function>malloc_message()</function> if
<parameter>write_cb</parameter> is <constant>NULL</constant>. This
function can be called repeatedly. General information that never changes
during execution can be omitted by specifying "g" as a character within
the <parameter>opts</parameter> string. Note that
<function>malloc_message<parameter/></function> uses the
<function>mallctl*<parameter/></function> functions internally, so
<function>malloc_message()</function> uses the
<function>mallctl*()</function> functions internally, so
inconsistent statistics can be reported if multiple threads use these
functions simultaneously. If <option>--enable-stats</option> is specified
during configuration, &ldquo;m&rdquo; and &ldquo;a&rdquo; can be specified
@ -433,15 +433,15 @@ for (i = 0; i < nbins; i++) {
would be required to merge counters that track thread cache
operations.</para>
<para>The <function>malloc_usable_size<parameter/></function> function
<para>The <function>malloc_usable_size()</function> function
returns the usable size of the allocation pointed to by
<parameter>ptr</parameter>. The return value may be larger than the size
that was requested during allocation. The
<function>malloc_usable_size<parameter/></function> function is not a
mechanism for in-place <function>realloc<parameter/></function>; rather
<function>malloc_usable_size()</function> function is not a
mechanism for in-place <function>realloc()</function>; rather
it is provided solely as a tool for introspection purposes. Any
discrepancy between the requested allocation size and the size reported
by <function>malloc_usable_size<parameter/></function> should not be
by <function>malloc_usable_size()</function> should not be
depended on, since such behavior is entirely implementation-dependent.
</para>
</refsect2>
@ -459,7 +459,7 @@ for (i = 0; i < nbins; i++) {
environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in
that order, from left to right as options. Note that
<varname>malloc_conf</varname> may be read before
<function>main<parameter/></function> is entered, so the declaration of
<function>main()</function> is entered, so the declaration of
<varname>malloc_conf</varname> should specify an initializer that contains
the final value to be read by jemalloc. <option>--with-malloc-conf</option>
and <varname>malloc_conf</varname> are compile-time mechanisms, whereas
@ -540,14 +540,14 @@ for (i = 0; i < nbins; i++) {
nearest multiple of the cacheline size, or specify cacheline alignment when
allocating.</para>
<para>The <function>realloc<parameter/></function>,
<function>rallocx<parameter/></function>, and
<function>xallocx<parameter/></function> functions may resize allocations
<para>The <function>realloc()</function>,
<function>rallocx()</function>, and
<function>xallocx()</function> functions may resize allocations
without moving them under limited circumstances. Unlike the
<function>*allocx<parameter/></function> API, the standard API does not
<function>*allocx()</function> API, the standard API does not
officially round up the usable size of an allocation to the nearest size
class, so technically it is necessary to call
<function>realloc<parameter/></function> to grow e.g. a 9-byte allocation to
<function>realloc()</function> to grow e.g. a 9-byte allocation to
16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage
trivially succeeds in place as long as the pre-size and post-size both round
up to the same size class. No other API guarantees are made regarding
@ -686,7 +686,7 @@ for (i = 0; i < nbins; i++) {
<refsect1 id="mallctl_namespace">
<title>MALLCTL NAMESPACE</title>
<para>The following names are defined in the namespace accessible via the
<function>mallctl*<parameter/></function> functions. Value types are
<function>mallctl*()</function> functions. Value types are
specified in parentheses, their readable/writable statuses are encoded as
<literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or
<literal>--</literal>, and required build configuration flags follow, if
@ -717,7 +717,7 @@ for (i = 0; i < nbins; i++) {
<literal>rw</literal>
</term>
<listitem><para>If a value is passed in, refresh the data from which
the <function>mallctl*<parameter/></function> functions report values,
the <function>mallctl*()</function> functions report values,
and increment the epoch. Return the current epoch. This is useful for
detecting whether another thread caused a refresh.</para></listitem>
</varlistentry>
@ -987,19 +987,19 @@ for (i = 0; i < nbins; i++) {
<literal>r-</literal>
</term>
<listitem><para>Enable/disable statistics printing at exit. If
enabled, the <function>malloc_stats_print<parameter/></function>
enabled, the <function>malloc_stats_print()</function>
function is called at program exit via an
<citerefentry><refentrytitle>atexit</refentrytitle>
<manvolnum>3</manvolnum></citerefentry> function. If
<option>--enable-stats</option> is specified during configuration, this
has the potential to cause deadlock for a multi-threaded process that
exits while one or more threads are executing in the memory allocation
functions. Furthermore, <function>atexit<parameter/></function> may
functions. Furthermore, <function>atexit()</function> may
allocate memory during application initialization and then deadlock
internally when jemalloc in turn calls
<function>atexit<parameter/></function>, so this option is not
<function>atexit()</function>, so this option is not
universally usable (though the application can register its own
<function>atexit<parameter/></function> function with equivalent
<function>atexit()</function> function with equivalent
functionality). Therefore, this option should only be used with care;
it is primarily intended as a performance tuning aid during application
development. This option is disabled by default.</para></listitem>
@ -1034,8 +1034,8 @@ for (i = 0; i < nbins; i++) {
<listitem><para>Zero filling enabled/disabled. If enabled, each byte
of uninitialized allocated memory will be initialized to 0. Note that
this initialization only happens once for each byte, so
<function>realloc<parameter/></function> and
<function>rallocx<parameter/></function> calls do not zero memory that
<function>realloc()</function> and
<function>rallocx()</function> calls do not zero memory that
was previously allocated. This is intended for debugging and will
impact performance negatively. This option is disabled by default.
</para></listitem>
@ -1256,11 +1256,11 @@ malloc_conf = "xmalloc:true";]]></programlisting>
<filename>&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.f.heap</filename>,
where <literal>&lt;prefix&gt;</literal> is controlled by the <link
linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link>
option. Note that <function>atexit<parameter/></function> may allocate
option. Note that <function>atexit()</function> may allocate
memory during application initialization and then deadlock internally
when jemalloc in turn calls <function>atexit<parameter/></function>, so
when jemalloc in turn calls <function>atexit()</function>, so
this option is not universally usable (though the application can
register its own <function>atexit<parameter/></function> function with
register its own <function>atexit()</function> function with
equivalent functionality). This option is disabled by
default.</para></listitem>
</varlistentry>
@ -1319,7 +1319,7 @@ malloc_conf = "xmalloc:true";]]></programlisting>
<link
linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link>
mallctl. This is useful for avoiding the overhead of repeated
<function>mallctl*<parameter/></function> calls.</para></listitem>
<function>mallctl*()</function> calls.</para></listitem>
</varlistentry>
<varlistentry id="thread.deallocated">
@ -1346,7 +1346,7 @@ malloc_conf = "xmalloc:true";]]></programlisting>
<link
linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link>
mallctl. This is useful for avoiding the overhead of repeated
<function>mallctl*<parameter/></function> calls.</para></listitem>
<function>mallctl*()</function> calls.</para></listitem>
</varlistentry>
<varlistentry id="thread.tcache.enabled">
@ -2189,8 +2189,8 @@ struct extent_hooks_s {
</term>
<listitem><para>Number of pages within unused extents that are
potentially dirty, and for which
<function>madvise<parameter>...</parameter>
<parameter><constant>MADV_DONTNEED</constant></parameter></function> or
<function>madvise(<parameter>...</parameter>
<parameter><constant>MADV_DONTNEED</constant></parameter>)</function> or
similar has not been called.</para></listitem>
</varlistentry>
@ -2253,8 +2253,8 @@ struct extent_hooks_s {
<literal>r-</literal>
[<option>--enable-stats</option>]
</term>
<listitem><para>Number of <function>madvise<parameter>...</parameter>
<parameter><constant>MADV_DONTNEED</constant></parameter></function> or
<listitem><para>Number of <function>madvise(<parameter>...</parameter>
<parameter><constant>MADV_DONTNEED</constant></parameter>)</function> or
similar calls made to purge dirty pages.</para></listitem>
</varlistentry>
@ -2579,10 +2579,10 @@ MAPPED_LIBRARIES:
to override the function which emits the text strings forming the errors
and warnings if for some reason the <constant>STDERR_FILENO</constant> file
descriptor is not suitable for this.
<function>malloc_message<parameter/></function> takes the
<function>malloc_message()</function> takes the
<parameter>cbopaque</parameter> pointer argument that is
<constant>NULL</constant> unless overridden by the arguments in a call to
<function>malloc_stats_print<parameter/></function>, followed by a string
<function>malloc_stats_print()</function>, followed by a string
pointer. Please note that doing anything which tries to allocate memory in
this function is likely to result in a crash or deadlock.</para>
@ -2593,15 +2593,15 @@ MAPPED_LIBRARIES:
<title>RETURN VALUES</title>
<refsect2>
<title>Standard API</title>
<para>The <function>malloc<parameter/></function> and
<function>calloc<parameter/></function> functions return a pointer to the
<para>The <function>malloc()</function> and
<function>calloc()</function> functions return a pointer to the
allocated memory if successful; otherwise a <constant>NULL</constant>
pointer is returned and <varname>errno</varname> is set to
<errorname>ENOMEM</errorname>.</para>
<para>The <function>posix_memalign<parameter/></function> function
<para>The <function>posix_memalign()</function> function
returns the value 0 if successful; otherwise it returns an error value.
The <function>posix_memalign<parameter/></function> function will fail
The <function>posix_memalign()</function> function will fail
if:
<variablelist>
<varlistentry>
@ -2620,11 +2620,11 @@ MAPPED_LIBRARIES:
</variablelist>
</para>
<para>The <function>aligned_alloc<parameter/></function> function returns
<para>The <function>aligned_alloc()</function> function returns
a pointer to the allocated memory if successful; otherwise a
<constant>NULL</constant> pointer is returned and
<varname>errno</varname> is set. The
<function>aligned_alloc<parameter/></function> function will fail if:
<function>aligned_alloc()</function> function will fail if:
<variablelist>
<varlistentry>
<term><errorname>EINVAL</errorname></term>
@ -2641,44 +2641,44 @@ MAPPED_LIBRARIES:
</variablelist>
</para>
<para>The <function>realloc<parameter/></function> function returns a
<para>The <function>realloc()</function> function returns a
pointer, possibly identical to <parameter>ptr</parameter>, to the
allocated memory if successful; otherwise a <constant>NULL</constant>
pointer is returned, and <varname>errno</varname> is set to
<errorname>ENOMEM</errorname> if the error was the result of an
allocation failure. The <function>realloc<parameter/></function>
allocation failure. The <function>realloc()</function>
function always leaves the original buffer intact when an error occurs.
</para>
<para>The <function>free<parameter/></function> function returns no
<para>The <function>free()</function> function returns no
value.</para>
</refsect2>
<refsect2>
<title>Non-standard API</title>
<para>The <function>mallocx<parameter/></function> and
<function>rallocx<parameter/></function> functions return a pointer to
<para>The <function>mallocx()</function> and
<function>rallocx()</function> functions return a pointer to
the allocated memory if successful; otherwise a <constant>NULL</constant>
pointer is returned to indicate insufficient contiguous memory was
available to service the allocation request. </para>
<para>The <function>xallocx<parameter/></function> function returns the
<para>The <function>xallocx()</function> function returns the
real size of the resulting resized allocation pointed to by
<parameter>ptr</parameter>, which is a value less than
<parameter>size</parameter> if the allocation could not be adequately
grown in place. </para>
<para>The <function>sallocx<parameter/></function> function returns the
<para>The <function>sallocx()</function> function returns the
real size of the allocation pointed to by <parameter>ptr</parameter>.
</para>
<para>The <function>nallocx<parameter/></function> returns the real size
<para>The <function>nallocx()</function> returns the real size
that would result from a successful equivalent
<function>mallocx<parameter/></function> function call, or zero if
<function>mallocx()</function> function call, or zero if
insufficient memory is available to perform the size computation. </para>
<para>The <function>mallctl<parameter/></function>,
<function>mallctlnametomib<parameter/></function>, and
<function>mallctlbymib<parameter/></function> functions return 0 on
<para>The <function>mallctl()</function>,
<function>mallctlnametomib()</function>, and
<function>mallctlbymib()</function> functions return 0 on
success; otherwise they return an error value. The functions will fail
if:
<variablelist>
@ -2714,13 +2714,13 @@ MAPPED_LIBRARIES:
<term><errorname>EFAULT</errorname></term>
<listitem><para>An interface with side effects failed in some way
not directly related to <function>mallctl*<parameter/></function>
not directly related to <function>mallctl*()</function>
read/write processing.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>The <function>malloc_usable_size<parameter/></function> function
<para>The <function>malloc_usable_size()</function> function
returns the usable size of the allocation pointed to by
<parameter>ptr</parameter>. </para>
</refsect2>
@ -2769,13 +2769,13 @@ malloc_conf = "narenas:1";]]></programlisting></para>
</refsect1>
<refsect1 id="standards">
<title>STANDARDS</title>
<para>The <function>malloc<parameter/></function>,
<function>calloc<parameter/></function>,
<function>realloc<parameter/></function>, and
<function>free<parameter/></function> functions conform to ISO/IEC
<para>The <function>malloc()</function>,
<function>calloc()</function>,
<function>realloc()</function>, and
<function>free()</function> functions conform to ISO/IEC
9899:1990 (&ldquo;ISO C90&rdquo;).</para>
<para>The <function>posix_memalign<parameter/></function> function conforms
<para>The <function>posix_memalign()</function> function conforms
to IEEE Std 1003.1-2001 (&ldquo;POSIX.1&rdquo;).</para>
</refsect1>
</refentry>

5
doc/stylesheet.xsl
View File

@ -1,6 +1,9 @@
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
<xsl:param name="function.parens" select="1"/>
<xsl:param name="function.parens" select="0"/>
<xsl:template match="function">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template match="mallctl">
"<xsl:call-template name="inline.monoseq"/>"
</xsl:template>