Standard C Library Functions door_xcreate(3C)
NAME
door_xcreate - create a door descriptor for a private door
with per-door control over thread creation
SYNOPSIS
#include
typedef void door_server_procedure_t(void *, char *, size_t,
door_desc_t *, uint_t);
typedef int door_xcreate_server_func_t(door_info_t *,
void *(*)(void *), void *, void *);typedef void door_xcreate_thrsetup_func_t(void *);
int door_xcreate(door_server_procedure_t *server_proceduere,
void *cookie, uint_t attributes,
door_xcreate_server_func_t *thr_create_func,
door_xcreate_thrsetup_func_t *thr_setup_func, void *crcookie,
int nthread);DESCRIPTION
The door_xcreate() function creates a private door to the
given server_procedure, with per-door control over the crea-
tion of threads that will service invocations of that door. A private door is a door that has a private pool of threadsthat service calls to that door alone; non-private doors
share a pool of service threads (see door_create(3C)).
Creating private doors using door_create()
Prior to the introduction of door_xcreate(), a private door
was created using door_create() specifying attributes
including DOOR_PRIVATE after installing a suitable door
server thread creation function using door_server_create().
During such a call to door_create(), the first server thread
for that door is created by calling the door server func-
tion; you must therefore already have installed a customdoor server creation function using door_server_create().
The custom server creation function is called at initialcreation of a private door, and again whenever a new invoca-
tion uses the last available thread for that door. The func-
tion must decide whether it wants to increase the level ofconcurrency by creating an additional thread - if it decides
not to then further invocations may have to wait for an existing active invocation to complete before they can proceed. Additional threads may be created using whatever thread attributes are desired in the application, and the application must specify a thread start function (toSunOS 5.11 Last change: 17 Nov 2009 1
Standard C Library Functions door_xcreate(3C)
thr_create(3C) or pthread_create(3C)) which will perform a
door_bind() to the newly-created door before calling
door_return(NULL, 0, NULL, 0) to enter service. See
door_server_create(3C) and door_bind(3C) for more informa-
tion and for an example. This "legacy" private door API is adequate for many uses, but has some limitations: o The server thread creation function appointed viathe door_server_create() is shared by all doors in
the process. Private doors are distinguished fromnon-private in that the door_info_t pointer argu-
ment to the thread creation function is non-null
for private doors; from the door_info_t the associ-
ated door server procedure is available via thedi_proc member.
o If a library wishes to create a private door of which the application is essentially unaware it has no option but to inherit any function appointedwith door_server_create() which may render the
library door inoperable.o Newly-created server threads must bind to the door
they will service, but the door file descriptor toquote in door_bind() is not available in the
door_info_t structure we receive a pointer to. The
door file descriptor is returned as the result ofdoor_create(), but the initial service thread is
created during the call to door_create(). This
leads to complexity in the startup of the servicethread, and tends to force the use of global vari-
ables for the door file descriptors as per theexample in door_bind().
Creating private doors with door_xcreate()
The door_xcreate() function is purpose-designed for the
creation of private doors and simplifies their use by movingresponsibility for binding the new server thread and syn-
chronizing with it into a library-provided thread startup
function:o The first three arguments to door_xcreate() are as
you would use in door_create(): the door
server_procedure, a private cookie to pass to that
procedure whenever it is invoked for this door, anddesired door attributes. The DOOR_PRIVATE attribute
is implicit, and an additional attribute ofDOOR_NO_DEPLETION_CB is available.
SunOS 5.11 Last change: 17 Nov 2009 2
Standard C Library Functions door_xcreate(3C)
o Four additional arguments specify a server thread creation function to use for this door (must not be NULL), a thread setup function for new server threads (can be NULL), a cookie to pass to those functions, and the initial number of threads to create for this door.o The door_xcreate_server_func_t() for creating
server threads has differing semantics to those ofa door_server_func_t() used in
door_server_create(). In addition to a door_info_t
pointer it also receives as arguments a library-
provided thread start function and thread start argument that it must use, and the private cookieregistered in the call to door_xcreate(). The nom-
inated door_xcreate_server_func_t() must:
o Return 0 if no additional thread is to be created, for example if it decides the current level of concurrency is sufficient. When the server thread creation function is invoked as part of a depletion callback (as opposed toduring initial door_xcreate()) the door_info_t
di_attributes member includes
DOOR_DEPLETION_CB.
o Otherwise attempt to create exactly one newthread using thr_create() or pthread_create(),
with whatever thread attributes (stack size)are desired and quoting the implementation-
provided thread start function and opaque datacookie. If the call to thr_create() or
pthread_create() is successful then return 1,
otherwise return -1.
o Do not call door_bind() or request to enter
service via door_return(NULL, 0, NULL, 0).
As in door_server_create() new server threads must be
created PTHREAD_SCOPE_SYSTEM and PTHREAD_CREATE_DETACHED
for POSIX threads, and THR_BOUND and THR_DETACHED for
Solaris threads. The signal disposition and schedulingclass of newly-created threads are inherited from the
calling thread, initially from the thread callingdoor_xcreate() and subsequently from the current active
door server thread.o The library-provided thread start function performs
the following operations in the order presented:o Calls the door_xcreate_thrsetup_func_t() if it
is not NULL, passing the crcookie. You can use this setup function to perform custom serviceSunOS 5.11 Last change: 17 Nov 2009 3
Standard C Library Functions door_xcreate(3C)
thread configuration that must be done from the context of the new thread. Typically this is toconfigure cancellation preferences, and possi-
bly to associate application thread-specific-
data with the newly-created server thread.
If thr_setup_func() was NULL then a default is
applied which will configure the new thread withpthread_setcancelstate(PTHREAD_CANCEL_DISABLE,
NULL) andpthread_setcanceltype(PTHREAD_CANCEL_DEFERRED,
NULL). If the server code is truly interested in notifications of client aborts during a door invocation then you will need to provide athr_setup_func() that does not disable cancel-
lations, and use pthread_cleanup_push(3C)and
pthread_cleanup_pop(3C)as appropriate.
o Binds the new thread to the door file descrip-
tor using door_bind().
o Synchronizes with door_xcreate() so that the
new server thread is known to have successfullycompleted door_bind() before door_xcreate()
returns. o The number of service threads to create at initial door creation time can be controlled through thenthread argument to door_xcreate(). The nominated
door_xcreate_server_func_t() will be called nthread
times. All nthread new server threads must becreated successfully (thr_create_func() returns 1
for each) and all must succeed in binding to the new door; if fewer than nthread threads are created, or fewer than nthread succeed in binding,then door_xcreate() fails and any threads that were
created are made to exit. No artificial maximum value is imposed on the nthread argument: it may be as high as system resources and available virtual memory permit. There is a small amount of additional stack usagein the door_xcreate() stack frame for each thread -
up to 16 bytes in a 64-bit application. If there is
unsufficient room to extend the stack for this pur-
pose then door_xcreate() fails with E2BIG.
The door attributes that can be selected in thecall to door_xcreate() are the same as in
door_create(), with DOOR_PRIVATE implied and
DOOR_NO_DEPLETION_CB added:
SunOS 5.11 Last change: 17 Nov 2009 4
Standard C Library Functions door_xcreate(3C)
DOOR_PRIVATE
It is not necessary to include this attribute.The door_xcreate() interfaces only creates
private doors.DOOR_NO_DEPLETION_CB
Create the initial pool of nthread service threads, but do not perform further callbacksto the thr_create_func() for this door when the
thread pool appears to be depleted at the start of a new door invocation. This allows you to select a fixed level of concurrency.Another di_attribute is defined during thread
depletion callbacks:DOOR_DEPLETION_CB
This call to the server thread creation func-
tion is the result of a depletion callback. This attribute is not set when the function iscalled during initial door_xcreate().
The descriptor returned from door_xcreate() will be marked
as close on exec (FD_CLOEXEC). Information about a door is
available for all clients of a door using door_info(3C).
Applications concerned with security should not place secureinformation in door data that is accessible by door_info().
In particular, secure data should not be stored in the data item cookie. A process can advertise a door in the file system name space using fattach(3C).After creation, door_setparam(3C)can be used to set limits
on the amount of data and descriptors clients can send over the door.A door created with door_xcreate() may be revoked using
door_revoke(3C). This closes the associated file descriptor,
and acts as a barrier to further door invocations, but existing active invocations are not guaranteed to haveSunOS 5.11 Last change: 17 Nov 2009 5
Standard C Library Functions door_xcreate(3C)
completed before door_revoke() returns. Server threads bound
to a revoked door do not wakeup or exit automatically when the door is revoked.RETURN VALUES
Upon successful completion, door_xcreate() returns a non-
negative value. Otherwise, door_xcreate() returns -1 and
sets errno to indicate the error.ERRORS
The door_xcreate() function will fail if:
E2BIG The requested nthread is too large. A small amount of stack space is required for each thread we must start and synchronize with. If extendingthe door_xcreate() stack by the required amount
will exceed the stack bounds then E2BIG is returned.EBADF The attempt to door_bind() within the library-
provided thread start function failed. EINVAL Invalid attributes are passed, nthread is lessthan 1, or thr_create_func() is NULL. This is
also returned if thr_create_func() returns 0 (no
thread creation attempted) during door_xcreate().
EMFILE The process has too many open descriptors. ENOMEM Insufficient memory condition while creating the door.ENOTSUP A door_xcreate() call was attempted from a fork
handler.EPIPE A call to the nominated thr_create_func()
returned -1 indicating that pthread_create() or
thr_create() failed.
EXAMPLES
Example 1 Create a private door with an initial pool of 10 server threadsSunOS 5.11 Last change: 17 Nov 2009 6
Standard C Library Functions door_xcreate(3C)
Create a private door with an initial pool of 10 server threads. Threads are created with the minimum requiredattributes and there is no thread setup function. Use fat-
tach() to advertise the door in the filesystem namespace.static pthread_attr_t tattr;
/** Simplest possible door_xcreate_server_func_t. Always attempt to
* create a thread, using the previously initialized attributes for * all threads. We must use the start function and argument provided, * and make no use of our private mycookie argument. */ intthrcreatefunc(door_info_t *dip, void *(*startf)(void *),
void *startfarg, void *mycookie) {if (pthread_create(NULL, &tattr, startf, startfarg) != 0) {
perror("thrcreatefunc: pthread_create");
return (-1);
} return (1); } /** Dummy door server procedure - does no processing.
*/ voiddoor_proc(void *cookie, char *argp, size_t argsz, door_desc_t *descp,
uint_t n)
{door_return (NULL, 0, NULL, 0);
} int main(int argc, char *argv[]) { struct stat buf; int did; /** Setup thread attributes - minimum required.
*/(void) pthread_attr_init(&tattr);
(void) pthread_attr_setdetachstate(&tattr, PTHREAD_CREATE_DETACHED);
(void) pthread_attr_setscope(&tattr, PTHREAD_SCOPE_SYSTEM);
/* * Create a private door with an initial pool of 10 server threads. */SunOS 5.11 Last change: 17 Nov 2009 7
Standard C Library Functions door_xcreate(3C)
did = door_xcreate(door_proc, NULL, 0, thrcreatefunc, NULL, NULL,
10);if (did == -1) {
perror("door_xcreate");
exit(1); } if (stat(DOORPATH, &buf) < 0) { int newfd; if ((newfd = creat(DOORPATH, 0644)) < 0) { perror("creat"); exit(1); } (void) close(newfd); } (void) fdetach(DOORPATH); (void) fdetach(DOORPATH); if (fattach(did, DOORPATH) < 0) { perror("fattach"); exit(1); } (void) fprintf(stderr, "Pausing in main0); (void) pause(); } Example 2 Create a private door with exactly one server thread and no callbacks for additional threads Create a private door with exactly one server thread and no callbacks for additional threads. Use a server thread stacksize of 32K, and specify a thread setup function.#define DOORPATH "/tmp/grmdoor"
static pthread_attr_t tattr;
/** Thread setup function - configuration that must be performed from
* the conext of the new thread. The mycookie argument is the* second-to-last argument from door_xcreate.
*/ void thrsetupfunc(void *mycookie) {SunOS 5.11 Last change: 17 Nov 2009 8
Standard C Library Functions door_xcreate(3C)
/* * If a thread setup function is specified it must do the * following at minimum. */(void) pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, NULL);
/* * The default thread setup functions also performs the following * to disable thread cancellation notifications, so that server * threads are not cancelled when a client aborts a door call. * This is not a requirement. */(void) pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
/* * Now we can go on to perform other thread initialization,* for example to allocate and initialize some thread-specific data
* for this thread; for thread-specific data you can use a
destructor function in pthread_key_create if you want to perform
any actions if/when a door server thread exits. */ } /** The door_xcreate_server_func_t we will use for server thread
* creation. The mycookie argument is the second-to-last argument
* from door_xcreate.
*/ intthrcreatefunc(door_info_t *dip, void *(*startf)(void *),
void *startfarg, void *mycookie) {if (pthread_create(NULL, &tattr, startf, startfarg) != 0) {
perror("thrcreatefunc: pthread_create");
return (-1);
} return (1); } /* * Door procedure. The cookie received here is the second arg to* door_xcreate.
*/ voiddoor_proc(void *cookie, char *argp, size_t argsz, door_desc_t *descp,
uint_t n)
{(void) door_return(NULL, 0, NULL, 0);
} intSunOS 5.11 Last change: 17 Nov 2009 9
Standard C Library Functions door_xcreate(3C)
main(int argc, char *argv[]) { struct stat buf; int did; /* * Configure thread attributes we will use in thrcreatefunc.* The PTHREAD_CREATE_DETACHED and PTHREAD_SCOPE_SYSTEM are
* required. */(void) pthread_attr_init(&tattr);
(void) pthread_attr_setdetachstate(&tattr, PTHREAD_CREATE_DETACHED);
(void) pthread_attr_setscope(&tattr, PTHREAD_SCOPE_SYSTEM);
(void) pthread_attr_setstacksize(&tattr, 16 * 1024);
/* * Create a private door with just one server thread and asking for * no further callbacks on thread pool depletion during an * invocation. */did = door_xcreate(door_proc, NULL, DOOR_NO_DEPLETION_CB,
thrcreatefunc, thrsetupfunc, NULL, 1);if (did == -1) {
perror("door_xcreate");
exit(1); } if (stat(DOORPATH, &buf) < 0) { int newfd; if ((newfd = creat(DOORPATH, 0644)) < 0) { perror("creat"); exit(1); } (void) close(newfd); } (void) fdetach(DOORPATH); if (fattach(did, DOORPATH) < 0) { perror("fattach"); exit(1); } (void) fprintf(stderr, "Pausing in main0); (void) pause(); }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 17 Nov 2009 10
Standard C Library Functions door_xcreate(3C)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | all ||_____________________________|_____________________________|
| Availability | SUNWcs ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
door_bind(3C), door_call(3C), door_create(3C),
door_info(3C), door_revoke(3C), door_server_create(3C),
door_setparam(3C), fattach(3C), libdoor(3LIB),
pthread_create(3C), pthread_cleanup_pop(3C),
pthread_cleanup_push(3C), thr_create(3C), attributes(5),
cancellation(5)SunOS 5.11 Last change: 17 Nov 2009 11