usr/src/man/man3c/door_server_create.3c

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DOOR_SERVER_CREATE 3C "May 12, 2017"
   7 .SH NAME
   8 door_server_create \- specify an alternative door server thread creation
   9 function
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  14 #include <door.h>
  15
  16 \fBvoid (*)(door_info_t *)\fR \fBdoor_server_create\fR(\fBvoid (*\fR\fIcreate_proc\fR)(door_info_t *));
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .LP
  21 Normally, the doors library creates new door server threads in response to
  22 incoming concurrent door invocations automatically. There is no pre-defined
  23 upper limit on the number of server threads that the system creates in
  24 response to incoming invocations (1 server thread for each active door
  25 invocation). These threads are created with the default thread stack size and
  26 POSIX (see \fBstandards\fR(5)) threads cancellation disabled. The created
  27 threads also have the \fBTHR_BOUND\fR | \fBTHR_DETACHED\fR attributes for
  28 Solaris threads and the \fBPTHREAD_SCOPE_SYSTEM\fR |
  29 \fBPTHREAD_CREATE_DETACHED\fR attributes for POSIX threads. The signal
  30 disposition, and scheduling class of the newly created thread are inherited
  31 from the calling thread (initially from the thread calling
  32 \fBdoor_create()\fR, and subsequently from the current active door server
  33 thread).
  34 .sp
  35 .LP
  36 The \fBdoor_server_create()\fR function allows control over the creation of
  37 server threads needed for door invocations. The procedure \fIcreate_proc\fR is
  38 called every time the available server thread pool is depleted. In the case of
  39 private server pools associated with a door (see the \fBDOOR_PRIVATE\fR
  40 attribute in \fBdoor_create()\fR), information on which pool is depleted is
  41 passed to the create function in the form of a \fBdoor_info_t\fR structure.
  42 The \fBdi_proc\fR and \fBdi_data\fR members of the \fBdoor_info_t\fR structure
  43 can be used as a door identifier associated with the depleted pool. The
  44 \fIcreate_proc\fR procedure may limit the number of server threads created and
  45 may also create server threads with appropriate attributes (stack size,
  46 thread-specific data, POSIX thread cancellation, signal mask, scheduling
  47 attributes, and so forth) for use with door invocations.
  48 .sp
  49 .LP
  50 The overall amount of data and argument descriptors that can be sent through a
  51 door is limited by both the server thread's stack size and by the parameters of
  52 the door itself. See \fBdoor_setparam\fR(3C).
  53 .sp
  54 .LP
  55 The specified server creation function should create user level threads using
  56 \fBthr_create()\fR with the \fBTHR_BOUND\fR flag, or in the case of POSIX
  57 threads, \fBpthread_create()\fR with the \fBPTHREAD_SCOPE_SYSTEM\fR attribute.
  58 The server threads make themselves available for incoming door invocations on
  59 this process by issuing a \fBdoor_return\fR(\fBNULL, 0, NULL, 0\fR). In this
  60 case, the \fBdoor_return()\fR arguments are ignored. See \fBdoor_return\fR(3C)
  61 and \fBthr_create\fR(3C).
  62 .sp
  63 .LP
  64 The server threads created by default are enabled for POSIX thread
  65 cancellations which may lead to unexpected thread terminations while holding
  66 resources (such as locks) if the client aborts the associated
  67 \fBdoor_call()\fR. See \fBdoor_call\fR(3C). Unless the server code is truly
  68 interested in notifications of client aborts during a door invocation and is
  69 prepared to handle such notifications using cancellation handlers, POSIX
  70 thread cancellation should be disabled for server threads using
  71 \fBpthread_setcancelstate\fR (\fBPTHREAD_CANCEL_DISABLE\fR, \fINULL\fR). If all
  72 doors are created with the \fBDOOR_NO_CANCEL\fR flag (see
  73 \fBdoor_create\fR(3C)), the threads will never be cancelled by an aborted
  74 \fBdoor_call()\fR call
  75 .sp
  76 .LP
  77 The \fIcreate_proc\fR procedure need not create any additional server threads
  78 if there is at least one server thread currently active in the process (perhaps
  79 handling another door invocation) or it may create as many as seen fit each
  80 time it is called. If there are no available server threads during an incoming
  81 door invocation, the associated \fBdoor_call()\fR blocks until a server thread
  82 becomes available. The \fIcreate_proc\fR procedure must be MT-Safe.
  83 .SH RETURN VALUES
  84 .LP
  85 Upon successful completion, \fBdoor_server_create()\fR returns a pointer to the
  86 previous server creation function. This function has no failure mode (it cannot
  87 fail).
  88 .SH EXAMPLES
  89 .LP
  90 \fBExample 1 \fRCreating door server threads.
  91 .sp
  92 .LP
  93 The following example creates door server threads with cancellation disabled
  94 and an 8k stack instead of the default stack size:
  95
  96 .sp
  97 .in +2
  98 .nf
  99 #include <door.h>
 100 #include <pthread.h>
 101 #include <thread.h>
 102
 103 void *
 104 my_thread(void *arg)
 105 {
 106         pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
 107         door_return(NULL, 0, NULL, 0);
 108 }
 109 void
 110 my_create(door_info_t *dip)
 111 {
 112         thr_create(NULL, 8192, my_thread, NULL,
 113                    THR_BOUND | THR_DETACHED, NULL);
 114 }
 115 main(\|)
 116 {
 117         (void)door_server_create(my_create);
 118         \|.\|.\|.
 119 }
 120 .fi
 121 .in -2
 122
 123 .SH ATTRIBUTES
 124 .LP
 125 See \fBattributes\fR(5) for descriptions of the following attributes:
 126 .sp
 127
 128 .sp
 129 .TS
 130 box;
 131 c | c
 132 l | l .
 133 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 134 _
 135 Architecture    all
 136 _
 137 Interface Stability     Stable
 138 _
 139 MT-Level        Safe
 140 .TE
 141
 142 .SH SEE ALSO
 143 .LP
 144 \fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_create\fR(3C),
 145 \fBdoor_return\fR(3C), \fBpthread_create\fR(3C),
 146 \fBpthread_setcancelstate\fR(3C), \fBthr_create\fR(3C), \fBattributes\fR(5),
 147 \fBcancellation\fR(5), \fBstandards\fR(5)