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 comfortable 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.

Implement your protocol's generated C++ interface

Like Mozilla's IDL compiler, the IPDL compiler generates skeleton, concrete C++ implementations for the "abstract" classes it spits out. We'll add our "Hello, world!" printing code to those skeleton implementations in this step.

Open $OBJDIR/ipc/ipdl/_ipdlheaders/mozilla/test/TestProtocolChild.h and $OBJDIR/ipc/ipdl/_ipdlheaders/mozilla/test/TestProtocolParent.h. Look for the sections marked // Skeleton implementation of abstract actor class; you should see something like the following.

// ----- [in TestProtocolChild.h] -----
// Header file contents
class ActorImpl :
    public TestProtocolChild
{
    virtual nsresult RecvHello();
    ActorImpl();
    virtual ~ActorImpl();
};


// C++ file contents
nsresult ActorImpl::RecvHello()
{
    return NS_ERROR_NOT_IMPLEMENTED;
}

ActorImpl::ActorImpl()
{
}

ActorImpl::~ActorImpl()
{
}

// ----- [in TestProtocolParent.h] -----
// Header file contents
class ActorImpl :
    public TestProtocolParent
{
    virtual nsresult RecvWorld();
    ActorImpl();
    virtual ~ActorImpl();
};


// C++ file contents
nsresult ActorImpl::RecvWorld()
{
    return NS_ERROR_NOT_IMPLEMENTED;
}

ActorImpl::ActorImpl()
{
}

ActorImpl::~ActorImpl()
{
}

Looking past the odd fact that both skeletons are named "ActorImpl," note the substantial difference between the two skeletons: the ProtocolChild requires your C++ code to implement the code that acts on receiving a "Hello()" message, whereas the ProtocolParent requires your C++ code to implement the "World()" handler. IPDL generates boilerplate code to send these messages, but it has no idea what you want to do upon receiving them.

NOTE: if you don't implement these functions, libxul will not link.

Now we'll make these skeletons do something useful. Take the code marked "// Header contents" in the ProtocolChild.h header and put it in a file called ipc/test-harness/TestChild.h. Rename "ActorImpl" to "TestChild," and make the constructor and destructor public. Put it inside the mozilla::test namespace. Next, take the code marked "// C++ file contents", put it in a file called ipc/test-harness/TestChild.cpp, and s/ActorImpl/TestChild/g again. Finally, repeat for the ProtocolParent.h header, creating TestParent.h and .cpp files.

As mentioned above, the existing test-harness calls into TestParent::DoStuff when it has finished low-level initialization. Let's implement that method now.

void TestParent::DoStuff()
{
    puts("[TestParent] in DoStuff()");
    SendHello();
}

This code will print the string above to stdout, then send the "Hello()" message to the TestChild actor. When the TestChild actor receives that message, its RecvHello() method will be called. Let's next implement that. Change its skeleton definition to

nsresult TestChild::RecvHello()
{
    puts("[TestChild] Hello, ");
    SendWorld();
    return NS_OK;
}

As you might guess, this will print "Hello, " to stdout and then send the "World()" message back to the TestParent. And, you got it, this will in turn cause the parent actor's RecvWorld() handler to be invoked. Let's finally implement that.

nsresult TestParent::RecvWorld()
{
    puts("[TestParent] world!");
    return NS_OK;
}

Now we're ready to compile and run the C++ code.

Put it all together

First, compile the C++ actor implementations. This is beyond the scope of this guide; see the Mozilla build documentation.

If you put your code in the ipc/test-harness, you can run it by invoking the test-harness binary. Navigate to your dist/bin directory and run

$ ./ipctestharness

If all goes well, you should see the output

[TestParent] in DoStuff()
[TestChild] Hello, 
[TestParent] world!

fly by eventually. Remember, the first and third messages are printed by the parent process, and the second is printed by the child process.

You can enable more detailed logging by setting the MOZ_IPC_MESSAGE_LOG environment variable in DEBUG builds. For this small example, you will only see something like the following

$ MOZ_IPC_MESSAGE_LOG=1 ./ipctestharness
// [...SNIP...]
[TestParent] in DoStuff()
[time:1248148008902152][TestProtocolParent] SendHello()
[time:1248148008902898][TestProtocolChild] RecvHello()
[TestChild] Hello, 
[time:1248148008902939][TestProtocolChild] SendWorld()
[time:1248148008903080][TestProtocolParent] RecvWorld()
[TestParent] world!

Note, however, this code also logs the parameters and returned values of messages that have them (neither message in this little example do), so it can be a valuable debugging asset.

Exercise: write a slightly less trivial protocol

Try writing a system that behaves as follows.

• the parent keeps a map of String keys to String values
• the parent allows the child to:
  • synchronously map a key to a new value
  • asynchronously query the current value of a key
  • asynchronously query the values of an array of keys

After writing your own protocol, take a look at the code in ipc/test-harness that implements the IPDL part of this exercise. Depending on your interpretation of the problem statement this code may not look much like yours. But it's worth refreshing your knowledge of the language features the example code employs.

Happy piddling!