From f689e777d1bf190fcd7b2185bd64f3ca6a46c45c Mon Sep 17 00:00:00 2001 From: rwatson Date: Sun, 24 Jul 2005 01:29:30 +0000 Subject: 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 --- lib/libmemstat/Makefile | 1 + lib/libmemstat/libmemstat.3 | 170 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 171 insertions(+) (limited to 'lib/libmemstat') diff --git a/lib/libmemstat/Makefile b/lib/libmemstat/Makefile index 464400c..e58f99e 100644 --- a/lib/libmemstat/Makefile +++ b/lib/libmemstat/Makefile @@ -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 diff --git a/lib/libmemstat/libmemstat.3 b/lib/libmemstat/libmemstat.3 index a97d7ba..2e9f0bf 100644 --- a/lib/libmemstat/libmemstat.3 +++ b/lib/libmemstat/libmemstat.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 -- cgit v1.1