diff options
Diffstat (limited to 'usr/src/man/man3c/door_bind.3c')
| -rw-r--r-- | usr/src/man/man3c/door_bind.3c | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/usr/src/man/man3c/door_bind.3c b/usr/src/man/man3c/door_bind.3c new file mode 100644 index 0000000000..cc00575aa1 --- /dev/null +++ b/usr/src/man/man3c/door_bind.3c @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH door_bind 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_bind, door_unbind \- bind or unbind the current thread with the door +server pool +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_bind\fR(\fBint\fR \fIdid\fR); +.fi + +.LP +.nf +\fBint\fR \fBdoor_unbind\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_bind()\fR function associates the current thread with a door server +pool. A door server pool is a private pool of server threads that is available +to serve door invocations associated with the door \fIdid\fR. +.sp +.LP +The \fBdoor_unbind()\fR function breaks the association of \fBdoor_bind()\fR by +removing any private door pool binding that is associated with the current +thread. +.sp +.LP +Normally, door server threads are placed in a global pool of available threads +that invocations on any door can use to dispatch a door invocation. A door that +has been created with \fBDOOR_PRIVATE\fR only uses server threads that have +been associated with the door by \fBdoor_bind()\fR. It is therefore necessary +to bind at least one server thread to doors created with \fBDOOR_PRIVATE\fR. +.sp +.LP +The server thread create function, \fBdoor_server_create()\fR, is initially +called by the system during a \fBdoor_create()\fR operation. See +\fBdoor_server_create\fR(3C) and \fBdoor_create\fR(3C). +.sp +.LP +The current thread is added to the private pool of server threads associated +with a door during the next \fBdoor_return()\fR (that has been issued by the +current thread after an associated \fBdoor_bind()\fR). See +\fBdoor_return\fR(3C). A server thread performing a \fBdoor_bind()\fR on a +door that is already bound to a different door performs an implicit +\fBdoor_unbind()\fR of the previous door. +.sp +.LP +If a process containing threads that have been bound to a door calls +\fBfork\fR(2), the threads in the child process will be bound to an invalid +door, and any calls to \fBdoor_return\fR(3C) will result in an error. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_bind()\fR and \fBdoor_unbind()\fR functions fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIdid\fR argument is not a valid door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fBdoor_unbind()\fR function was called by a thread that is currently not +bound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIdid\fR was not created with the \fBDOOR_PRIVATE\fR attribute. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBdoor_bind()\fR to create private server pools for two +doors. +.sp +.LP +The following example shows the use of \fBdoor_bind()\fR to create private +server pools for two doors, \fBd1\fR and \fBd2\fR. Function \fBmy_create()\fR +is called when a new server thread is needed; it creates a thread running +function, \fBmy_server_create()\fR, which binds itself to one of the two doors. + +.sp +.in +2 +.nf +#include <door.h> +#include <thread.h> +#include <pthread.h> +thread_key_t door_key; +int d1 = -1; +int d2 = -1; +cond_t cv; /* statically initialized to zero */ +mutex_t lock; /* statically initialized to zero */ + +extern void foo(void *, char *, size_t, door_desc_t *, uint_t); +extern void bar(void *, char *, size_t, door_desc_t *, uint_t); + +static void * +my_server_create(void *arg) +{ + /* wait for d1 & d2 to be initialized */ + mutex_lock(&lock); + while (d1 == -1 || d2 == -1) + cond_wait(&cv, &lock); + mutex_unlock(&lock); + + if (arg == (void *)foo){ + /* bind thread with pool associated with d1 */ + thr_setspecific(door_key, (void *)foo); + if (door_bind(d1) < 0) { + perror("door_bind"); exit (-1); + } + } else if (arg == (void *)bar) { + /* bind thread with pool associated with d2 */ + thr_setspecific(door_key, (void *)bar); + if (door_bind(d2) < 0) { + /* bind thread to d2 thread pool */ + perror("door_bind"); exit (-1); + } + } + pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + door_return(NULL, 0, NULL, 0); /* Wait for door invocation */ +} + +static void +my_create(door_info_t *dip) +{ + /* Pass the door identity information to create function */ + thr_create(NULL, 0, my_server_create, (void *)dip->di_proc, + THR_BOUND | THR_DETACHED, NULL); +} + +main() +{ + (void) door_server_create(my_create); + if (thr_keycreate(&door_key, NULL) != 0) { + perror("thr_keycreate"); + exit(1); + } + mutex_lock(&lock); + d1 = door_create(foo, NULL, DOOR_PRIVATE); /* Private pool */ + d2 = door_create(bar, NULL, DOOR_PRIVATE); /* Private pool */ + cond_signal(&cv); + mutex_unlock(&lock); + while (1) + pause(); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2),\fBdoor_create\fR(3C), \fBdoor_return\fR(3C), +\fBdoor_server_create\fR(3C), \fBattributes\fR(5) |