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

Improve arena.<i>.chunk_hooks documentation formatting.

Browse Source
This commit is contained in:
Jason Evans 2015-08-14 13:46:08 -07:00
parent 38f864947b
commit 92e96e3bfc
1 changed files with 46 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
doc/jemalloc.xml.in
View File

@ -1541,7 +1541,7 @@ malloc_conf = "xmalloc:true";]]></programlisting>
to the application having an opportunity to take over chunk to the application having an opportunity to take over chunk
allocation.</para> allocation.</para>
<para><programlisting language="C"><![CDATA[ <programlisting language="C"><![CDATA[
typedef struct { typedef struct {
chunk_alloc_t *alloc; chunk_alloc_t *alloc;
chunk_dalloc_t *dalloc; chunk_dalloc_t *dalloc;
@ -1551,8 +1551,8 @@ typedef struct {
chunk_split_t *split; chunk_split_t *split;
chunk_merge_t *merge; chunk_merge_t *merge;
} chunk_hooks_t;]]></programlisting> } chunk_hooks_t;]]></programlisting>
The <type>chunk_hooks_t</type> structure comprises function pointers <para>The <type>chunk_hooks_t</type> structure comprises function
which are described individually below. jemalloc uses these pointers which are described individually below. jemalloc uses these
functions to manage chunk lifetime, which starts off with allocation of functions to manage chunk lifetime, which starts off with allocation of
mapped committed memory, in the simplest case followed by deallocation. mapped committed memory, in the simplest case followed by deallocation.
However, there are performance and platform reasons to retain chunks for However, there are performance and platform reasons to retain chunks for
@ -1565,7 +1565,7 @@ typedef struct {
operating system kernel do not automatically coalesce and split, e.g. operating system kernel do not automatically coalesce and split, e.g.
Windows.</para> Windows.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef void *<function>(chunk_alloc_t)</function></funcdef> <funcdef>typedef void *<function>(chunk_alloc_t)</function></funcdef>
<paramdef>void *<parameter>chunk</parameter></paramdef> <paramdef>void *<parameter>chunk</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
@ -1574,9 +1574,10 @@ typedef struct {
<paramdef>bool *<parameter>commit</parameter></paramdef> <paramdef>bool *<parameter>commit</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
A chunk allocation function conforms to the <type>chunk_alloc_t</type> <literallayout></literallayout>
type and upon success returns a pointer to <parameter>size</parameter> <para>A chunk allocation function conforms to the
bytes of mapped memory on behalf of arena <type>chunk_alloc_t</type> type and upon success returns a pointer to
<parameter>size</parameter> bytes of mapped memory on behalf of arena
<parameter>arena_ind</parameter> such that the chunk's base address is a <parameter>arena_ind</parameter> such that the chunk's base address is a
multiple of <parameter>alignment</parameter>, as well as setting multiple of <parameter>alignment</parameter>, as well as setting
<parameter>*zero</parameter> to indicate whether the chunk is zeroed and <parameter>*zero</parameter> to indicate whether the chunk is zeroed and
@ -1599,13 +1600,15 @@ typedef struct {
linkend="arena.i.dss"><mallctl>arena.&lt;i&gt;.dss</mallctl></link> linkend="arena.i.dss"><mallctl>arena.&lt;i&gt;.dss</mallctl></link>
setting irrelevant.</para> setting irrelevant.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef bool <function>(chunk_dalloc_t)</function></funcdef> <funcdef>typedef bool <function>(chunk_dalloc_t)</function></funcdef>
<paramdef>void *<parameter>chunk</parameter></paramdef> <paramdef>void *<parameter>chunk</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
<paramdef>bool <parameter>committed</parameter></paramdef> <paramdef>bool <parameter>committed</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
<literallayout></literallayout>
<para>
A chunk deallocation function conforms to the A chunk deallocation function conforms to the
<type>chunk_dalloc_t</type> type and deallocates a <type>chunk_dalloc_t</type> type and deallocates a
<parameter>chunk</parameter> of given <parameter>size</parameter> with <parameter>chunk</parameter> of given <parameter>size</parameter> with
@ -1616,7 +1619,7 @@ typedef struct {
remains mapped, in the same commit state, and available for future use, remains mapped, in the same commit state, and available for future use,
in which case it will be automatically retained for later reuse.</para> in which case it will be automatically retained for later reuse.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef bool <function>(chunk_commit_t)</function></funcdef> <funcdef>typedef bool <function>(chunk_commit_t)</function></funcdef>
<paramdef>void *<parameter>chunk</parameter></paramdef> <paramdef>void *<parameter>chunk</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
@ -1624,11 +1627,12 @@ typedef struct {
<paramdef>size_t <parameter>length</parameter></paramdef> <paramdef>size_t <parameter>length</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
A chunk commit function conforms to the <type>chunk_commit_t</type> type <literallayout></literallayout>
and commits zeroed physical memory to back pages within a <para>A chunk commit function conforms to the
<parameter>chunk</parameter> of given <parameter>size</parameter> at <type>chunk_commit_t</type> type and commits zeroed physical memory to
<parameter>offset</parameter> bytes, extending for back pages within a <parameter>chunk</parameter> of given
<parameter>length</parameter> on behalf of arena <parameter>size</parameter> at <parameter>offset</parameter> bytes,
extending for <parameter>length</parameter> on behalf of arena
<parameter>arena_ind</parameter>, returning false upon success. <parameter>arena_ind</parameter>, returning false upon success.
Committed memory may be committed in absolute terms as on a system that Committed memory may be committed in absolute terms as on a system that
does not overcommit, or in implicit terms as on a system that does not overcommit, or in implicit terms as on a system that
@ -1636,7 +1640,7 @@ typedef struct {
faults. If the function returns true, this indicates insufficient faults. If the function returns true, this indicates insufficient
physical memory to satisfy the request.</para> physical memory to satisfy the request.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef bool <function>(chunk_decommit_t)</function></funcdef> <funcdef>typedef bool <function>(chunk_decommit_t)</function></funcdef>
<paramdef>void *<parameter>chunk</parameter></paramdef> <paramdef>void *<parameter>chunk</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
@ -1644,18 +1648,19 @@ typedef struct {
<paramdef>size_t <parameter>length</parameter></paramdef> <paramdef>size_t <parameter>length</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
A chunk decommit function conforms to the <type>chunk_decommit_t</type> <literallayout></literallayout>
type and decommits any physical memory that is backing pages within a <para>A chunk decommit function conforms to the
<parameter>chunk</parameter> of given <parameter>size</parameter> at <type>chunk_decommit_t</type> type and decommits any physical memory
<parameter>offset</parameter> bytes, extending for that is backing pages within a <parameter>chunk</parameter> of given
<parameter>length</parameter> on behalf of arena <parameter>size</parameter> at <parameter>offset</parameter> bytes,
extending for <parameter>length</parameter> on behalf of arena
<parameter>arena_ind</parameter>, returning false upon success, in which <parameter>arena_ind</parameter>, returning false upon success, in which
case the pages will be committed via the chunk commit function before case the pages will be committed via the chunk commit function before
being reused. If the function returns true, this indicates opt-out from being reused. If the function returns true, this indicates opt-out from
decommit; the memory remains committed and available for future use, in decommit; the memory remains committed and available for future use, in
which case it will be automatically retained for later reuse.</para> which case it will be automatically retained for later reuse.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef bool <function>(chunk_purge_t)</function></funcdef> <funcdef>typedef bool <function>(chunk_purge_t)</function></funcdef>
<paramdef>void *<parameter>chunk</parameter></paramdef> <paramdef>void *<parameter>chunk</parameter></paramdef>
<paramdef>size_t<parameter>size</parameter></paramdef> <paramdef>size_t<parameter>size</parameter></paramdef>
@ -1663,16 +1668,17 @@ typedef struct {
<paramdef>size_t <parameter>length</parameter></paramdef> <paramdef>size_t <parameter>length</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
A chunk purge function conforms to the <type>chunk_purge_t</type> type <literallayout></literallayout>
and optionally discards physical pages within the virtual memory mapping <para>A chunk purge function conforms to the <type>chunk_purge_t</type>
associated with <parameter>chunk</parameter> of given type and optionally discards physical pages within the virtual memory
mapping associated with <parameter>chunk</parameter> of given
<parameter>size</parameter> at <parameter>offset</parameter> bytes, <parameter>size</parameter> at <parameter>offset</parameter> bytes,
extending for <parameter>length</parameter> on behalf of arena extending for <parameter>length</parameter> on behalf of arena
<parameter>arena_ind</parameter>, returning false if pages within the <parameter>arena_ind</parameter>, returning false if pages within the
purged virtual memory range will be zero-filled the next time they are purged virtual memory range will be zero-filled the next time they are
accessed.</para> accessed.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef bool <function>(chunk_split_t)</function></funcdef> <funcdef>typedef bool <function>(chunk_split_t)</function></funcdef>
<paramdef>void *<parameter>chunk</parameter></paramdef> <paramdef>void *<parameter>chunk</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
@ -1681,8 +1687,9 @@ typedef struct {
<paramdef>bool <parameter>committed</parameter></paramdef> <paramdef>bool <parameter>committed</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
A chunk split function conforms to the <type>chunk_split_t</type> type <literallayout></literallayout>
and optionally splits <parameter>chunk</parameter> of given <para>A chunk split function conforms to the <type>chunk_split_t</type>
type and optionally splits <parameter>chunk</parameter> of given
<parameter>size</parameter> into two adjacent chunks, the first of <parameter>size</parameter> into two adjacent chunks, the first of
<parameter>size_a</parameter> bytes, and the second of <parameter>size_a</parameter> bytes, and the second of
<parameter>size_b</parameter> bytes, operating on <parameter>size_b</parameter> bytes, operating on
@ -1692,7 +1699,7 @@ typedef struct {
remains unsplit and therefore should continue to be operated on as a remains unsplit and therefore should continue to be operated on as a
whole.</para> whole.</para>
<para><funcsynopsis><funcprototype> <funcsynopsis><funcprototype>
<funcdef>typedef bool <function>(chunk_merge_t)</function></funcdef> <funcdef>typedef bool <function>(chunk_merge_t)</function></funcdef>
<paramdef>void *<parameter>chunk_a</parameter></paramdef> <paramdef>void *<parameter>chunk_a</parameter></paramdef>
<paramdef>size_t <parameter>size_a</parameter></paramdef> <paramdef>size_t <parameter>size_a</parameter></paramdef>
@ -1701,15 +1708,17 @@ typedef struct {
<paramdef>bool <parameter>committed</parameter></paramdef> <paramdef>bool <parameter>committed</parameter></paramdef>
<paramdef>unsigned <parameter>arena_ind</parameter></paramdef> <paramdef>unsigned <parameter>arena_ind</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
A chunk merge function conforms to the <type>chunk_merge_t</type> type <literallayout></literallayout>
and optionally merges adjacent chunks, <parameter>chunk_a</parameter> of <para>A chunk merge function conforms to the <type>chunk_merge_t</type>
given <parameter>size_a</parameter> and <parameter>chunk_b</parameter> type and optionally merges adjacent chunks,
of given <parameter>size_b</parameter> into one contiguous chunk, <parameter>chunk_a</parameter> of given <parameter>size_a</parameter>
operating on <parameter>committed</parameter>/decommitted memory as and <parameter>chunk_b</parameter> of given
indicated, on behalf of arena <parameter>arena_ind</parameter>, <parameter>size_b</parameter> into one contiguous chunk, operating on
returning false upon success. If the function returns true, this <parameter>committed</parameter>/decommitted memory as indicated, on
indicates that the chunks remain distinct mappings and therefore should behalf of arena <parameter>arena_ind</parameter>, returning false upon
continue to be operated on independently.</para> success. If the function returns true, this indicates that the chunks
remain distinct mappings and therefore should continue to be operated on
independently.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>