pset(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
PSET(3)                 NetBSD Library Functions Manual                PSET(3)


NAME

     pset_create, pset_assign, pset_bind, pset_destroy -- processor sets


SYNOPSIS

     #include <sys/pset.h>

     int
     pset_create(psetid_t *psid);

     int
     pset_assign(psetid_t psid, cpuid_t cpuid, psetid_t *opsid);

     int
     pset_bind(psetid_t psid, idtype_t type, id_t id, psetid_t *opsid);

     int
     pset_destroy(psetid_t psid);


DESCRIPTION

     The processor sets API provides the possibility to exclusively dedicate
     specific processors or groups of processors to processes or threads.
     After processes or threads are bound to a group of processors by the API,
     the group henceforth runs only those processes or threads.  This section
     describes the functions used to control processor sets.


FUNCTIONS

     pset_create(psid)
              Creates a processor set, and returns its ID into psid.

     pset_assign(psid, cpu, opsid)
              Assigns the processor specified by cpuid to the processor set
              specified by psid.  Stores the current processor set ID of the
              processor or PS_NONE into opsid, if the pointer is not NULL.

              The following actions can be specified:

                1.   If psid is set to PS_QUERY, then the current processor
                     set ID will be returned into psid, and no assignment will
                     be performed.

                2.   If psid is set to PS_MYID, then the processor set ID of
                     the calling process will be used, and psid will be
                     ignored.

                3.   If psid is set to PS_NONE, any assignment to the proces-
                     sor will be cleared.

     pset_bind(psid, type, id, opsid)
              Dedicates the processor set specified by psid to the target
              specified by id.  The current processor set ID to which the tar-
              get is bound or PS_NONE will be returned in opsid, if the
              pointer is not NULL.  NetBSD supports the following types of
              targets specified by type:

                P_PID    Process identified by the PID.

                P_LWPID  Thread of the calling process identified by the LID.

              The following actions can be specified:

                1.   If psid is set to PS_QUERY, then the current processor
                     set ID to which the target is bound or PS_NONE will be
                     returned in opsid, and no binding will be performed.

                2.   If psid is set to PS_MYID, then the processor set ID of
                     the calling process will be used.

                3.   If psid is set to PS_NONE, the specified target will be
                     unbound from the processor set.

     pset_destroy(psid)
              Destroys the processor set specified by psid.  Before destroying
              the processor set, all related assignments of the processors
              will be cleared, and all bound threads will be unbound.

              If psid is PS_MYID, the processor set ID of the caller thread
              will be used.


IMPLEMENTATION NOTES

     The pset_bind() function can return the current processor set ID to which
     the target is bound, or PS_NONE.  However, for example, the process may
     have many threads, which could be bound to different processor sets.  In
     such a case it is unspecified which thread will be used to return the
     information.

     There is an alternative thread affinity interface, see affinity(3).  How-
     ever, processor sets and thread affinity are mutually exclusive, hence
     mixing of these interfaces is prohibited.


RETURN VALUES

     Upon successful completion these functions return 0.  Otherwise, -1 is
     returned and errno is set to indicate the error.


EXAMPLES

     An example of code fragment, which assigns the CPU whose ID is 0, for
     current process:

             psetid_t psid;
             cpuid_t ci = 0;

             if (pset_create(&psid) < 0)
                     err(EXIT_FAILURE, "pset_create");

             /* Assign CPU 0 to the processor-set */
             if (pset_assign(psid, ci, NULL) < 0)
                     err(EXIT_FAILURE, "pset_assign");

             /* Bind the current process to the processor-set */
             if (pset_bind(psid, P_PID, P_MYID, NULL) < 0)
                     err(EXIT_FAILURE, "pset_bind");

             /*
              * At this point, CPU 0 runs only the current process.
              */
             perform_work();

             if (pset_destroy(psid) < 0)
                     err(EXIT_FAILURE, "pset_destroy");


ERRORS

     The pset_create() function fails if:

     [ENOMEM]           No memory is available for creation of the processor
                        set, or limit of the allowed count of the processor
                        sets was reached.

     [EPERM]            The calling process is not the super-user.

     The pset_assign() function fails if:

     [EBUSY]            Another operation is performing on the processor set.

     [EINVAL]           psid or cpuid are invalid.

     [EPERM]            The calling process is not the super-user, and psid is
                        not PS_QUERY.

     The pset_bind() function fails if:

     [EBUSY]            Another operation is performing on the processor set.

     [EINVAL]           psid or type are invalid.

     [EPERM]            The calling process is not the super-user, and psid is
                        not PS_QUERY.

     [ESRCH]            The specified target was not found.

     The pset_destroy() function fails if:

     [EBUSY]            Another operation is performing on the processor set.

     [EPERM]            The calling process is not the super-user.


SEE ALSO

     affinity(3), cpuset(3), sched(3), schedctl(8)


STANDARDS

     This API is expected to be compatible with the APIs found in Solaris and
     HP-UX operating systems.


HISTORY

     The processor sets appeared in NetBSD 5.0.

NetBSD 10.99                      May 6, 2010                     NetBSD 10.99