Manual Pages for UNIX Operating System command usage for man door_server_create

Standard C Library Functions               door_server_create(3C)



NAME
     door_server_create -  specify  an  alternative  door  server
     thread creation function

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

     void (*) () door_server_create(void (*create_proc)(door_info_t*));


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
     THR_BOUND |  THR_DETACHED attributes   for  Solaris  threads
     and  the   PTHREAD_SCOPE_SYSTEM  |   PTHREAD_CREATE_DETACHED
     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
     door_create(), and subsequently from the current active door
     server thread).


     The door_server_create() function allows  control  over  the
     creation  of server threads needed for door invocations. The
     procedure create_proc is called  every  time  the  available
     server  thread  pool  is  depleted.  In  the case of private
     server pools associated with a door  (see the   DOOR_PRIVATE
     attribute  in   door_create()), information on which pool is
     depleted is passed  to the create function in the form of  a
     door_info_t  structure.  The  di_proc and di_data members of
     the door_info_t structure can be  used as a door  identifier
     associated with the depleted pool. The create_proc 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 door_setparam(3C).





SunOS 5.11          Last change: 22 Mar 2005                    1






Standard C Library Functions               door_server_create(3C)



     The specified server creation function  should  create  user
     level  threads  using thr_create() with the  THR_BOUND flag,
     or in the case of POSIX threads, pthread_create()  with  the
     PTHREAD_SCOPE_SYSTEM  attribute.  The  server  threads  make
     themselves available for incoming door invocations  on  this
     process  by issuing a door_return(NULL, 0, NULL, 0). In this
     case,  the   door_return()  arguments   are   ignored.   See
     door_return(3C) and thr_create(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 door_call(). See door_call(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             pthread_setcancelstate
     (PTHREAD_CANCEL_DISABLE,  NULL).  If  all  doors are created
     with the  DOOR_NO_CANCEL  flag  (see  door_create(3C)),  the
     threads  will  never  be cancelled by an aborted door_call()
     call


     The create_proc 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
     door_call() blocks until a server thread becomes  available.
     The create_proc procedure must be MT-Safe.

RETURN VALUES
     Upon successful completion, door_server_create()  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               door_server_create(3C)



       void *
       my_thread(void *arg)
       {
               pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
               door_return(NULL, 0, NULL, 0);
       }
       void
       my_create(door_info_t *dip)
       {
               thr_create(NULL, 8192, my_thread, NULL,
                          THR_BOUND | THR_DETACHED, NULL);
       }
       main()
       {
               (void)door_server_create(my_create);
               ...
       }


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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | all                         |
    |_____________________________|_____________________________|
    | Availability                | SUNWcs                      |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     door_bind(3C),        door_call(3C),        door_create(3C),
     door_return(3C),                         pthread_create(3C),
     pthread_setcancelstate(3C),  thr_create(3C),  attributes(5),
     cancellation(5), standards(5)












SunOS 5.11          Last change: 22 Mar 2005                    3