C bindings pt3: Type table definitions and barebones files to get generated code to compile.

mojo/public/c/bindings/lib/type_table.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// This file contains structs used for constructing type tables for generated
+// mojom types. A type table for a mojom struct is a table describing the
+// byte-offsets of all the pointers and handles in the struct, and has
+// references to the type tables that further describe the pointers. This table
+// is used for doing all computations for the struct -- determining serialized
+// size, encoding and decoding recursively, etc. A type table is generated for
+// each struct, union, array and map.
+//
+// The user is not expected to construct type tables -- a bindings generator
+// will do this when it generates bindings for a mojom file.
+//
+// A type table for a mojom struct and a mojom union is a |MojomTypeTable| with
+// containing an array of entries of types of |MojomTypeTableStructEntry| and
+// |MojomTypeTableUnionEntry|, respectively.
+// Since arrays only have one type, they are described by
+// |MojomTypeTableArrayEntry|, not contained inside a |MojomTypeTable|.
+
+#ifndef MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_TABLE_H_
+#define MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_TABLE_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "mojo/public/c/system/macros.h"
+
+MOJO_BEGIN_EXTERN_C
+
+// This enum is used in a type table entry for the |elem_type| field, and
+// indicates which type the accompanying |elem_table| is describing.
+enum MojomTypeTableElemType {
+  // A map is a struct with 2 arrays.
+  MOJOM_ELEMENT_TYPE_STRUCT = 0,
+  MOJOM_ELEMENT_TYPE_ARRAY = 1,
+  MOJOM_ELEMENT_TYPE_UNION = 2,
+  MOJOM_ELEMENT_TYPE_HANDLE = 3,
+  MOJOM_ELEMENT_TYPE_INTERFACE = 4,
+  // This is only used in an array table entry, and serves as a way to terminate
+  // a chain of array entries; the last entry in the chain always contains a
+  // plain-old-data type.
+  MOJOM_ELEMENT_TYPE_POD = 5,
+};
+
+// Structs and unions are described using this struct; |entries| is of type

[viettrungluu, 2016/06/21 18:08:30]

I suggest you just make two separate structs (with suitably descriptive names --
see below) with correct types.

[vardhan, 2016/06/21 22:42:58]

Done.

+// |MojomTypeTableStructEntry| for mojom structs, and |MojomTypeTableUnion|
+// for mojom unions.
+struct MojomTypeTable {
+  size_t num_entries;
+  const void* entries;
+};
+
+// This struct is used to describe each entry in a mojom struct. Each entry
+// indicates whether it is describing a reference type, or a handle type through
+// the field |elem_type|. |elem_table| points to the type table describing the
+// field, if the type has one (handles don't have type tables). |offset|
+// indicates the starting byte offset of the element within the struct.
+struct MojomTypeTableStructEntry {
+  // The type that |elem_table| points to.
+  // - If MOJOM_ELEMENT_TYPE_STRUCT, then |elem_table| points to a
+  //   |MojomTypeTable|, with its |entries| field pointing to an array of
+  //   |MojomTypeTableStructEntry|.
+  // - If MOJOM_ELEMENT_TYPE_UNION, then |elem_table| points to a
+  //   |MojomTypeTable|, with its |entries| field pointing to an array of
+  //   |MojomTypeTableUnionEntry|.
+  // - If MOJOM_ELEMENT_TYPE_ARRAY, then |elem_table| points to a
+  //   |MojomTypeTableArrayEntry|.
+  // - For any other value, |elem_table| is NULL.
+  enum MojomTypeTableElemType elem_type;
+  // |elem_table| can be |MojomTypeTable|, MojomTypeTableArrayEntry|, or NULL.

[viettrungluu, 2016/06/21 18:08:30]

I think you should rationalize the names of things. Think of it this way: if
these were C++ classes, instead of C structs, how would you name them?

You have two kinds of things:
1. Things that describe a type. (These stand alone, but sometimes may be in a
table contained in a thing of type 1.)
2. Things that do not stand alone, but only occur in something of type 1.

Let's call type 1 things "type descriptors". You split MojomTypeTable into
MojomTypeDescriptorStruct (or maybe it should be MojomStructTypeDescriptor?) and
MojomTypeDescriptorUnion. And MojomTypeTableArrayEntry should be renamed to
MojomTypeDescriptorArray.

Type 2 things are really "inner types" for things of type 1, so should be named
correspondingly.

E.g., MojomTypeTableStructEntry maybe becomes MojomTypeDescriptorStructEntry (or
something like that), and similarly for unions.

(Incidentally, what about maps?)

[vardhan, 2016/06/21 22:42:58]

Done.
Maps are mojom structs with mojom arrays -- i just added a comment at the top of
the file explaining this.

+  // Use |elem_type| to decide which it is.
+  const void* elem_table;
+  // |offset| does not account for the struct header. Offset 0 always refers to
+  // the first element.
+  uint32_t offset;
+  // Corresponds to the '[MinVersion]' attribute in mojom IDL. This determines
+  // if this field should be ignored if its min_version < version of the struct
+  // we are dealing with.
+  uint32_t min_version;
+  // Is this field nullable?
+  bool nullable;
+};
+
+// Like |MojomTypeTableStructEntry|, this variant is used to construct a type
+// table for a union. Instead of an offset, it describes a union field by the
+// |tag|.
+struct MojomTypeTableUnionEntry {
+  // The behaviour of |elem_type| and |elem_table| is the same as
+  // |MojomTypeTableStructEntry|.
+  enum MojomTypeTableElemType elem_type;
+  const void* elem_table;
+  // The tag of the union field.
+  uint32_t tag;
+  bool nullable;
+};
+
+// Describes a mojom array. To describe an array, we don't need a type table of
+// entries, since arrays can only describe 1 type. However, that one type can
+// recursively be an array (e.g, array<array<int>>), in which case a
+// chain of array entries are constructed.
+struct MojomTypeTableArrayEntry {
+  enum MojomTypeTableElemType elem_type;
+  const void* elem_table;
+  // How many elements is this array expected to hold?
+  // 0 means unspecified.
+  uint32_t num_elements;
+  bool nullable;
+};
+
+// This describes a mojom string.
+// A mojom string is a mojom array of chars without a fixed-sized.
+extern const struct MojomTypeTableArrayEntry MojomTypeTableStringEntry;

[viettrungluu, 2016/06/21 18:08:30]

It's very odd that MojomTypeTableStringEntry is not a type, but an instance of a
type.

[vardhan, 2016/06/21 22:42:58]

Renamed to MojomStringTypeDescription.

+
+MOJO_END_EXTERN_C
+
+#endif  // MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_TABLE_H_