Standard C Library Functions                    schedctlinit(3C)



NAME
     schedctlinit,        schedctllookup,        schedctlexit,
     schedctlstart, schedctlstop - preemption control

SYNOPSIS
     cc [ flag... ] file...  [ library... ]
     #include 

     schedctlt *schedctlinit(void);


     schedctlt *schedctllookup(void);


     void schedctlexit(void);


     void schedctlstart(schedctlt *ptr);


     void schedctlstop(schedctlt *ptr);


DESCRIPTION
     These functions provide limited control over the  scheduling
     of a thread (see threads(5)). They allow a running thread to
     give a hint to the kernel that preemptions  of  that  thread
     should  be  avoided. The most likely use for these functions
     is to block preemption while holding  a  spinlock.  Improper
     use of this facility, including attempts to block preemption
     for sustained periods of time, may result in reduced perfor-
     mance.


     The schedctlinit() function initializes preemption  control
     for  the  calling thread and returns a pointer used to refer
     to the data. If schedctlinit() is called more than once  by
     the  same  thread, the most recently returned pointer is the
     only valid one.


     The schedctllookup() function returns the  currently  allo-
     cated  preemption  control  data associated with the calling
     thread that was previously returned by schedctlinit(). This
     can  be useful in programs where it is difficult to maintain
     local state for each thread.


     The schedctlexit() function removes the preemption  control
     data associated with the calling thread.





SunOS 5.11          Last change: 28 May 2003                    1






Standard C Library Functions                    schedctlinit(3C)



     The schedctlstart()  macro  gives  a  hint  to  the  kernel
     scheduler  that  preemption should be avoided on the current
     thread. The pointer passed to the macro must be the same  as
     the  pointer  returned by the call to schedctlinit() by the
     current thread. The  behavior  of  the  program  when  other
     values are passed is undefined.


     The schedctlstop() macro removes the hint that was  set  by
     schedctlstart().  As  with  schedctlstart(),  the  pointer
     passed to the macro must be the same as the pointer returned
     by the call to schedctlinit() by the current thread.


     The schedctlstart() and schedctlstop() macros are intended
     to  be  used to bracket short critical sections, such as the
     time spent holding a spinlock.  Other  uses,  including  the
     failure   to   call   schedctlstop()   soon  after  calling
     schedctlstart(), might result in poor performance.

RETURN VALUES
     The  schedctlinit()  function  returns  a  pointer   to   a
     schedctlt  structure  if the initialization was successful,
     or NUL otherwise. The schedctllookup() function returns  a
     pointer  to  a  schedctlt  structure  if  the data for that
     thread was found, or NUL otherwise.

ERORS
     No errors are returned.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Stable                      
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     priocntl(1), exec(2), fork(2),  priocntl(2),  attributes(5),
     threads(5)

NOTES
     Preemption control is intended for use by threads  belonging
     to  the  time-sharing  (TS),  interactive  (IA),  fair-share



SunOS 5.11          Last change: 28 May 2003                    2






Standard C Library Functions                    schedctlinit(3C)



     (FS), and fixed-priority (FX) scheduling classes.  If  used
     by  threads  in  other scheduling classes, such as real-time
     (RT), no errors will be returned  but  schedctlstart()  and
     schedctlstop() will not have any effect.


     The data used for preemption control are not copied  in  the
     child  of  a  fork(2). Thus, if a process containing threads
     using preemption control calls fork and the child  does  not
     immediately call exec(2), each thread in the child must call
     schedctlinit()  again  prior  to   any   future   uses   of
     schedctlstart()  and schedctlstop(). Failure to do so will
     result in undefined behavior.










































SunOS 5.11          Last change: 28 May 2003                    3