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 where all
+// the pointers and handles are, and references to the type tables that further

[viettrungluu, 2016/06/17 20:37:19]

- where all the pointers and handles are in what?
- ... and *has* references ...?

[vardhan, 2016/06/21 16:07:36]

Done.

+// 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 is an array of entries of type

[viettrungluu, 2016/06/17 20:37:19]

So, if I understand you correctly, the |const void* elem_table|s either point to
an array of structs (in the struct and union cases) or a single struct (in the
array case)?

Would it be clearer instead to always point to a struct, which (in the struct
and union cases) could then point to an array? (That way, you'd also have a
place to put the number of elements in the array, instead of using
|keep_going|.)

[vardhan, 2016/06/21 16:07:36]

Yes.
Hm.. the trade-off being making the generator generate more structs (i.e.
generating an extra struct that only encodes a pointer to the array and array
size). i'm not sure that will be all that much easier to understand than the
|keep_going| scheme, but I understand the weirdness in encoding it in a
run-length fashion, so Done.

+// |MojomPointerTableStructEntry|.
+// Arrays are described using |MojomPointerTableArrayEntry|, and they are not
+// tables -- an array entry simply describes 1 entry, the array's type.
+// Unions are described using |MojomPointerTableUnionEntry|. They do not contain
+// offsets, but instead contain the tag the field is meant to describe.
+
+#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 MojomPointerTableElemType {
+  // 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.
+  MOJOM_ELEMENT_TYPE_POD = 5,
+};
+
+// The size of the type table is not directly encoded into any of the entries.
+// Instead, each entry has a |keep_going| field which indicates that there is a
+// following entry. Each entry indicates whether it is describing a reference
+// type, or a handle type through the field |elem_type| (which is an enum of
+// |MojomPointerTableElemType|). |offset| indicates the (within the struct)
+// starting byte offset of the element. |elem_table| points to the type table
+// describing the field, if the type has one (handles don't have type tables).
+struct MojomPointerTableStructEntry {
+  // |elem_table| can be |MojomPointerTableStructEntry|,
+  // |MojomPointerTableUnionEntry|, |MojomPointerTableArrayEntry|, or NULL.
+  // 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;
+  // The type that |elem_table| points to.
+  enum MojomPointerTableElemType elem_type;

[viettrungluu, 2016/06/17 20:37:19]

As a matter of readability, this should be immediately next to (probably
preceding) |elem_table|.

[vardhan, 2016/06/21 16:07:36]

Done.

+  // Is this field nullable?
+  bool nullable;
+  // Are there more entries after this? (the last |MojomPointerTableStructEntry|

[viettrungluu, 2016/06/17 20:37:19]

At the very least, you're missing a closing ')'....

But also, maybe you should call this "is_last" (or "is_last_entry", or
"last_entry") instead of "keep_going"?

[vardhan, 2016/06/21 16:07:36]

(removed all-together)

+  bool keep_going;
+};
+
+// Like |MojomPointerTableStructEntry|, 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 MojomPointerTableUnionEntry {
+  const void* elem_table;
+  // The tag of the union field.
+  uint32_t tag;
+  enum MojomPointerTableElemType elem_type;
+  bool nullable;
+  bool keep_going;
+};
+
+// Describes an array. To describe an array, we don't need a type table, arrays
+// can only describe 1 type. However, that one type can recursively be an array
+// (e.g, array<array<array<int>>>), so an array entry, if it contains another
+// array.
+struct MojomPointerTableArrayEntry {
+  const void* elem_table;
+  // How many elements is this array expected to hold?
+  // 0 means unspecified.
+  uint32_t num_elements;
+  enum MojomPointerTableElemType elem_type;
+  bool nullable;
+};
+
+// This describes a mojom string.
+// A mojom string is a mojom array of chars without a fixed-sized.
+extern const struct MojomPointerTableArrayEntry MojomStringPointerEntry;
+
+MOJO_END_EXTERN_C
+
+#endif  // MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_TABLE_H_