From 92e96e3bfc5e02c6d59f0db931f7acb29c3b82ff Mon Sep 17 00:00:00 2001 From: Jason Evans Date: Fri, 14 Aug 2015 13:46:08 -0700 Subject: [PATCH] Improve arena..chunk_hooks documentation formatting. --- doc/jemalloc.xml.in | 83 +++++++++++++++++++++++++-------------------- 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/doc/jemalloc.xml.in b/doc/jemalloc.xml.in index e12abb0d..8fc774b1 100644 --- a/doc/jemalloc.xml.in +++ b/doc/jemalloc.xml.in @@ -1541,7 +1541,7 @@ malloc_conf = "xmalloc:true";]]> to the application having an opportunity to take over chunk allocation. - - The chunk_hooks_t structure comprises function pointers - which are described individually below. jemalloc uses these + The chunk_hooks_t structure comprises function + pointers which are described individually below. jemalloc uses these functions to manage chunk lifetime, which starts off with allocation of mapped committed memory, in the simplest case followed by deallocation. 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. Windows. - + typedef void *(chunk_alloc_t) void *chunk size_t size @@ -1574,9 +1574,10 @@ typedef struct { bool *commit unsigned arena_ind - A chunk allocation function conforms to the chunk_alloc_t - type and upon success returns a pointer to size - bytes of mapped memory on behalf of arena + + A chunk allocation function conforms to the + chunk_alloc_t type and upon success returns a pointer to + size bytes of mapped memory on behalf of arena arena_ind such that the chunk's base address is a multiple of alignment, as well as setting *zero to indicate whether the chunk is zeroed and @@ -1599,13 +1600,15 @@ typedef struct { linkend="arena.i.dss">arena.<i>.dss setting irrelevant. - + typedef bool (chunk_dalloc_t) void *chunk size_t size bool committed unsigned arena_ind + + A chunk deallocation function conforms to the chunk_dalloc_t type and deallocates a chunk of given size with @@ -1616,7 +1619,7 @@ typedef struct { remains mapped, in the same commit state, and available for future use, in which case it will be automatically retained for later reuse. - + typedef bool (chunk_commit_t) void *chunk size_t size @@ -1624,11 +1627,12 @@ typedef struct { size_t length unsigned arena_ind - A chunk commit function conforms to the chunk_commit_t type - and commits zeroed physical memory to back pages within a - chunk of given size at - offset bytes, extending for - length on behalf of arena + + A chunk commit function conforms to the + chunk_commit_t type and commits zeroed physical memory to + back pages within a chunk of given + size at offset bytes, + extending for length on behalf of arena arena_ind, returning false upon success. 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 @@ -1636,7 +1640,7 @@ typedef struct { faults. If the function returns true, this indicates insufficient physical memory to satisfy the request. - + typedef bool (chunk_decommit_t) void *chunk size_t size @@ -1644,18 +1648,19 @@ typedef struct { size_t length unsigned arena_ind - A chunk decommit function conforms to the chunk_decommit_t - type and decommits any physical memory that is backing pages within a - chunk of given size at - offset bytes, extending for - length on behalf of arena + + A chunk decommit function conforms to the + chunk_decommit_t type and decommits any physical memory + that is backing pages within a chunk of given + size at offset bytes, + extending for length on behalf of arena arena_ind, returning false upon success, in which case the pages will be committed via the chunk commit function before being reused. If the function returns true, this indicates opt-out from decommit; the memory remains committed and available for future use, in which case it will be automatically retained for later reuse. - + typedef bool (chunk_purge_t) void *chunk size_tsize @@ -1663,16 +1668,17 @@ typedef struct { size_t length unsigned arena_ind - A chunk purge function conforms to the chunk_purge_t type - and optionally discards physical pages within the virtual memory mapping - associated with chunk of given + + A chunk purge function conforms to the chunk_purge_t + type and optionally discards physical pages within the virtual memory + mapping associated with chunk of given size at offset bytes, extending for length on behalf of arena arena_ind, returning false if pages within the purged virtual memory range will be zero-filled the next time they are accessed. - + typedef bool (chunk_split_t) void *chunk size_t size @@ -1681,8 +1687,9 @@ typedef struct { bool committed unsigned arena_ind - A chunk split function conforms to the chunk_split_t type - and optionally splits chunk of given + + A chunk split function conforms to the chunk_split_t + type and optionally splits chunk of given size into two adjacent chunks, the first of size_a bytes, and the second of size_b bytes, operating on @@ -1692,7 +1699,7 @@ typedef struct { remains unsplit and therefore should continue to be operated on as a whole. - + typedef bool (chunk_merge_t) void *chunk_a size_t size_a @@ -1701,15 +1708,17 @@ typedef struct { bool committed unsigned arena_ind - A chunk merge function conforms to the chunk_merge_t type - and optionally merges adjacent chunks, chunk_a of - given size_a and chunk_b - of given size_b into one contiguous chunk, - operating on committed/decommitted memory as - indicated, on behalf of arena arena_ind, - returning false upon success. If the function returns true, this - indicates that the chunks remain distinct mappings and therefore should - continue to be operated on independently. + + A chunk merge function conforms to the chunk_merge_t + type and optionally merges adjacent chunks, + chunk_a of given size_a + and chunk_b of given + size_b into one contiguous chunk, operating on + committed/decommitted memory as indicated, on + behalf of arena arena_ind, returning false upon + success. If the function returns true, this indicates that the chunks + remain distinct mappings and therefore should continue to be operated on + independently.