Document additional aspects of libmemstat(3):
- Short description of each memory type access method. - Descriptions of libmemstat(3) errors and memstat_mtl_geterror(3). MFC after: 1 day
This commit is contained in:
rwatson
parent
ed2ee35685
commit
f689e777d1
@ -16,6 +16,7 @@ MLINKS+= libmemstat.3 memstat_mtl_first.3
|
||||
MLINKS+= libmemstat.3 memstat_mtl_next.3
|
||||
MLINKS+= libmemstat.3 memstat_mtl_find.3
|
||||
MLINKS+= libmemstat.3 memstat_mtl_free.3
|
||||
MLINKS+= libmemstat.3 memstat_mtl_geterror.3
|
||||
MLINKS+= libmemstat.3 memstat_sysctl_all.3
|
||||
MLINKS+= libmemstat.3 memstat_sysctl_malloc.3
|
||||
MLINKS+= libmemstat.3 memstat_sysctl_uma.3
|
||||
|
||||
@ -46,6 +46,8 @@
|
||||
.Fn memstat_mtl_find "struct memory_type_list *list" "int allocator" "const char *name"
|
||||
.Ft void
|
||||
.Fn memstat_mtl_free "struct memory_type_list *list"
|
||||
.Ft int
|
||||
.Fn memstat_mtl_geterror "struct memory_type_list *list"
|
||||
.Ss Allocator Query Functions
|
||||
.Ft int
|
||||
.Fn memstat_sysctl_all "struct memory_type_list *list" "int flags"
|
||||
@ -146,6 +148,10 @@ and
|
||||
.Fn memstat_sysctl_malloc .
|
||||
Repeated calls will incrementally update the list of memory types, permitting
|
||||
tracking over time without recreating all list state.
|
||||
If an error is detected during a query call, error condition information may
|
||||
be retrieved using
|
||||
.Fn memstat_mtl_geterror .
|
||||
.Pp
|
||||
Freeing the list will free all memory type data in the list, and so
|
||||
invalidates any outstanding pointers to entries in the list.
|
||||
.Vt struct memory_type
|
||||
@ -226,6 +232,170 @@ which will only be returned as a result of a library error, and
|
||||
which can be used to specify that returning types matching any allocator is
|
||||
permittible from
|
||||
.Fn memstat_mtl_find .
|
||||
.Ss Access Method List
|
||||
The following accessor methods are defined, of which some will be valid for
|
||||
a given memory type:
|
||||
.Pp
|
||||
.Bl -tag -width "memstat_get_name" -compact -offset wee
|
||||
.It memstat_get_name
|
||||
Return a pointer to the name of the memory type.
|
||||
Memory for the name is owned by
|
||||
.Nm
|
||||
and will be valid through a call to
|
||||
.Fn memstat_mtl_free .
|
||||
Note that names will be unique with respect to a single allocator, but that
|
||||
the same name might be used by different memory types owned by different
|
||||
memory allocators.
|
||||
.It memstat_get_allocator
|
||||
Return an integer identifier for the memory allocator that owns the memory
|
||||
type.
|
||||
.It memstat_get_countlimit
|
||||
If the memory type has an administrative limit on the number of simultaneous
|
||||
allocations, return it.
|
||||
.It memstat_get_byteslimit
|
||||
If the memory type has an administrative limit on the number of bytes of
|
||||
memory that may be simultaenously allocated for the memory type, return it.
|
||||
.It memstat_get_sizemask
|
||||
If the memory type supports variable allocation sizes, return a bitmask of
|
||||
sizes allocated for the memory type.
|
||||
.It memstat_get_size
|
||||
If the memory type supports a fixed allocation size, return that size.
|
||||
.It memstat_get_memalloced
|
||||
Return the total number of bytes allocated for the memory type over its
|
||||
lifetime.
|
||||
.It memstat_get_memfreed
|
||||
Return the total number of bytes freed for the memory type over its lifetime.
|
||||
.It memstat_get_numallocs
|
||||
Return the total number of allocations for the memory type over its lifetime.
|
||||
.It memstat_get_numfrees
|
||||
Return the total number of frees for the memory type over its lifetime.
|
||||
.It memstat_get_bytes
|
||||
Return the current number of bytes allocated to the memory type.
|
||||
.It memstat_get_count
|
||||
Return the current number of allocations for the memory type.
|
||||
.It memstat_get_free
|
||||
If the memory allocator supports a cache, return the number of items in the
|
||||
cache.
|
||||
.It memstat_get_failures
|
||||
If the memory allocator and type permit allocation failures, return the
|
||||
number of allocation failures measured.
|
||||
.It memstat_get_caller_pointer
|
||||
Return a caller-owned pointer for the memory type.
|
||||
.It memstat_set_caller_pointer
|
||||
Set a caller-owned pointer for the memory type.
|
||||
.It memstat_get_caller_uint64
|
||||
Return a caller-owned integer for the memory type.
|
||||
.It memstat_set_caller_uint64
|
||||
Set a caller-owned integer for the memory type.
|
||||
.It memstat_get_zonefree
|
||||
If the memory allocator supports a multi-level allocation structure, return
|
||||
the number of cached items in the zone.
|
||||
These items will be in a fully constructed state available for immediate
|
||||
use.
|
||||
.It memstat_get_kegfree
|
||||
If the memory allocator supports a multi-level allocation structure, return
|
||||
the number of cached items in the keg.
|
||||
These items may be in a partially constructed state, and may require further
|
||||
processing before they can be made available for use.
|
||||
.It memstat_get_percpu_memalloced
|
||||
If the memory allocator supports per-CPU statistics, return the number of
|
||||
bytes of memory allocated for the memory type on the CPU over its lifetime.
|
||||
.It memstat_get_percpu_memfreed
|
||||
If the memory allocator supports per-CPU statistics, return the number of
|
||||
bytes of memory freed from the memory type on the CPU over its lifetime.
|
||||
.It memstat_get_percpu_numallocs
|
||||
If the memory allocator supports per-CPU statistics, return the number of
|
||||
allocations for the memory type on the CPU over its lifetime.
|
||||
.It memstat_get_percpu_numfrees
|
||||
If the memory allocator supports per-CPU statistics, return the number of
|
||||
frees for the memory type on the CPU over its lifetime.
|
||||
.It memstat_get_percpu_sizemask
|
||||
If the memory allocator supports variable size memory allocation and per-CPU
|
||||
statistics, return the size bitmask for the memory type on the CPU.
|
||||
.It memstat_get_percpu_caller_pointer
|
||||
Return a caller-owned per-CPU pointer for the memory type.
|
||||
.It memstat_set_percpu_caller_pointer
|
||||
Set a caller-owned per-CPU pointer for the memory type.
|
||||
.It memstat_get_percpu_caller_uint64
|
||||
Return a caller-owned per-CPU integer for the memory type.
|
||||
.It memsttat_set_percpu_caller_uint64
|
||||
Set a caller-owned per-CPU integer for the memory type.
|
||||
.It memstat_get_percpu_free
|
||||
If the memory allocator supports a per-CPU cache, return the number of free
|
||||
items in the per-CPU cache of the designated CPU.
|
||||
.El
|
||||
.Sh RETURN VALUES
|
||||
.Nm
|
||||
functions fall into three categories: functions returning a pointer to an
|
||||
object, functions returning an integer return value, and functions
|
||||
implementing accessor methods returning data from a
|
||||
.Vt struct memory_type .
|
||||
.Pp
|
||||
Functions returning a pointer to an object will generally return
|
||||
.Dv NULL
|
||||
on failure.
|
||||
.Fn memstat_mtl_alloc
|
||||
will return an error value via
|
||||
.Va errno ,
|
||||
which will consist of the value
|
||||
.Dv ENOMEM .
|
||||
Functions
|
||||
.Fn memstat_mtl_first ,
|
||||
.Fn memstat_mtl_next ,
|
||||
and
|
||||
.Fn memstat_mtl_find
|
||||
will return
|
||||
.Dv NULL
|
||||
when there is no entry or match in the list; however, this is not considered
|
||||
a failure mode and no error value is available.
|
||||
.Pp
|
||||
Functions returning a integer success valuye will return
|
||||
.Dv 0
|
||||
on success, or
|
||||
.Dv -1
|
||||
on failure.
|
||||
If a failure is returned, the list error access method,
|
||||
.Fn memstat_mtl_geterror ,
|
||||
may be used to retrieve the error state. Possible error values are:
|
||||
.Pp
|
||||
.Bl -tag -width "MEMSTAT_ERROR_TOOMANYCPUS" -compact -offset wee
|
||||
.It Dv MEMSTAT_ERROR_UNDEFINED
|
||||
Undefined error. Occurs if
|
||||
.Fn memstat_mtl_geterror
|
||||
is called on a list before an error associated with the list has occurred.
|
||||
.It Dv MEMSTAT_ERROR_NOMEMORY
|
||||
Insufficient memory. Occurs if library calls to
|
||||
.Xr malloc 3
|
||||
fail, or if a system call to retrieve kernel statistics fails with
|
||||
.Er ENOMEM .
|
||||
.It Dv MEMSTAT_ERROR_VERSION
|
||||
Returned if the current version of
|
||||
.Nm
|
||||
is unable to interpret the statistics data returned by the kernel due to an
|
||||
explicit version mismatch, or to differences in data structures that cannot
|
||||
be reconciled.
|
||||
.It Dv MEMSTAT_ERROR_PERMISSION
|
||||
Returned if a statistics source returns
|
||||
.Va errno
|
||||
values of
|
||||
.Dv EACCES
|
||||
or
|
||||
.Dv EPERM .
|
||||
.It Dv MEMSTAT_ERROR_TOOMANYCPUS
|
||||
Returned if the compile-time limit on the number of CPUs in
|
||||
.Nm
|
||||
is lower than the number of CPUs returned by a statistics data source.
|
||||
.It Dv MEMSTAT_ERROR_DATAERROR
|
||||
Returned if
|
||||
.Nm
|
||||
is unable to interpret statistics data returned by the data source, even
|
||||
though there does not appear to be a version problem.
|
||||
.El
|
||||
.Pp
|
||||
Finally, functions returning data from a
|
||||
.Dt struct memory_type
|
||||
pointer are not permitted to fail, and directly return either a statistic
|
||||
or pointer to a string.
|
||||
.Sh EXAMPLES
|
||||
Create a memory type list, query the
|
||||
.Xr uma 9
|
||||
|
||||
Loading…
Reference in New Issue
Block a user