IPDL/Getting started: Difference between revisions

The above specification will generate three headers: PluginProtocolParent.h, PluginProtocolChild.h, and PluginProtocol.h (we'll ignore the third completely; it's full of uninteresting implementation details). As you might guess, PluginProtocolParent.h defines a C++ class (PluginProtocolParent) that code on the parent side utilizes, the browser in this example.  And similarly, code running in the plugin process will use the PluginProtocolChild class.

These Parent and Child classes are abstract.  They will contain a "Send" function implementation for each message type in the protocol (which inheriting classes can call to initiate communication), and a pure virtual "Recv" function for the message receiver (which needs to be implemented by the inheriting class).  For example, the PluginProtocolParent class will look something like the following in C++

   '''class''' PluginProtocolParent {

and the PluginProtocolChild will be something like:

   '''class''' PluginProtocolChild {

These Parent and Child abstract classes take care of all the "protocol layer" concerns; sending messages, checking protocol safety (we'll discuss that later), and so forth.  However, these abstract classes can do nothing but send and receive messages; they don't actually ''do'' anything, like draw to the screen or write to files.  It's up to ''implementing'' C++ code to actually do interesting things with the messages.

So these abstract Parent and Child classes are meant to be subclassed by C++ ''implementors''.  Below is a dirt simple example of how a browser implementor might utilize the PluginProtocolParent

   '''class''' PluginParent : '''public''' PluginProtocolParent {

This is a boring class.  It simply launches the plugin child process.  Note that since PluginParent inherits from PluginProtocolParent, the browser code can invoke the <code>SendInit()</code> and <code>SendDeinit()</code> methods on PluginParent objects.  We'll show an example of this below.

Here's how the PluginProtocolChild might be used by a C++ implementor in the plugin process:

   '''class''' PluginChild : '''public''' PluginProtocolChild {

       // implement the PluginProtocolChild "interface"

Let's run through an example of how this dirt simple protocol and its implementation could be used.  In the table below, the first column shows C++ statements executing in the browser process, and the second shows C++ statements executing in the plugin process.

  | PluginProtocolParent.h: (construct Init() message, send it)

  | PluginProtocolChild.h: (unpack Init() message, call RecvInit();)

  // ----- DirectionProtocolParent.h -----

  '''class''' DirectionProtocolParent {

  // ----- DirectionProtocolChild.h -----

  '''class''' DirectionProtocolChild {

Message declarations allow any number of ''parameters'', which are data serialized by the sender and deserialized by the receiver.  The following snippet of IPDL and generated code shows how parameters can be used in message declarations.

   // class BlahProtocolParent { ...

   // class BlahProtocolChild { ...

IPDL has two categories of built-in types.  The first is C++ types that IPDL "imports" (described in more detail below) automatically, on behalf of the IPDL author.  These builtin types include the C/C++ integer types (bool, char, int, ..., int8_t, uint16_t, ...) and string types (<code>nsString</code>, <code>nsCString</code>).  IPDL does this because these types are common, and library code already exists to serialize and deserialize parameters of those types.  These builtin types are in flux and will certainly change.  See <code>ipc/ipdl/ipdl/builtins.py</code> for the most up-to-date reference.

The second category of built-ins are types that are native to IPDL.  These are IPDL unions and arrays and are described below.  These native IPDL types translate into C++ types.

The builtin types are insufficient for all protocols.  When you need to send data of type other than one built into IPDL, you can add a <code>'''using'''</code> declaration of the type in an IPDL specification, and in C++ define your own data serializer and deserializer.  The details of this are beyond the scope of this document; see <code>dom/plugins/PPluginInstance.ipdl</code> and <code>dom/plugins/PluginMessageUtils.h</code> for examples of how this is done.

In the Plugin protocol example above, we saw the parent actor send the Init() message to the child actor.  Under the covers, "sending the Init() message" encompasses code on the parent side creating some Init()-like message object in C++, serializing that message object into a sequence of bytes, and then sending those bytes over a socket to the child actor.  (All this is hidden from the C++ implementor, PluginParent above.  You don't have to worry about this except to better understand message semantics.)  What happens in the parent-side code once it has written those bytes to the socket's file descriptor?  It is this behavior that we broadly call ''message semantics''.

In IPDL, the parent-side code has three options for what happens after those serialized bytes are written to the socket:

'''Detour''': the above protocol will fail the IPDL type checker.  Why?  IPDL protocols also have "semantics specifiers", just like messages.  A protocol must be declared to have semantics at least as "strong" as its strongest message semantics.  Synchronous semantics is called "stronger than" asynchronous.  Like message declarations, the default protocol semantics is asynchronous; however, since the Plugin protocol declares a synchronous message, this type rule is violated.  The fixed up Plugin protocol is shown below.

This new '''sync''' message with '''returns''' values changes the generated PluginProtocolParent and PluginProtocolChild headers as follows

  // class PluginProtocolParent { ...

  // class PluginProtocolChild { ...

'''Important''': To reiterate, after the parent code calls SendInit(), it will block the parent actor's thread until the response to this message is received from the child actor.  On the child side, the int returned by child implementor from RecvInit() is packed into the response to Init(), then this response is sent back to the parent.  Once the parent reads the bytes of response message from its socket, it deserializes the int return value and unblocks the parent actor's thread, returning that deserialized int to the caller of SendInit().  It is very important to grok this sequence of events.

C++ does not have syntax that allows returning multiple values from functions/methods.  Additionally, IPDL needs to allow implementor code to signal error conditions, and IPDL itself needs to notify implementors of errors.  To those ends, IPDL generates interface methods with nsresult return types and "outparams" for the IPDL '''returns''' values.  So in reality, the C++ interface generated for the Blah example above would be

  // class BlahProtocolParent { ...

  // class BlahProtocolChild { ...

  // class PluginProtocolParent { ...

  // class PluginProtocolChild { ...