.\" SPDX-License-Identifier: BSD-2-Clause
.\" Copyright (C) 2014 - 2020 Intel Corporation.
.\"
.TH "MEMKIND_DEFAULT" 3 "2015-04-21" "Intel Corporation" "MEMKIND_DEFAULT" \" -*- nroff -*-
.SH "NAME"
memkind_default \- default implementations for 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_default_create(struct memkind " "*kind" ", struct memkind_ops " "*ops" ", const char " "*name" );
.br
.BI "int memkind_default_destroy(struct memkind " "*kind" );
.br
.BI "void *memkind_default_malloc(struct memkind " "*kind" ", size_t " "size" );
.br
.BI "void *memkind_default_calloc(struct memkind " "*kind" ", size_t " "num" ", size_t " "size" );
.br
.BI "int memkind_default_posix_memalign(struct memkind " "*kind" ", void " "**memptr" ", size_t " "alignment" ", size_t " "size" );
.br
.BI "void *memkind_default_realloc(struct memkind " "*kind" ", void " "*ptr" ", size_t " "size" );
.br
.BI "void memkind_default_free(struct memkind " "*kind" ", void " "*ptr" );
.br
.BI "void *memkind_default_mmap(struct memkind " "*kind" ", void " "*addr" ", size_t " "size" );
.br
.BI "int memkind_default_mbind(struct memkind " "*kind" ", void " "*ptr" ", size_t " "len" );
.br
.BI "int memkind_default_get_mmap_flags(struct memkind " "*kind" ", int " "*flags" );
.br
.BI "int memkind_default_get_mbind_mode(struct memkind " "*kind" ", int " "*mode" );
.br
.BI "size_t memkind_default_malloc_usable_size(struct memkind " "*kind" ", void " "*ptr" );
.br
.BI "int memkind_preferred_get_mbind_mode(struct memkind " "*kind" ", int " "*mode" );
.br
.BI "int memkind_interleave_get_mbind_mode(struct memkind " "*kind" ", int " "*mode" );
.br
.BI "int memkind_nohugepage_madvise(struct memkind " "*kind" ", void " "*addr" ", size_t " "size" );
.br
.BI "int memkind_posix_check_alignment(struct memkind " "*kind" ", size_t " "alignment" );
.br
.BI "int memkind_default_get_mbind_nodemask(struct memkind " "*kind" ", unsigned long " "*nodemask" ", unsigned long " "maxnode" );
.br
.BI "void memkind_default_init_once(void);"
.br
.BI "bool size_out_of_bounds(size_t " "size" );
.br
.SH DESCRIPTION
.PP
Default implementations for memkind operations which include a several
useful methods that are not part of the
.B MEMKIND_DEFAULT
kind which is a fall through to the jemalloc implementation.
.PP
.BR memkind_default_create ()
implements the required start up for every kind. If a kind does not
point to this function directly for its
.BR ops.create ()
operation, then the function that it points to must call
.BR memkind_default_create ()
at its start.
.PP
.BR memkind_default_destroy ()
implements the required shutdown for every kind. If a kind does not
point to this function directly for its
.BR ops.destroy ()
operation, then the function that it points to must call
.BR memkind_default_destroy ()
at its end.
.PP
.BR memkind_default_malloc ()
is a direct call through the jemalloc's
.BR malloc ().
.PP
.BR memkind_default_calloc ()
is a direct call through the jemalloc's
.BR calloc ().
.PP
.BR memkind_default_posix_memalign ()
is a direct call through the jemalloc's
.BR posix_memalign ().
.PP
.BR memkind_default_realloc ()
is a direct call through the jemalloc's
.BR realloc ().
.PP
.BR memkind_default_free ()
is a direct call through the jemalloc's
.BR free ().
Note that this method can be called on any pointer returned by a
jemalloc allocation, and in particular, all of the arena
allocations described in
.BR memkind_arena (3)
can use this function for freeing.
.PP
.BR memkind_default_mmap ()
This calls the ops->get_mmap_flags()
operations for the kind, or falls back on the default implementations
if the function pointers are
.IR "NULL" .
The results of these calls are
passed to the
.BR mmap (2)
call to allocate pages from the operating system.  The
.I addr
is the hint passed through to
.BR mmap (2)
and
.I size
is the size of the buffer to be allocated.  The return value is the
allocated buffer or
.B MAP_FAILED
in the case of an error.
.PP
.BR memkind_default_mbind ()
makes calls the kind's
.BR ops.get_mbind_nodemask ()
and
.BR ops.get_mbind_mode ()
operations to gather inputs and then calls the
.BR mbind (2)
system call using the results along with and user input
.I ptr
and
.IR len .
.PP
.BR memkind_default_get_mmap_flags ()
sets
.I flags
to
.BR "MAP_PRIVATE | MAP_ANONYMOUS" .
See
.BR mmap (2)
for more information about these flags.
.PP
.BR memkind_default_get_mbind_mode ()
sets
.I mode
to
.BR MPOL_BIND .
See
.BR mbind (2)
for more information about this flag.
.PP
.BR memkind_default_malloc_usable_size ()
is a direct call through the jemalloc's
.BR malloc_usable_size ().
.PP
.BR memkind_preferred_get_mbind_mode ()
sets
.I mode
to
.BR MPOL_PREFERRED .
See
.BR mbind (2)
for more information about this flag.
.PP
.BR memkind_interleave_get_mbind_mode ()
sets
.I mode
to
.BR MPOL_INTERLEAVE .
See
.BR mbind (2)
for more information about this flag.
.PP
.BR memkind_nohugepage_madvise ()
calls
.BR madvise (2)
with the
.B MADV_NOHUGEPAGE
advice.
See
.BR madvise (2)
for more information about this option.
.PP
.BR memkind_posix_check_alignment ()
can be used to check the alignment value for
.BR memkind_posix_memalign ()
to ensure that is abides by the POSIX requirements:
alignment must be a power of 2 at least as large as
.IR "sizeof(void*)" .
.PP
.BR memkind_default_get_mbind_nodemask ()
wraps jemalloc's
.BR copy_bitmask_to_bitmask .
This function copies body of the bitmask structure into passed pointer.
.PP
.BR memkind_default_init_once ()
initializes heap manager.
.PP
.BR size_out_of_bounds ()
returns true if given size is out of bounds, otherwise will return false.
.SH "COPYRIGHT"
Copyright (C) 2014 - 2020 Intel Corporation. All rights reserved.
.SH "SEE ALSO"
.BR memkind (3),
.BR memkind_arena (3),
.BR memkind_hbw (3),
.BR memkind_hugetlb (3),
.BR memkind_pmem (3),
.BR jemalloc (3),
.BR mbind (2),
.BR mmap (2)