IPDL/Five minute example

This page walks you through the steps of creating an IPDL protocol and writing the C++ code that implements the required interfaces. It is intended to be a practical complement to the more abstract IPDL/Getting started guide.

Broadly understand IPDL's C++ environment

IPDL "describes" the communication of two threads, whether in the same process or not. For two threads to communicate using IPDL, at least two things are required

1. two threads
2. an OS-level communication mechanism (transport layer)

Ramping these up in C++ is a rather complicated process, and is likely to be uncommon. If you really do need this, see the guide IPDL/Low level setup. This "five minute example" will assume that you can glom onto an existing IPDL environment.

Not coincidentally, we provide a bare-bones IPDL environment in the directory ipc/test-harness. This guide will assume that you're using this environment. The test-harness environment is set up for "inter-process communication" --- the parent and child actors' threads live in different address spaces. It contains the following classes

• TestProcessParent: represents the "child" from inside the "parent" process. Akin to nsIProcess. TestProcessParent also holds the raw socket fd over which IPDL messages are sent.
• TestThreadChild: the "main thread" of the child process. Holds the other end of the raw socket over which IPDL messages are sent.
• TestParent: the "parent actor" --- concrete C++ implementation of the IPDL parent actor abstract class.
• TestChild: the "child actor" --- concrete C++ implementation of the IPDL child actor abstract class. Its code executes on the TestThreadChild thread in the subprocess.

All the necessary code to create the subprocess, set up the communication socket, etc. is already implemented for you. After all the setup code is run, whatever code you write will be invoked through the method ParentActor::DoStuff. You can think of this as the test-harness's main() function.

Write the IPDL "Hello, world" protocol

(No, this isn't the traditional "Hello, world" example. IPDL lacks facilities for printing. I'm taking some poetic license.)

You should be familiar with the following IPDL specification. If not, you should re-read the IPDL/Getting started guide. Copy the code into ipc/test-harness/Test.ipdl.

namespace mozilla {
namespace test {

protocol Test
{
child:
    Hello();

parent:
    World();
};

} // namespace test
} // namespace mozilla

We will use this specification to make a C++ program in which the parent sends the child the Hello() message, and the child prints "Hello, " to stdout. The child will then send the parent the World() message, and the parent will print "world!" to stdout.

Run the IPDL compiler

The IPDL compiler is a python script wrapped around an IPDL module. It can be invoked in two different ways: directly, by calling the IPDL script; and indirectly, through the Mozilla build system.

To invoke it directly, use a command such as

$ python $ELECTROLYSIS/ipc/ipdl/ipdl.py -d /tmp Test.ipdl

This will run the compiler on "Test.ipdl" and spit out the generated headers into /tmp. (Try python ipdl.py --help for a list of all options.)

The second, recommended way is to use the build system. Assuming your working directory is set up correctly (ipc/test-harness is), you only need to add your new protocol specification file to the ipdl.mk file in your working directory, then invoke

$ make -C $OBJDIR/ipc/ipdl

(If your working directory is not set up correctly, see IPDL/Low level setup for guidance.)

After invoking IPDL on the file Test.ipdl, you should see three new headers generated (or updated) in the output directory (-d DIR when invoked directory, $OBJDIR/ipc/ipdl/_ipdlheaders when invoked through the build system). The headers are output in directories corresponding to the namespace(s) the protocol was defined within. So invoking the IPDL compiler on the Test protocol above, through the build system, will result in these files being (re)generated: $OBJDIR/ipc/ipdl/_ipdlheaders/mozilla/test/TestProtocol.h, $OBJDIR/ipc/ipdl/_ipdlheaders/mozilla/test/TestProtocolParent.h, $OBJDIR/ipc/ipdl/_ipdlheaders/mozilla/test/TestProtocolChild.h. Don't worry, the build system also sets up the C++ compiler's include path appropriately.