Get Started: Before we Begin

Revolving Doors

Learning the illumos Doors API

illumos Doors are a novel form of inter-process communication. They allow a thread in a client process to call a function in a server process, automatically spawning a handler thread in the server process if needed.

This repository includes a set of annotated code examples of increasing complexity, each of which discusses a different aspect of the doors API. Though unusual, this API is not very big. The goal of this project is to help folks become comfortable with the doors API in two or three attempts.

Prerequisites

You should know a little C, and have an interest in systems programming. More specifically, this tutorial assumes you either understand or can teach yourself about the following:

• When a process opens a file, it gets back a "file descriptor" which is an int
• Making a "System Call" is really just asking the OS to do something for you
• C represents arrays by a pointer to the beginning of some data, and its length
• printf takes some funky arguments, and you have to look those up sometimes.

illumos

Of course, to play with doors, you will need access to illumos! I recommend installing OpenIndiana on a VM on your workstation. Or, if you are an AWS customer, you might find it easier to launch an OmniOS instance in your AWS account.

Sources

I am writing this because there seems to be so little about doors on the internet. Here is what I have been able to gather, in order of usefulness:

• Chapter 15 "Doors" of UNIX Network Programming, Volume 2, Second Edition: Interprocess Communications, Prentice Hall, 1999, ISBN 0-13-081081-9.
• DOOR_CREATE(3C)
• Section 4.8 "Solaris Doors" of Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture, Second Edition, Prentice Hall, 2006, ISBN 0-13-148209-2.
• "Doors" in SolarisTM: Lightweight RPC using File Descriptors
• Slides 28-36 of "OpenSolaris Overview lecture" by Rami Rosen
• Linux Doors
• An Implementation of the Solaris Doors API for Linux by Jason Lango

Special Thanks

• @jack-morrison and @AnthonyDiGirolamo for encouraging me to get the OpenIndiana setup guide together
• Nicole Deasy for suggesting explicit forward/backward navigation over github's built-in nav
• @jasonbking for this excellent feedback
• The excellent Mermaid library which was used to create the diagrams in each lesson
• Social Media icon due to Daniel Lobo, licensed (CC BY-SA 2.0). Retrieved at the time of this commit.