Introduction to the Solaris Doors API

The Solaris Doors API is essentially an RPC mechanism, which makes use of the UNIX notion of the filesystem as a universal name space and has built in support for multithreading. The fundamental building block of this RPC mechanism is the door. Abstractly, the door can be thought of as a service procedure or object, upon which a thread can invoke a method (or function call). The door is often referred to in the literature [6, 7] as “describing” a particular procedure in a remote server.

Doors are made visible to the applications programmer as standard UNIX file descriptors (or “door descriptors”). To make a door visible to other applications, a process may attach an existing door descriptor to an existing regular file in the UNIX file system, using a standard SVR4 mechanism for associating STREAMS file descriptors with files in the file system.

What follows is a list of the relevant library routines encompassing the Solaris Doors API, and the two related routines fattach(3) and fdetach(3). Most detail is omitted, since it is covered at length in the Solaris documentation [7], but there should be enough to provide a general overview of the supported functionality.

• door create(3) is used to create a new door. The function takes as its arguments a

server procedure, data cookie, and flags. The data cookie is a value passed to the

server procedure every time this door is the target of a door call(3) method invocation.

The result of the function call is a door descriptor, which can subsequently be used

for door call(3) invocations, attached to a file with fattach(3), or passed directly to

other processes (again via door call(3)). The process which calls door create(3) is the

same process which handles door call(3) invocations. Any running process can be a

door server, simply by calling door create(3).

• door call(3) is used to invoke a procedure call in the remote server process which

created the door using door create(3). The function takes as its arguments a door

descriptor, representing the procedure to call in the server, a memory block (contain-

ing the arguments for the procedure call), and a set of door descriptors which are to

be passed to the server process. The door descriptor is the only required argument,

the memory block and set of doors are each independently optional. The result of

the function call is either an error code, or another memory block and set of door

descriptors from the server process (again, both are optional, at the server’s discre-

tion). The client process may provide a memory buffer in which the results (if any)

from the server will be placed. If the client-provided result buffer is too small to hold

the results from the server, the operating system will allocate a new memory block

large enough to hold the results of the call.

• door return(3) is used within a server procedure to return values to the client process.

It is only valid to call door return(3) within a server procedure called by a door call(3)

invocation. The arguments that this function takes are a memory block and set of

doors to be returned to the client process (as the results of door call(3)). Both

arguments are optional.

• fattach(3) is used to attach a door descriptor to a regular file in the UNIX file system.

The function takes as arguments the door descriptor and a pathname to the regular

file.

• fdetach(3) is used to detach a door descriptor from a regular file (attached via fat-

tach(3)). The function takes the pathname to the file as its argument.

• door revoke(3) is used to revoke access to a door. All future door call(3) invocations

through any door descriptor referring to this door will fail.

• door info(3) is used to get information about a door. This function returns the process

id of the server which handles door call(3) invocations, the server procedure (address

in the server process), the data cookie for this door, a system-wide unique identifier

for the door, and certain other attributes, such as whether the current process is the

server for the door, whether the door has been revoked, etc.

• door cred(3) can be used within a server procedure to get the credentials of the client

process giving the current door call(3) invocation. This function returns the user id,

group id, and process id of the calling thread’s client.

• door server create(3) is used to register a function which will be called in the server

process whenever the kernel thinks that a new thread should be created. This allows

the programmer the ability to control how many threads are actually created in the

server and the initial parameters of the server threads (e.g. scheduling parameters,

signal dispositions, etc.).

• door bind(3) is used to bind the calling thread to a particular door. The calling thread

will be one of a set of threads which will specifically handle invocations on this door.

The door must have been created will the “private” attribute (via door create(3))

indicating that it has a private pool of server threads.

• door unbind(3) is used to remove the calling thread from a particular door’s private

server pool.

The Doors API was engineered with certain performance optimizations in mind. Server

threads will be created in the calling process in proportion to the load on the server (at

most one per concurrent request) [6]. The server may control how many threads are created

via door server create(3). Since the programmer doesn’t necessarily provide the memory

block to receive arguments to and from door call(3), the kernel may optimize the transfer

of large arguments by mapping the underlying pages of memory into the target process and

copying a page only if a process attempts to modify it. The kernel may also use handoff

scheduling to optimize door call(3) invocations [6].