share/man/man3c/door_bind.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_BIND 3C "Mar 22, 2005"
   7 .SH NAME
   8 door_bind, door_unbind \- bind or unbind the current thread with the door
   9 server pool
  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 \fBint\fR \fBdoor_bind\fR(\fBint\fR \fIdid\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBdoor_unbind\fR(\fBvoid\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .LP
  26 The \fBdoor_bind()\fR function associates the current thread with a door server
  27 pool. A door server pool is a private pool of server threads that is available
  28 to serve door invocations associated with the door \fIdid\fR.
  29 .sp
  30 .LP
  31 The \fBdoor_unbind()\fR function breaks the association of \fBdoor_bind()\fR by
  32 removing any private door pool binding that is associated with the current
  33 thread.
  34 .sp
  35 .LP
  36 Normally, door server threads are placed in a global pool of available threads
  37 that invocations on any door can use to dispatch a door invocation. A door that
  38 has been created with \fBDOOR_PRIVATE\fR only uses server threads that have
  39 been associated with the door by \fBdoor_bind()\fR. It is therefore necessary
  40 to bind at least one server thread to doors created with \fBDOOR_PRIVATE\fR.
  41 .sp
  42 .LP
  43 The server thread create function, \fBdoor_server_create()\fR, is initially
  44 called by the system during a \fBdoor_create()\fR operation. See
  45 \fBdoor_server_create\fR(3C) and \fBdoor_create\fR(3C).
  46 .sp
  47 .LP
  48 The current thread is added to the private pool of server threads associated
  49 with a door during the next \fBdoor_return()\fR (that has been issued by the
  50 current thread after an associated \fBdoor_bind()\fR). See
  51 \fBdoor_return\fR(3C). A server thread performing a \fBdoor_bind()\fR on a
  52 door that is already bound to a different door performs an implicit
  53 \fBdoor_unbind()\fR of the previous door.
  54 .sp
  55 .LP
  56 If a process containing threads that have been bound to a door calls
  57 \fBfork\fR(2), the threads in the child process will be bound to an invalid
  58 door, and any calls to \fBdoor_return\fR(3C) will result in an error.
  59 .SH RETURN VALUES
  60 .LP
  61 Upon successful completion, a \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
  62 returned and \fBerrno\fR is set to indicate the error.
  63 .SH ERRORS
  64 .LP
  65 The \fBdoor_bind()\fR and \fBdoor_unbind()\fR functions fail if:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBEBADF\fR\fR
  70 .ad
  71 .RS 10n
  72 The \fIdid\fR argument is not a valid door.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBEBADF\fR\fR
  79 .ad
  80 .RS 10n
  81 The \fBdoor_unbind()\fR function was called by a thread that is currently not
  82 bound.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBEINVAL\fR\fR
  89 .ad
  90 .RS 10n
  91 \fIdid\fR was not created with the \fBDOOR_PRIVATE\fR attribute.
  92 .RE
  93
  94 .SH EXAMPLES
  95 .LP
  96 \fBExample 1 \fRUse \fBdoor_bind()\fR to create private server pools for two
  97 doors.
  98 .sp
  99 .LP
 100 The following example shows the use of \fBdoor_bind()\fR to create private
 101 server pools for two doors, \fBd1\fR and \fBd2\fR. Function \fBmy_create()\fR
 102 is called when a new server thread is needed; it creates a thread running
 103 function, \fBmy_server_create()\fR, which binds itself to one of the two doors.
 104
 105 .sp
 106 .in +2
 107 .nf
 108 #include <door.h>
 109 #include <thread.h>
 110 #include <pthread.h>
 111 thread_key_t door_key;
 112 int d1 = -1;
 113 int d2 = -1;
 114 cond_t cv;       /* statically initialized to zero */
 115 mutex_t lock;    /* statically initialized to zero */
 116
 117 extern void foo(void *, char *, size_t, door_desc_t *, uint_t);
 118 extern void bar(void *, char *, size_t, door_desc_t *, uint_t);
 119
 120 static void *
 121 my_server_create(void *arg)
 122 {
 123         /* wait for d1 & d2 to be initialized */
 124         mutex_lock(&lock);
 125         while (d1 == -1 || d2 == -1)
 126                 cond_wait(&cv, &lock);
 127         mutex_unlock(&lock);
 128
 129         if (arg == (void *)foo){
 130                 /* bind thread with pool associated with d1 */
 131                 thr_setspecific(door_key, (void *)foo);
 132                 if (door_bind(d1) < 0) {
 133                         perror("door_bind"); exit (-1);
 134                 }
 135         } else if (arg == (void *)bar) {
 136                 /* bind thread with pool associated with d2 */
 137                 thr_setspecific(door_key, (void *)bar);
 138                 if (door_bind(d2) < 0) {
 139                 /* bind thread to d2 thread pool */
 140                         perror("door_bind"); exit (-1);
 141                 }
 142         }
 143         pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
 144         door_return(NULL, 0, NULL, 0);  /* Wait for door invocation */
 145 }
 146
 147 static void
 148 my_create(door_info_t *dip)
 149 {
 150         /* Pass the door identity information to create function */
 151         thr_create(NULL, 0, my_server_create, (void *)dip->di_proc,
 152                 THR_BOUND | THR_DETACHED, NULL);
 153 }
 154
 155 main()
 156 {
 157         (void) door_server_create(my_create);
 158         if (thr_keycreate(&door_key, NULL) != 0) {
 159                 perror("thr_keycreate");
 160                 exit(1);
 161         }
 162         mutex_lock(&lock);
 163         d1 = door_create(foo, NULL, DOOR_PRIVATE); /* Private pool */
 164         d2 = door_create(bar, NULL, DOOR_PRIVATE); /* Private pool */
 165         cond_signal(&cv);
 166         mutex_unlock(&lock);
 167         while (1)
 168                 pause();
 169 }
 170 .fi
 171 .in -2
 172
 173 .SH ATTRIBUTES
 174 .LP
 175 See \fBattributes\fR(5) for descriptions of the following attributes:
 176 .sp
 177
 178 .sp
 179 .TS
 180 box;
 181 c | c
 182 l | l .
 183 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 184 _
 185 Architecture    all
 186 _
 187 Interface Stability     Stable
 188 _
 189 MT-Level        Safe
 190 .TE
 191
 192 .SH SEE ALSO
 193 .LP
 194 \fBfork\fR(2), \fBdoor_create\fR(3C), \fBdoor_return\fR(3C),
 195 \fBdoor_server_create\fR(3C), \fBattributes\fR(5)