cpusetAllocQueueDef(3x) cpusetAllocQueueDef(3x) NAME cpusetAllocQueueDef - allocate a cpuset_QueueDef_t structure SYNOPSIS #include <cpuset.h> cpuset_QueueDef_t *cpusetAllocQueueDef(int count) DESCRIPTION The cpusetAllocQueueDef function is used to allocate memory for a cpuset_QueueDef_t structure. This memory can then be released using the function cpusetFreeQueueDef(3x). The count argument indicates the number of CPUs that will be assigned to the cpuset definition structure. The cpuset_QueueDef_t structure is defined as follows: typedef struct { int flags; char *permfile; cpuset_CPUList_t *cpu; } cpuset_QueueDef_t; The flags member is used to specify various control options for the cpuset queue. It is formed by OR-ing together zero or more of the following values: CPUSET_CPU_EXCLUSIVE Defines a cpuset to be restricted. Only threads attached to the cpuset queue (descendents of an attached thread inherit the attachement) may execute on the CPUs contained in the cpuset. CPUSET_MEMORY_LOCAL Threads assigned to the cpuset will attempt to assign memory only from nodes within the cpuset. Assignment of memory from outside the cpuset will occur only if no free memory is available from within the cpuset. No restrictions are made on memory assignment to threads running outside the cpuset. CPUSET_MEMORY_EXCLUSIVE Threads assigned to the cpuset will attempt to assign memory only from nodes within the cpuset. Assignment of memory from outside the cpuset will occur only if no free memory is available from within the cpuset. Threads not assigned to the cpuset will not use memory from within the cpuset unless no memory outside the cpuset is available. If, at the time a cpuset is created, memory is already assigned to threads that are already running, no attempt will be made to explicitly move this memory. If page migration is enabled, the pages will be migrated when the system detects that most references to the pages are non-local. CPUSET_MEMORY_KERNEL_AVOID The kernel should attempt to avoid allocating memory from nodes contained in this cpuset. If kernel memory requests cannot be satisfied from outside this cpuset, this option will be ignored and allocations will occur from within the cpuset. (This avoidance currently extends only to keeping buffer cache away from the protected nodes.) CPUSET_MEMORY_MANDATORY The kernel will limit all memory allocations to nodes that are contained in this cpuset. If memory requests cannot be satisfied, the allocating process will sleep until memory is available. The process will be killed if no more memory can be allocated. See policies below. CPUSET_POLICY_PAGE Requires MEMORY_MANDATORY. This is the default policy if no policy is specified. This policy will cause the kernel to page user pages to the swap file (see swap(1M)) to free physical memory on the nodes contained in this cpuset. If swap space is exhausted, the process will be killed. CPUSET_POLICY_KILL Requires MEMORY_MANDATORY. The kernel will attempt to free as much space as possible from kernel heaps, but will not page user pages to the swap file. If all physical memory on the nodes contained in this cpuset are exhausted, the process will be killed. CPUSET_POLICY_SHARE_WARN When creating a cpuset, if it is possible for the new cpuset to share memory on a node with another cpuset the new cpuset will be created but a warning message will be issued. POLICY_SHARE_WARN and POLICY_SHARE_FAIL cannot be used together. CPUSET_POLICY_SHARE_FAIL When creating a cpuset, if it is possible for the new cpuset to share memory on a node with another cpuset the new cpuset will fail to be created and an error message will be issued. POLICY_SHARE_WARN and POLICY_SHARE_FAIL cannot be used together. The permfile member is the name of the file that defines the access permissions for the cpuset queue. The file permissions of filename referenced by permfile define access to the cpuset. Every time permissions need to be checked, the current permissions of this file are used. Thus, it is possible to change the access to a particular cpuset without having to tear it down and recreate it, simply by changing the access permissions. Read access to the permfile allows a user to retrieve information about a cpuset, while execute permission allows the user to attach a process to the cpuset. The cpu member is a pointer to a cpuset_CPUList_t structure. The memory for the cpuset_CPUList_t structure is allocated and released when the cpuset_QueueDef_t structure is allocated and released (see cpusetFreeQueueDef(3x)). The cpuset_CPUList_t structure contains the list of CPUs assigned to the cpuset. The cpuset_CPUList_t structure (defind in <cpuset.h>) is defined as follows: typedef struct { int count; cpuid_t *list; } cpuset_CPUList_t; The count member defines the number of CPUs contained in the list. The list member is the pointer to the list (an allocated array) of the CPU IDs. The memory for the list array is allocated and released when the cpuset_CPUList_t structure is allocated and released. The size of the list is determined by the count argument passed into the function cpusetAllocQueueDef. EXAMPLES This example creates a cpuset queue using cpusetCreate(3x) and provides an example of how cpusetAllocQueueDef might be used. The cpuset created will have access controlled by the file /usr/tmp/mypermfile; it will contain CPU IDs 4, 8, and 12; and it will be CPU exclusive and memory exclusive: cpuset_QueueDef_t *qdef; char *qname = "myqueue"; /* Alloc queue def for 3 CPU IDs */ qdef = cpusetAllocQueueDef(3); if (!qdef) { perror("cpusetAllocQueueDef"); exit(1); } /* Define attributes of the cpuset */ qdef->flags = CPUSET_CPU_EXCLUSIVE | CPUSET_MEMORY_EXCLUSIVE; qdef->permfile = "/usr/tmp/mypermfile" qdef->cpu->count = 3; qdef->cpu->list[0] = 4; qdef->cpu->list[1] = 8; qdef->cpu->list[2] = 12; /* Request that the cpuset be created */ if (!cpusetCreate(qname, qdef)) { perror("cpusetCreate"); exit(1); } cpusetFreeQueueDef(qdef); As of IRIX 6.5.21, this cpuset_QueueDef_t references and extended data structure of which it is only part, and the rest of the data structure is hidden. This allows future feature enhancements to cpusets while not impacting existing programs that make use of the cpuset API. To set cpuset queue definition attributes in the extended data structure, you must use the API interfaces. You can continue to to set the flags, permfile, and CPUs as previously described, but it is suggested that you begin using the new interfaces for setting such information. The interfaces for setting the cpuset queue definition attributes are as follows: cpusetSetFlags(3x) Used to set the attribute flags. cpusetSetPermFile(3x) Used to set the name of the permissions file. cpusetSetCPUList(3x) Used to set the list of CPUs to be assigned to the cpuset. cpusetSetMemList(3x) Used to set the list of nodes whose memory will be assigned to the cpuset. cpusetSetNodeList(3x) Used to set the nodes whose CPUs and memory will be assigned to the cpuset. cpusetSetCPULimits(3x) Used to set advisory and mandatory limits on the number of CPUs in the cpuset. cpusetSetMemLimits(3x) Used to set advisory and mandatory limits on the amount of memory that will be included in the cpuset. NOTES cpusetAllocQueueDef is found in the library "libcpuset.so", and will be loaded if the option -lcpuset is used with cc(1) or ld(1). SEE ALSO cpuset(1), cpusetAllocQueueDef(3x), cpusetSetFlags(3x), cpusetSetPermFile(3x), cpusetSetCPUList(3x), cpusetSetMemList(3x), cpusetSetNodeList(3x), cpusetSetCPULimits(3x), cpusetSetMemLimits(3x), cpusetFreeQueueDef(3x), cpuset(5). DIAGNOSTICS If successful, cpusetAllocQueueDef returns a pointer to a cpuset_QueueDef_t structure. If cpusetAllocQueueDef fails, it returns NULL and errno is set to indicate the error. The possible errno values include those returned by sbrk(2) and the following: EINVAL Invalid argument was supplied. The user must supply a value greater than or equal to 0. Page 5