cpusetAllocQueueDef  - allocate a cpuset_QueueDef_t struc­
       ture


SYNOPSIS

       #include <cpuset.h>

       cpuset_QueueDef_t *cpusetAllocQueueDef(int count)


DESCRIPTION

       The cpusetAllocQueueDef function is used to allocate  mem­
       ory  for  a  cpuset_QueueDef_t structure.  This memory can
       then  be   released   using   the   function   cpusetFree­
       QueueDef(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:

        CCPPUUSSEETT_CCPPUU_EEXXCCLLUUSSIIVVEE
               Defines  a  cpuset to be restricted.  Only threads
               attached to the cpuset queue  (descendents  of  an
               attached  thread inherit the attachement) may exe­
               cute on the CPUs contained in the cpuset.

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

        CCPPUUSSEETT_MMEEMMOORRYY_EEXXCCLLUUSSIIVVEE
               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

               ning,  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.

        CCPPUUSSEETT_MMEEMMOORRYY_KKEERRNNEELL_AAVVOOIIDD
               The kernel should attempt to avoid allocating mem­
               ory from nodes contained in this cpuset. If kernel
               memory requests cannot be satisfied  from  outside
               this cpuset, this option will be ignored and allo­
               cations will occur from within the  cpuset.  (This
               avoidance currently extends only to keeping buffer
               cache away from the protected nodes.)

        CCPPUUSSEETT_MMEEMMOORRYY_MMAANNDDAATTOORRYY
               The kernel will limit all  memory  allocations  to
               nodes that are contained in this cpuset. If memory
               requests cannot be satisfied, the allocating  pro­
               cess  will  sleep  until  memory is available. The
               process will be killed if no more  memory  can  be
               allocated. See policies below.

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

        CCPPUUSSEETT_PPOOLLIICCYY_KKIILLLL
               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 con­
               tained in this cpuset are exhausted,  the  process
               will be killed.

       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 struc­
       ture.  The memory for the  cpuset_CPUList_t  structure  is
       allocated   and   released   when   the  cpuset_QueueDef_t

       QueueDef(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;
                int    *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 deter­
       mined  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 //uussrr//ttmmpp//mmyyppeerrmmffiillee; 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);


NOTES

       cpusetAllocQueueDef   is   found  in  the  library  "libc­
       puset.so", and will be loaded if the  option  --llccppuusseett  is
       used with cc(1) or ld(1).


RESTRICTIONS

       Not  all  of  the above capabilities are implemented.  See
       the RESTRICTIONS secion  in  manual  entry  cpuset(4)  for
       details.


SEE ALSO

       cpuset(1),       cpusetAllocQueueDef(3x),      cpusetFree­
       QueueDef(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  sup­
              ply a value greater than or equal to 0.


Man(1) output converted with man2html