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

FreeBSD Manual Pages


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

     domainset(9) -- domainset functions and operation

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

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

     struct domainset *

     struct domainset *

     struct domainset *

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


     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:

	  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.

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

	  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 al-
	  lowed	sets.

	  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).

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

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

BSD			       October 30, 2018				   BSD


Want to link to this manual page? Use this URL:

home | help