door_bind(3DOOR)					      Door Library Functions						  door_bind(3DOOR)

NAME

       door_bind, door_unbind - bind or unbind the current thread with the door server pool

SYNOPSIS

       cc -mt [ flag... ] file... -ldoor  [ library... ]
       #include <door.h>

       int door_bind(int did);

       int door_unbind(void);

DESCRIPTION

       The door_bind() 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 did.

       The door_unbind() function breaks the association of door_bind() by removing any private door pool binding that is associated with the cur-
       rent thread.

       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 DOOR_PRIVATE only uses server threads that have been associated with the door by door_bind().
       It is therefore necessary to bind at least one server thread  to doors created with DOOR_PRIVATE.

       The  server  thread  create  function,  door_server_create(),  is  initially  called  by  the system during a  door_create() operation. See
       door_server_create(3DOOR) and  door_create(3DOOR).

       The current thread is added to the private pool of server  threads associated with a door during the  next  door_return()  (that  has  been
       issued by the current thread after an associated  door_bind()). See door_return(3DOOR). A server thread performing a  door_bind() on a door
       that is already bound to a different door performs an implicit door_unbind() of the previous door.

       If a process containing threads that have been bound to a door calls fork(2), the threads in the child process will be bound to an  invalid
       door, and any calls to door_return(3DOOR) will result in an error.

RETURN VALUES

       Upon successful completion, a 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

       The  door_bind() and  door_unbind() functions fail if:

       EBADF	       The did argument is not a valid door.

       EBADF	       The door_unbind() function was called by a thread that is currently not bound.

       EINVAL	       did was not created with the DOOR_PRIVATE attribute.

EXAMPLES

       Example 1: Use door_bind() to create private server pools for two doors.

       The  following  example	shows  the  use  of door_bind() to create private server pools for two doors,  d1 and d2. Function  my_create() is
       called when a new server thread is needed; it creates a thread running function, my_server_create(), which binds itself to one of  the  two
       doors.

       #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();
       }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Architecture		     |all			   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       fork(2),door_create(3DOOR), door_return(3DOOR), door_server_create(3DOOR), libdoor(3LIB), attributes(5)

SunOS 5.10							    23 Apr 2003 						  door_bind(3DOOR)