Tribblix: manual page: door_server

DOOR_SERVER_CREATE(3C) Standard C Library Functions DOOR_SERVER_CREATE(3C)

NAME

door_server_create - specify an alternative door server thread
creation function

SYNOPSIS

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

void (*)(door_info_t *) door_server_create(void (*create_proc)(door_info_t *));

DESCRIPTION

Normally, the doors library creates new door server threads in
response to incoming concurrent door invocations automatically. There
is no pre-defined upper limit on the number of server threads that
the system creates in response to incoming invocations (1 server
thread for each active door invocation). These threads are created
with the default thread stack size and POSIX (see standards(7))
threads cancellation disabled. The created threads also have the
THR_BOUND | THR_DETACHED attributes for Solaris threads and the
PTHREAD_SCOPE_SYSTEM | PTHREAD_CREATE_DETACHED attributes for POSIX
threads. The signal disposition, and scheduling class of the newly
created thread are inherited from the calling thread (initially from
the thread calling door_create(), and subsequently from the current
active door server thread).

The door_server_create() function allows control over the creation of
server threads needed for door invocations. The procedure create_proc
is called every time the available server thread pool is depleted. In
the case of private server pools associated with a door (see the
DOOR_PRIVATE attribute in door_create()), information on which pool
is depleted is passed to the create function in the form of a
door_info_t structure. The di_proc and di_data members of the
door_info_t structure can be used as a door identifier associated
with the depleted pool. The create_proc procedure may limit the
number of server threads created and may also create server threads
with appropriate attributes (stack size, thread-specific data, POSIX
thread cancellation, signal mask, scheduling attributes, and so
forth) for use with door invocations.

The overall amount of data and argument descriptors that can be sent
through a door is limited by both the server thread's stack size and
by the parameters of the door itself. See door_setparam(3C).

The specified server creation function should create user level
threads using thr_create() with the THR_BOUND flag, or in the case of
POSIX threads, pthread_create() with the PTHREAD_SCOPE_SYSTEM
attribute. The server threads make themselves available for incoming
door invocations on this process by issuing a door_return(NULL, 0,
NULL, 0). In this case, the door_return() arguments are ignored. See
door_return(3C) and thr_create(3C).

The server threads created by default are enabled for POSIX thread
cancellations which may lead to unexpected thread terminations while
holding resources (such as locks) if the client aborts the associated
door_call(). See door_call(3C). Unless the server code is truly
interested in notifications of client aborts during a door invocation
and is prepared to handle such notifications using cancellation
handlers, POSIX thread cancellation should be disabled for server
threads using pthread_setcancelstate (PTHREAD_CANCEL_DISABLE, NULL).
If all doors are created with the DOOR_NO_CANCEL flag (see
door_create(3C)), the threads will never be cancelled by an aborted
door_call() call

The create_proc procedure need not create any additional server
threads if there is at least one server thread currently active in
the process (perhaps handling another door invocation) or it may
create as many as seen fit each time it is called. If there are no
available server threads during an incoming door invocation, the
associated door_call() blocks until a server thread becomes
available. The create_proc procedure must be MT-Safe.

RETURN VALUES

Upon successful completion, door_server_create() returns a pointer to
the previous server creation function. This function has no failure
mode (it cannot fail).

EXAMPLES

Example 1: Creating door server threads.

The following example creates door server threads with cancellation
disabled and an 8k stack instead of the default stack size:

#include <door.h>
#include <pthread.h>
#include <thread.h>

void *
my_thread(void *arg)
{
pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
door_return(NULL, 0, NULL, 0);
}
void
my_create(door_info_t *dip)
{
thr_create(NULL, 8192, my_thread, NULL,
THR_BOUND | THR_DETACHED, NULL);
}
main()
{
(void)door_server_create(my_create);
...
}

ATTRIBUTES