Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DOMAINSET(9)	       FreeBSD Kernel Developer's Manual	  DOMAINSET(9)

NAME
     domainset(9) -- domainset functions and operation

SYNOPSIS
     #include <sys/_domainset.h>
     #include <sys/domainset.h>

	   struct domainset {
		   domainset_t	   ds_mask;
		   uint16_t	   ds_policy;
		   domainid_t	   ds_prefer;
		   ...
	   };

     struct domainset *
     DOMAINSET_FIXED(domain);

     struct domainset *
     DOMAINSET_RR();

     struct domainset *
     DOMAINSET_PREF(domain);

     struct domainset *
     domainset_create(const struct domainset *key);

     int
     sysctl_handle_domainset(SYSCTL_HANDLER_ARGS);

DESCRIPTION
     The domainset(9) API provides memory domain allocation policy for NUMA
     machines.	Each domainset contains	a bitmask of allowed domains, an inte-
     ger policy, and an	optional preferred domain.  Together, these specify a
     search order for memory allocations as well as the	ability	to restrict
     threads and objects to a subset of	available memory domains for system
     partitioning and resource management.

     Every thread in the system	and optionally every vm_object_t, which	is
     used to represent files and other memory sources, has a reference to a
     struct domainset.	The domainset associated with the object is consulted
     first and the system falls	back to	the thread policy if none exists.

     The allocation policy has the following possible values:

     DOMAINSET_POLICY_ROUNDROBIN
	  Memory is allocated from each	domain in the mask in a	round-robin
	  fashion.  This distributes bandwidth evenly among available domains.
	  This policy can specify a single domain for a	fixed allocation.

     DOMAINSET_POLICY_FIRSTTOUCH
	  Memory is allocated from the node that it is first accessed on.
	  Allocation falls back	to round-robin if the current domain is	not in
	  the allowed set or is	out of memory.	This policy optimizes for
	  locality but may give	pessimal results if the	memory is accessed
	  from many CPUs that are not in the local domain.

     DOMAINSET_POLICY_PREFER
	  Memory is allocated from the node in the prefer member.  The pre-
	  ferred node must be set in the allowed mask.	If the preferred node
	  is out of memory the allocation falls	back to	round-robin among
	  allowed sets.

     DOMAINSET_POLICY_INTERLEAVE
	  Memory is allocated in a striped fashion with	multiple pages allo-
	  cated	to each	domain in the set according to the offset within the
	  object.  The strip width is object dependent and may be as large as
	  a super-page (2MB on amd64).	This gives good	distribution among
	  memory domains while keeping system efficiency higher	and is prefer-
	  ential to round-robin	for general use.

     The DOMAINSET_FIXED(), DOMAINSET_RR() and DOMAINSET_PREF()	macros provide
     pointers to global	pre-defined policies for use when the desired policy
     is	known at compile time.	DOMAINSET_FIXED() is a policy which only per-
     mits allocations from the specified domain.  DOMAINSET_RR() provides
     round-robin selection among all domains in	the system.  The
     DOMAINSET_PREF() policies attempt allocation from the specified domain,
     but unlike	DOMAINSET_FIXED() will fall back to other domains to satisfy
     the request.  These policies should be used in preference to
     DOMAINSET_FIXED() to avoid	blocking indefinitely on a M_WAITOK request.
     The domainset_create() function takes a partially filled in domainset as
     a key and returns a valid domainset or NULL.  It is critical that con-
     sumers not	use domainsets that have not been returned by this function.
     domainset is an immutable type that is shared among all matching keys and
     must not be modified after	return.

     The sysctl_handle_domainset() function is provided	as a convenience for
     modifying or viewing domainsets that are not accessible via cpuset(2).
     It	is intended for	use with sysctl(9).

SEE ALSO
     cpuset(1),	cpuset(2), cpuset_setdomain(2),	bitset(9)

HISTORY
     <sys/domainset.h> first appeared in FreeBSD 12.0.

FreeBSD	Ports 11.2	       October 30, 2018		    FreeBSD Ports 11.2

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=domainset&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help