1door_server_create(3C) Standard C Library Functions door_server_create(3C)
2
3
4
6 door_server_create - specify an alternative door server thread creation
7 function
8
10 cc -mt [ flag... ] file... [ library... ]
11 #include <door.h>
12
13 void (*) () door_server_create(void (*create_proc)(door_info_t*));
14
15
17 Normally, the doors library creates new door server threads in
18 response to incoming concurrent door invocations automatically. There
19 is no pre-defined upper limit on the number of server threads that the
20 system creates in response to incoming invocations (1 server thread
21 for each active door invocation). These threads are created with the
22 default thread stack size and POSIX (see standards(5)) threads cancel‐
23 lation disabled. The created threads also have the THR_BOUND |
24 THR_DETACHED attributes for Solaris threads and the
25 PTHREAD_SCOPE_SYSTEM | PTHREAD_CREATE_DETACHED attributes for POSIX
26 threads. The signal disposition, and scheduling class of the newly
27 created thread are inherited from the calling thread (initially from
28 the thread calling door_create(), and subsequently from the current
29 active door server thread).
30
31
32 The door_server_create() function allows control over the creation of
33 server threads needed for door invocations. The procedure create_proc
34 is called every time the available server thread pool is depleted. In
35 the case of private server pools associated with a door (see the
36 DOOR_PRIVATE attribute in door_create()), information on which pool is
37 depleted is passed to the create function in the form of a door_info_t
38 structure. The di_proc and di_data members of the door_info_t structure
39 can be used as a door identifier associated with the depleted pool.
40 The create_proc procedure may limit the number of server threads cre‐
41 ated and may also create server threads with appropriate attributes
42 (stack size, thread-specific data, POSIX thread cancellation, signal
43 mask, scheduling attributes, and so forth) for use with door invoca‐
44 tions.
45
46
47 The overall amount of data and argument descriptors that can be sent
48 through a door is limited by both the server thread's stack size and by
49 the parameters of the door itself. See door_setparam(3C).
50
51
52 The specified server creation function should create user level threads
53 using thr_create() with the THR_BOUND flag, or in the case of POSIX
54 threads, pthread_create() with the PTHREAD_SCOPE_SYSTEM attribute. The
55 server threads make themselves available for incoming door invocations
56 on this process by issuing a door_return(NULL, 0, NULL, 0). In this
57 case, the door_return() arguments are ignored. See door_return(3C) and
58 thr_create(3C).
59
60
61 The server threads created by default are enabled for POSIX thread
62 cancellations which may lead to unexpected thread terminations while
63 holding resources (such as locks) if the client aborts the associated
64 door_call(). See door_call(3C). Unless the server code is truly inter‐
65 ested in notifications of client aborts during a door invocation and
66 is prepared to handle such notifications using cancellation handlers,
67 POSIX thread cancellation should be disabled for server threads using
68 pthread_setcancelstate (PTHREAD_CANCEL_DISABLE, NULL). If all doors are
69 created with the DOOR_NO_CANCEL flag (see door_create(3C)), the threads
70 will never be cancelled by an aborted door_call() call
71
72
73 The create_proc procedure need not create any additional server threads
74 if there is at least one server thread currently active in the process
75 (perhaps handling another door invocation) or it may create as many as
76 seen fit each time it is called. If there are no available server
77 threads during an incoming door invocation, the associated door_call()
78 blocks until a server thread becomes available. The create_proc proce‐
79 dure must be MT-Safe.
80
82 Upon successful completion, door_server_create() returns a pointer to
83 the previous server creation function. This function has no failure
84 mode (it cannot fail).
85
87 Example 1 Creating door server threads.
88
89
90 The following example creates door server threads with cancellation
91 disabled and an 8k stack instead of the default stack size:
92
93
94 #include <door.h>
95 #include <pthread.h>
96 #include <thread.h>
97
98 void *
99 my_thread(void *arg)
100 {
101 pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
102 door_return(NULL, 0, NULL, 0);
103 }
104 void
105 my_create(door_info_t *dip)
106 {
107 thr_create(NULL, 8192, my_thread, NULL,
108 THR_BOUND | THR_DETACHED, NULL);
109 }
110 main()
111 {
112 (void)door_server_create(my_create);
113 ...
114 }
115
116
118 See attributes(5) for descriptions of the following attributes:
119
120
121
122
123 ┌─────────────────────────────┬─────────────────────────────┐
124 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
125 ├─────────────────────────────┼─────────────────────────────┤
126 │Architecture │all │
127 ├─────────────────────────────┼─────────────────────────────┤
128 │Availability │SUNWcsu │
129 ├─────────────────────────────┼─────────────────────────────┤
130 │Interface Stability │Stable │
131 ├─────────────────────────────┼─────────────────────────────┤
132 │MT-Level │Safe │
133 └─────────────────────────────┴─────────────────────────────┘
134
136 door_bind(3C), door_call(3C), door_create(3C), door_return(3C),
137 pthread_create(3C), pthread_setcancelstate(3C), thr_create(3C),
138 attributes(5), cancellation(5), standards(5)
139
140
141
142SunOS 5.11 22 Mar 2005 door_server_create(3C)