unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



numa_types(4)							numa_types(4)



NAME

  numa_types - Data types used by NUMA application interfaces

SYNOPSIS

  #include <&lt;sys/numa_types.h>&gt;

DESCRIPTION

  This reference page lists and	describes the data types, flags, structures,
  and unions that are defined in the <&lt;numa_types.h>&gt; header file	to support
  the Compaq Tru64 UNIX	NUMA APIs.

  The program must call	radsetcreate() or cpusetcreate() to allocate the RAD
  set or CPU set associated with any fields defined as type radset_t or
  cpuset_t, respectively.

  Note that numa_types.h is indirectly included	by the <&lt;numa.h>&gt;	header file,
  which	is the header file more	frequently specified in	the SYNOPSIS sections
  of reference pages for NUMA-related functions.

  Definitions


  The <&lt;numa_types>&gt; header defines the following	data types, flags, struc-
  tures, and unions, and associated symbolic values:

  iopath_t
      Reserved for future use.

  memalloc_attr_t
      A	structure type that defines the	policy and associated parameters for
      memory allocation.  The memalloc_attr structures are associated with
      memory objects and with processes	and threads. This structure contains
      the following members:

      memalloc_policy_t	mattr_policy
	  Specifies the	memory allocation policy (as described in the entry
	  for memalloc_policy_t). Remaining members of the structure contain
	  parameters used to implement this policy.

      radid_t mattr_rad
	  Specifies the	primary	or preferred RAD (region) from which to	allo-
	  cate memory for the MPOL_DIRECTED memory allocation policy.

      int mattr_distance
	  Specifies the	distance to overflow. This value is not	currently
	  used for any memory allocation policy.

      int mattr_stride
	  Specifies the	stride (in pages) for the MPOL_STRIPED memory alloca-
	  tion policy.

      int mattr_pagesz
	  Specifies the	page size in bytes. This value is not currently	used
	  for any memory allocation policy.

      radset_t mattr_radset
	  If mattr_policy is MPOL_DIRECTED or MPOL_THREAD, specifies the
	  overflow RAD set.

	  If mattr_policy is MPOL_STRIPED, specifies the RAD set across	which
	  memory is striped.

  memalloc_policy_t
      An enumeration type that determines, along with associated parameter
      attributes, how memory will be allocated for a memory object or a	ker-
      nel memory allocation request.  Valid policy values are:

      MPOL_DIRECTED
	      Allocate pages from a specified (meaning preferred) RAD with
	      overflow into a specified, possibly NULL,	overflow RAD set.

      MPOL_THREAD
	      Equivalent to MPOL_DIRECTED but having the thread	context
	      determine	the preferred RAD from which pages are allocated. (In
	      this case, the mattr_rad value is	ignored.)

      MPOL_STRIPED
	      Allocate pages so	that they are striped across a specified RAD
	      set by using a specified (page multiple) stripe as specified by
	      the mattr_stride member of the memalloc_attr_t structure.
	      Starting with a specified	RAD, pages will	be allocated from
	      RADs in the RAD set in order of increasing RAD number. An
	      mattr_stride number of pages will	be allocated from each RAD
	      before pages are allocated from the next RAD. After pages	are
	      allocated	from the highest numbered RAD in the set, allocation
	      will wrap, which means that pages	are next allocated from	the
	      lowest numbered RAD in the set.

      MPOL_REPLICATED
	      Replicate	pages on the home RAD of the thread that caused	the
	      pages to be allocated.


					   Note

	     MPOL_REPLICATED is	the default and	only memory allocation policy
	     supported for shared library text pages and program text pages.
	     Furthermore, the operating	system ignores MPOL_REPLICATED when
	     it	is specified for other types of	memory (stack, heap, and
	     shared data pages).  Therefore, specifying	MPOL_REPLICATED	has
	     no	effect in the current implementation.



      The following modifier may be combined (by using a logical OR opera-
      tion) with the preceding policies:

      MPOL_NO_MIGRATE
	      Disable automatic	migration of pages by the system.

      The following table indicates how	different memory policies are sup-
      ported for the different types of	memory in the program address space:


       SHPT = shared program text
       SHLT = shared library text
       SVSHM = System V	shared memory
       STACK = program or thread stack
       DATA = initialized program data
       BSS = uninitialized program data	and heap
       MPRIV = [n]mmap(MAP_PRIVATE)
       MSHAR = [n]mmap(MAP_SHARED)
       MANON = [n]mmap(MAP_ANONYMOUS)


      __________________________________________________________________________
		MPOL_DIRECTED	MPOL_THREAD	 MPOL_STRIPED



								 MPOL_REPLICATED
      __________________________________________________________________________
		Ignored	*			 Ignored *	 Default

      SHPT



				Ignored	*

		Ignored	*			 Ignored *	 Default

      SHLT



				Ignored	*

		As specified.			 Default ***

      SVSHM



				As specified
				but no migra-
				tion. **





								 =MPOL_DIRECTED



		As specified.			 As specified.

      STACK



				Default



								 =MPOL_DIRECTED

		As specified.			 As specified

      DATA



				Default



								 =MPOL_DIRECTED

		As specified.			 As specified.

      BSS



				Default



								 =MPOL_DIRECTED

		As specified.			 As specified.

      MPRIV



				Default



								 =MPOL_DIRECTED

		As specified.			 As specified.

      MSHAR



				Default



								 =MPOL_DIRECTED

		As specified.			 As specified.

      MANON



				Default



								 =MPOL_DIRECTED

      __________________________________________________________________________



      *	      "Ignored"	means only that	the MPOL_* flag	is ignored; the	nmad-
	      vise() call is still checked for errors and any applicable
	      behaviors	are performed.

      **      When thread-local	memory allocation is specified for System V
	      shared memory segments, the policy is used only for pages	that
	      have not yet been	allocated, have	been paged out,	or have	been
	      discarded	(by means of the MADV_DONTNEED flag on an nmadvise()
	      call). Existing pages are	not migrated according to the new
	      memory allocation	policy in order	to avoid thrashing; in other
	      words, the MADV_CURRENT flag on a	nmadvise() call	is treated as
	      MADV_DONTNEED with respect to System V shared memory segments.

      ***     The default memory allocation policy for System V	shared memory
	      segments is configurable.	If the shm_allocate_striped attribute
	      of the IPC kernel	subsystem is set to 1 (the default), SVSHM
	      segments are striped. If this attribute is set to	0, SVSHM seg-
	      ments are	allocated by using the thread local policy
	      (MPOL_THREAD).

  nmemalloc_range_t
      Structures of this type are supported for	internal use only.

  nsgid_t
      Identifier for a NUMA Scheduling Group (NSG).

  numa_attr_t
      A	structure that describes the NUMA topology attributes. This structure
      is used with the nloc() function to query	the NUMA system	topology or
      with the nfork() function	to specify the set of RADs from	which a	RAD
      will be selected for a new process. This structure contains the follow-
      ing members:

      rsrc_type_t nattr_type
		  The type of resource (as described in	the entry for type
		  rsrc_type_t).

      rsrc_descr_t nattr_descr
		  The resource descriptor, which identifies the	instance of
		  the resource specified by the	nattr_type value. Specify
		  this field as	a union	with the appropriate resource handle
		  as described in the entry for	rsrcdescr_t. For example, a
		  resource descriptor for a RAD	set might be specified as:

		  nat.nattr_descr.rd_radset

		  For this descriptor, nat is a	structure of type
		  numa_attr_t, rd_radset is the	resource handle, and
		  nat.nattr_type has been set to R_RAD.

      ulong nattr_distance
		  The distance to the requested	resource. The nloc() function
		  returns a set	of RADs	that are less than or equal this dis-
		  tance	from the specified resource.

      ulong nattr_flags
		  Symbolic values used by certain functions. The nloc(3) and
		  nfork(3) reference pages list	and describe these values.

  radid_t
      Identifier for a Resource	Affinity Domain	(RAD), which is	a grouping of
      basic system resources that form a NUMA building block. NUMA platforms
      contain multiple RADs, and each RAD can contain zero or more CPUs,
      memory arrays, and I/O busses. Single-processor and multiprocessor
      platforms	that do	not use	NUMA architecture are treated by the operat-
      ing system as single-RAD systems.

      The radid_t data type is a generic, integral type, for which there is
      the following symbolic value:

      RAD_NONE
	  No valid RAD ID. Functions return RAD_NONE when no RAD matches the
	  specified criteria, there are	no more	RADs in	a RAD set, and so
	  forth.

  radset_t
      A	set of RADs. This type is used to specify a set	of radid_t values to
      the NUMA APIs. A subset of these APIs perform operations on a set	of
      RADs and manage radset_t as an opaque type.

  rad_cursor_t
      A	opaque type used in an enumeration or an iteration operation on	a RAD
      set. This	type stores the	current	cursor position	during a scan of the
      members in a RAD set. See	rad_foreach(3) for more	information.

  rad_info_t
      A	structure returned by the rad_get_info() function to describe the
      state and	resources associated with a RAD. This structure	contains the
      following	members:

      int rinfo_version
		  The RAD revision number.

      radid_t rinfo_radid
		  The RAD identifier.

      rad_state_t rinfo_state
		  The RAD state, whose values are listed in the	description
		  of the rad_state_t type.

      int rinfo_max_rads
		  The maximum number of	RADs on	the system.

      ssize_t rinfo_physmem
		  The amount of	physical memory	present	in the RAD.

      ssize_t rinfo_freemem
		  The current amount of	free memory available in the RAD.

      cpuset_t rinfo_cpus
		  The set of CPUs associated with the RAD.

      See rad_get_info(3) for more information about querying RAD informa-
      tion.

  rad_state_t
      A	RAD's software state. The defined states are:

      RAD_ONLINE
	      The specified RAD	exists and is on-line. Processes and threads
	      may be assigned to and memory allocated to the RAD.

      RAD_OFFLINE
	      The specified RAD	exists but is not currently on line. No
	      processes	or threads may be assigned to, nor memory allocated
	      to, this RAD; however, its resource complement may be queried.


				       Note

	 RAD_ONLINE is the only	state currently	supported.

  rsrctype_t
      An enumeration type that specifies the kind of resource with which
      affinity is desired. Functions that perform NUMA topology	queries	and
      resource binding pass rsrctype_t arguments along with rsrcdescr_t
      descriptors to identify resources. The following symbolic	values iden-
      tify the type of resource	being specified	by a particular	descriptor:

      R_RAD
	  A RAD	set.

      R_FILDES
	  A file or device referenced by an open file descriptor.

      R_PATH
	  A file or device specified by	a pathname.

      R_SHM
	  A System V shared memory segment that	is referenced by a shared
	  memory ID.

      R_PID
	  A process that is referenced by a pid_t identifier.

      R_MEM
	  A physical memory mapped region that is referenced by	a process
	  virtual address. This	resource type is used to find RADs that	are
	  equal	to or less than	a specified distance from a particular memory
	  location. See	nloc(3).

      R_NSG
	  A NUMA Scheduling Group that is referenced by	an nsgid_t identif-
	  ier.

  rsrcdescr_t
      A	union of the various resource handles, or descriptors, that are
      specified	by different resource type (rsrctype_t)	values.	Along with an
      rsrctype_t argument, an rsrcdescr_t handle is included on	the
      nattr_descr argument to the NUMA APIs that perform NUMA topology
      queries and resource binding. The	resource handles for different
      resource types are as follows:

      radset_t rd_radset
		  If the rsrctype_t value is R_RAD, a RAD set is the
		  resource, for	which rd_radset	is the handle.

      int rd_fd	  If the rsrctype_t value is R_FILDES, an open file or device
		  (referenced by descriptor) is	the resource, for which	rd_fd
		  is the handle.

      char *rd_pathname
		  If the rsrctype_t value is R_PATH, a file or device (refer-
		  enced	by pathname) is	the resource, for which	rd_pathname
		  is the handle.

      int rd_shmid
		  If the rsrctype_t value is R_SHM, a System V shared memory
		  segment is the resource, for which rd_shmid is the handle.

      pid_t rd_pid
		  If the rsrctype_t value is R_PID, a process is the
		  resource, for	which rd_pid is	the handle.

      void *rd_addr
		  If the rsrctype_t value is R_MEM, a mapped region of vir-
		  tual memory is the resource, for which rd_addr is the	han-
		  dle.

      nsgid_t rd_nsg
		  If the rsrctype_t value is R_NSG, a NUMA Scheduling Group
		  is the resource, for which rd_nsg is the handle.

      See nloc(3) and nfork(3) for information about using rsrcdescr_t han-
      dles to query and	bind resources in the context of NUMA system topol-
      ogy.

  struct_nsgid_ds
      A	structure that specifies the access permissions	and associated param-
      eters and	statistics for a NUMA Scheduling Group (NSG). This structure
      contains the following members:

      struct ipc_perm nsg_perm
		  A subordinate	structure that contains	the NSG	access per-
		  missions.

      int nsg_nattach
		  The number of	processes attached to the NSG.

  struct_nsg_thread
      A	structure that specifies a thread (process ID and thread ID) attached
      to an NSG. This structure	contains the following members:

      pid_t nsgth_pid
	  The process ID of a thread that is attached to an NSG.

      unsigned int nsgth_thread
	  The thread ID	(index)	of a thread that is attached to	an NSG.







SEE ALSO

  Functions: nfork(3), nloc(3),	numa_intro(3), rad_foreach(3),
  rad_get_info(3)