09a263e607
git-subtree-dir: deps/memkind/src git-subtree-split: bb9f19dd1b3ed6cc5e1b35919564ccf6f4b32f69
199 lines
7.4 KiB
Groff
199 lines
7.4 KiB
Groff
.\"
|
|
.\" Copyright (C) 2014 - 2018 Intel Corporation.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright notice(s),
|
|
.\" this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright notice(s),
|
|
.\" this list of conditions and the following disclaimer in the documentation
|
|
.\" and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS
|
|
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
|
|
.\" EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
|
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.TH "MEMKIND_ARENA" 3 "2015-04-21" "Intel Corporation" "MEMKIND_ARENA" \" -*- nroff -*-
|
|
.SH "NAME"
|
|
memkind_arena.h \- jemalloc arena allocation memkind operations.
|
|
.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"
|
|
.nf
|
|
.B #include <memkind/internal/memkind_arena.h>
|
|
.sp
|
|
.B Link with -lmemkind
|
|
.sp
|
|
.BI "int memkind_arena_create(struct memkind " "*kind" ", struct memkind_ops " "*ops" ", const char " "*name" );
|
|
.BI "int memkind_arena_create_map(struct memkind " "*kind" ", extent_hooks_t " "*hooks" );
|
|
.BI "int memkind_arena_destroy(struct memkind " "*kind" );
|
|
.BI "void *memkind_arena_malloc(struct memkind " "*kind" ", size_t " "size" );
|
|
.BI "void *memkind_arena_calloc(struct memkind " "*kind" ", size_t " "num" ", size_t " "size" );
|
|
.BI "void *memkind_arena_pmem_calloc(struct memkind " "*kind" ", size_t " "num" ", size_t " "size" );
|
|
.BI "int memkind_arena_posix_memalign(struct memkind " "*kind" ", void " "**memptr" ", size_t " "alignment" ", size_t " "size" );
|
|
.BI "void *memkind_arena_realloc(struct memkind " "*kind" ", void " "*ptr" ", size_t " "size" );
|
|
.BI "int memkind_thread_get_arena(struct memkind " "*kind" ", unsigned int " "*arena" ", size_t " "size" );
|
|
.BI "int memkind_bijective_get_arena(struct memkind " "*kind" ", unsigned int " "*arena" ", size_t " "size" );
|
|
.BI "struct memkind *get_kind_by_arena(unsigned " "arena_ind" );
|
|
.BI "int memkind_arena_finalize(struct memkind " "*kind" );
|
|
.BI "void memkind_arena_init(struct memkind " "*kind" );
|
|
.BI "void memkind_arena_free(struct memkind " "*kind" ", void " "*ptr" );
|
|
.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.h (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_pmem_calloc ()
|
|
is an implementation of the memkind "calloc" operation for file-backed 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_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 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.
|
|
.SH "COPYRIGHT"
|
|
Copyright (C) 2014 - 2018 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)
|