Standard C Library Functions               doorservercreate(3C)



NAME
     doorservercreate -  specify  an  alternative  door  server
     thread creation function

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

     void (*) () doorservercreate(void (*createproc)(doorinfot*));


DESCRIPTION
     Normally, the doors library creates new door  server threads
     in response to incoming concurrent door invocations automat-
     ically. There is no pre-defined upper limit on the number of
     server threads that the system creates in response to incom-
     ing  invocations (1 server thread for each active door invo-
     cation).  These  threads are created with the default thread
     stack size and  POSIX (see standards(5))  threads  cancella-
     tion   disabled.    The   created   threads  also  have  the
     THRBOUND   THRDETACHED attributes   for  Solaris  threads
     and  the   PTHREADSCOPESYSTEM     PTHREADCREATEDETACHED
     attributes for POSIX threads. The  signal  disposition,  and
     scheduling  class of the  newly created thread are inherited
     from the  calling thread (initially from the thread  calling
     doorcreate(), and subsequently from the current active door
     server thread).


     The doorservercreate() function allows  control  over  the
     creation  of server threads needed for door invocations. The
     procedure createproc is called  every  time  the  available
     server  thread  pool  is  depleted.  In  the case of private
     server pools associated with a door  (see the   DORPRIVATE
     attribute  in   doorcreate()), information on which pool is
     depleted is passed  to the create function in the form of  a
     doorinfot  structure.  The  diproc and didata members of
     the doorinfot structure can be  used as a door  identifier
     associated with the depleted pool. The createproc procedure
     may limit the number of  server threads created and may also
     create  server   threads  with appropriate attributes (stack
     size, thread-specific data, POSIX thread cancellation,  sig-
     nal mask, scheduling attributes, and so forth)  for use with
     door invocations.


     The overall amount of data and argument descriptors that can
     be  sent  through  a  door  is  limited  by  both the server
     thread's stack size  and  by  the  parameters  of  the  door
     itself. See doorsetparam(3C).





SunOS 5.11          Last change: 22 Mar 2005                    1






Standard C Library Functions               doorservercreate(3C)



     The specified server creation function  should  create  user
     level  threads  using thrcreate() with the  THRBOUND flag,
     or in the case of POSIX threads, pthreadcreate()  with  the
     PTHREADSCOPESYSTEM  attribute.  The  server  threads  make
     themselves available for incoming door invocations  on  this
     process  by issuing a doorreturn(NUL, 0, NUL, 0). In this
     case,  the   doorreturn()  arguments   are   ignored.   See
     doorreturn(3C) and thrcreate(3C).


     The server threads created by default are enabled for  POSIX
     thread  cancellations  which  may lead to unexpected  thread
     terminations while holding resources  (such as locks) if the
     client aborts the associated doorcall(). See doorcall(3C).
     Unless the server code is truly interested in  notifications
     of  client  aborts during a door invocation and  is prepared
     to handle such notifications using   cancellation  handlers,
     POSIX  thread  cancellation  should   be disabled for server
     threads             using             pthreadsetcancelstate
     (PTHREADCANCELDISABLE,  NUL).  If  all  doors are created
     with the  DORNOCANCEL  flag  (see  doorcreate(3C)),  the
     threads  will  never  be cancelled by an aborted doorcall()
     call


     The createproc procedure need  not  create  any  additional
     server  threads  if  there  is  at  least  one server thread
     currently active in the process  (perhaps  handling  another
     door  invocation)  or it may create as many as seen fit each
     time it is called. If there are no available server  threads
     during   an   incoming   door   invocation,  the  associated
     doorcall() blocks until a server thread becomes  available.
     The createproc procedure must be MT-Safe.

RETURN VALUES
     Upon successful completion, doorservercreate()  returns  a
     pointer to the previous server creation function. This func-
     tion has no failure mode (it cannot fail).

EXAMPLES
     Example 1 Creating door server threads.


     The following example creates door server threads with  can-
     cellation  disabled  and  an 8k stack instead of the default
     stack size:


       #include 
       #include 
       #include 




SunOS 5.11          Last change: 22 Mar 2005                    2






Standard C Library Functions               doorservercreate(3C)



       void *
       mythread(void *arg)
       {
               pthreadsetcancelstate(PTHREADCANCELDISABLE, NUL);
               doorreturn(NUL, 0, NUL, 0);
       }
       void
       mycreate(doorinfot *dip)
       {
               thrcreate(NUL, 8192, mythread, NUL,
                          THRBOUND  THRDETACHED, NUL);
       }
       main()
       {
               (void)doorservercreate(mycreate);
               ...
       }


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 all                         
    
     Availability                 SUNWcsu                     
    
     Interface Stability          Stable                      
    
     MT-Level                     Safe                        
    


SEE ALSO
     doorbind(3C),        doorcall(3C),        doorcreate(3C),
     doorreturn(3C),                         pthreadcreate(3C),
     pthreadsetcancelstate(3C),  thrcreate(3C),  attributes(5),
     cancellation(5), standards(5)












SunOS 5.11          Last change: 22 Mar 2005                    3