.\" SPDX-License-Identifier: BSD-2-Clause
.\" Copyright (C) 2014 - 2021 Intel Corporation.
.\"
.TH "MEMKIND_ARENA" 3 "2015-04-21" "Intel Corporation" "MEMKIND_ARENA" \" -*- nroff -*-
.SH "NAME"
memkind_arena \- jemalloc arena allocation memkind operations.
.br
.BR Note:
This is EXPERIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes) or removed.
.SH "SYNOPSIS"
.sp
.BI "int memkind_arena_create(struct memkind " "*kind" ", struct memkind_ops " "*ops" ", const char " "*name" );
.br
.BI "int memkind_arena_create_map(struct memkind " "*kind" ", extent_hooks_t " "*hooks" );
.br
.BI "int memkind_arena_destroy(struct memkind " "*kind" );
.br
.BI "void *memkind_arena_malloc(struct memkind " "*kind" ", size_t " "size" );
.br
.BI "void *memkind_arena_calloc(struct memkind " "*kind" ", size_t " "num" ", size_t " "size" );
.br
.BI "int memkind_arena_posix_memalign(struct memkind " "*kind" ", void " "**memptr" ", size_t " "alignment" ", size_t " "size" );
.br
.BI "void *memkind_arena_realloc(struct memkind " "*kind" ", void " "*ptr" ", size_t " "size" );
.br
.BI "void *memkind_arena_realloc_with_kind_detect(void " "*ptr" ", size_t " "size" );
.br
.BI "int memkind_thread_get_arena(struct memkind " "*kind" ", unsigned int " "*arena" ", size_t " "size" );
.br
.BI "int memkind_bijective_get_arena(struct memkind " "*kind" ", unsigned int " "*arena" ", size_t " "size" );
.br
.BI "struct memkind *get_kind_by_arena(unsigned " "arena_ind" );
.br
.BI "struct memkind *memkind_arena_detect_kind(void " "*ptr" );
.br
.BI "int memkind_arena_finalize(struct memkind " "*kind" );
.br
.BI "void memkind_arena_init(struct memkind " "*kind" );
.br
.BI "void memkind_arena_free(struct memkind " "*kind" ", void " "*ptr" );
.br
.BI "void memkind_arena_free_with_kind_detect(void " "*ptr" );
.br
.BI "int memkind_arena_update_memory_usage_policy(struct memkind " "*kind" ", memkind_mem_usage_policy " "policy" );
.br
.BI "int memkind_arena_set_max_bg_threads(size_t " "threads_limit" );
.br
.BI "int memkind_arena_set_bg_threads(bool " "state" );
.br
.BI "int memkind_arena_stats_print(void " "(*write_cb) (void *, const char *)" ", void " "*cbopaque" ", memkind_stat_print_opt " "opts" );
.br
.SH DESCRIPTION
This header file is a collection of functions can be used to populate
the memkind operations structure for memory kinds that use jemalloc.
.PP
.BR memkind_arena_create ()
is an implementation of the memkind "create" operation for memory
kinds that use jemalloc.  This calls
.BR memkind_default_create ()
(see
.BR memkind_default (3))
followed by
.BR memkind_arena_create_map ()
described below.
.PP
.BR memkind_arena_create_map ()
creates the
.I arena_map
array for the memkind structure pointed to by
.IR kind
which can be indexed by the
.BR ops.get_arena ()
function from the kind's operations.  If get_arena points
.BR memkind_thread_get_arena ()
then there will be four arenas created for each processor,
and if get_arena points to
.BR memkind_bijective_get_arena ()
then just one arena is created.
.PP
.BR memkind_arena_destroy ()
is an implementation of the memkind "destroy" operation for memory
kinds that use jemalloc.  This releases all of the resources
allocated by
.BR memkind_arena_create ().
.PP
.BR memkind_arena_malloc ()
is an implementation of the memkind "malloc" operation for memory
kinds that use jemalloc.  This allocates memory using the arenas
created by
.BR memkind_arena_create ()
through the jemalloc's
.BR mallocx ()
interface.  It uses the memkind "get_arena" operation to select the
arena.
.PP
.BR memkind_arena_calloc ()
is an implementation of the memkind "calloc" operation for memory
kinds that use jemalloc.  This allocates memory using the arenas
created by
.BR memkind_arena_create ()
through the jemalloc's
.BR mallocx ()
interface.  It uses the memkind "get_arena" operation to select the
arena.
.PP
.BR memkind_arena_posix_memalign ()
is an implementation of the memkind "posix_memalign" operation for memory
kinds that use jemalloc.  This allocates memory using the arenas
created by
.BR memkind_arena_create ()
through the jemalloc's
.BR mallocx ()
interface.  It uses the memkind "get_arena" operation to select the
arena.  The POSIX standard requires that
.BR posix_memalign (3)
may not set
.I errno
however the jemalloc's
.BR mallocx ()
routine may.  In an attempt to abide by the standard
.I errno
is recorded before calling jemalloc's
.BR mallocx ()
and then reset after the call.
.PP
.BR memkind_arena_realloc ()
is an implementation of the memkind "realloc" operation for memory
kinds that use jemalloc.  This allocates memory using the arenas
created by
.BR memkind_arena_create ()
through the jemalloc's
.BR mallocx ()
interface.  It uses the memkind "get_arena" operation to select the
arena.
.PP
.BR memkind_arena_realloc_with_kind_detect ()
function will look up for kind associated to the allocated memory referenced by
.I ptr
and call (depending on kind value)
.BR memkind_arena_realloc ()
or
.BR memkind_default_realloc ().
.PP
.BR memkind_thread_get_arena ()
retrieves the
.I arena
index that is bound to to the calling thread based on a hash of its
thread ID.  The
.I arena
index can be used with the MALLOCX_ARENA macro to set flags for jemalloc's
.BR mallocx ().
.PP
.BR memkind_bijective_arena_get_arena ()
retrieves the
.I arena
index to be used with the MALLOCX_ARENA macro to set flags for jemalloc's
.BR mallocx ().
Use of this operation implies that only one arena is used for the
.IR kind .
.PP
.BR memkind_arena_free ()
is an implementation of the memkind "free" operation for memory
kinds that use jemalloc.  It causes the allocated memory referenced by
.IR ptr ,
which must have been returned by a previous call to
.BR memkind_arena_malloc (),
.BR memkind_arena_calloc ()
or
.BR memkind_arena_realloc ()
to be made available for future allocations.
It uses the memkind "get_arena" operation to select the arena.
.PP
.BR memkind_arena_free_with_kind_detect ()
function will look up for kind associated to the allocated memory referenced by
.I ptr
and call
.BR memkind_arena_free ().
.PP
.BR memkind_arena_detect_kind ()
returns pointer to memory kind structure associated with given allocated memory referenced by
.IR ptr .
.PP
.BR get_kind_by_arena ()
returns pointer to memory kind structure associated with given arena.
.PP
.BR memkind_arena_finalize ()
is an implementation of the memkind "finalize" operation for memory kinds that
use jemalloc. This function releases all resources allocated by
.BR memkind_arena_create ()
and it's called when
.BR main ()
finishes or after calling
.BR exit ()
function.
.PP
.BR memkind_arena_init ()
creates arena map with proper hooks per specified kind.
.PP
.BR memkind_arena_update_memory_usage_policy ()
function changes time, which determine how fast jemalloc returns unused pages back to
the operating system, in other words how fast it deallocates file space.
.PP
.BR memkind_arena_set_max_bg_threads ()
sets the maximum number of internal background worker threads in jemalloc.
The
.I threads_limit
specify limit of background threads which can be enabled ( 0 means no limit).
.PP
.BR memkind_arena_set_bg_threads ()
enables/disables internal background worker threads in jemalloc.
.PP
.BR memkind_arena_stats_print ()
prints summary statistics. This function wraps jemalloc's function
.BR je_malloc_stats_print ().
Uses
.I write_cb
function to print the output. While providing custom writer function, use
.BR syscall(2)
rather than
.BR write(2)
Pass
.IR NULL
in order to use the default write_cb function which prints the output to the stderr. Use
.I cbopaque
parameter in order to pass some data to your
.I write_cb
function. Pass additional options using
.IR "opts".
For more details on
.I opts
see the
.B "MEMORY STATISTICS PRINT OPTIONS"
section below.
Returns MEMKIND_ERROR_INVALID when failed to parse options string, MEMKIND_SUCCESS on success.
.SH "MEMORY STATISTICS PRINT OPTIONS"
The available options for printing statistics:
.TP
.B MEMKIND_STAT_PRINT_ALL
Print all statistics.
.TP
.B MEMKIND_STAT_PRINT_JSON_FORMAT
Print statistics in JSON format.
.TP
.B MEMKIND_STAT_PRINT_OMIT_GENERAL
Omit general information that never changes during execution.
.TP
.B MEMKIND_STAT_PRINT_OMIT_MERGED_ARENA
Omit merged arena statistics.
.TP
.B MEMKIND_STAT_PRINT_OMIT_DESTROYED_MERGED_ARENA
Omit destroyed merged arena statistics.
.TP
.B MEMKIND_STAT_PRINT_OMIT_PER_ARENA
Omit per arena statistics.
.TP
.B MEMKIND_STAT_PRINT_OMIT_PER_SIZE_CLASS_BINS
Omit per size class statistics for bins.
.TP
.B MEMKIND_STAT_PRINT_OMIT_PER_SIZE_CLASS_LARGE
Omit per size class statistics for large objects.
.TP
.B MEMKIND_STAT_PRINT_OMIT_MUTEX
Omit all mutex statistics.
.TP
.B MEMKIND_STAT_PRINT_OMIT_EXTENT
Omit extent statistics.
.PP
.SH "COPYRIGHT"
Copyright (C) 2014 - 2021 Intel Corporation. All rights reserved.
.SH "SEE ALSO"
.BR memkind (3),
.BR memkind_default (3),
.BR memkind_hbw (3),
.BR memkind_hugetlb (3),
.BR memkind_pmem (3),
.BR jemalloc (3),
.BR mbind (2),
.BR mmap (2),
.BR syscall(2),
.BR write(2)