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

[viettrungluu, 2016/06/21 23:06:52]

Maybe you should call them "type descriptors" instead of "type tables"?

Also, maybe you should rename the file? (Sorry.)

[vardhan, 2016/06/22 15:18:48]

Done.

+// 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 description is generated
+// for each struct, union, array and map. Note that mojom maps are just mojom
+// structs with two mojom arrays, so there is no separate descriptor for it.
+//
+// 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 a |MojomTypeDescriptorStruct| containing
+// an array of entries of types of |MojomTypeDescriptorStructEntry|. Similarly,
+// unions are described with |MojomTypeDescriptorUnion| with entries of
+// |MojomTypeDescriptorUnionEntry|. Arrays are described with
+// |MojomTypeDescriptorArray|.
+
+#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 MojomTypeDescriptorType {
+  // A map is a struct with 2 arrays.

[viettrungluu, 2016/06/21 23:06:52]

Probably you should prepend "Note: " to this.

Also, maybe you should indicate here the corresponding MojomTypeDescriptorX
types here (possibly "N/A" for handle/interface/POD).

[vardhan, 2016/06/22 15:18:48]

Done.

+  MOJOM_TYPE_DESCRIPTOR_TYPE_STRUCT = 0,
+  MOJOM_TYPE_DESCRIPTOR_TYPE_ARRAY = 1,
+  MOJOM_TYPE_DESCRIPTOR_TYPE_UNION = 2,
+  MOJOM_TYPE_DESCRIPTOR_TYPE_HANDLE = 3,
+  MOJOM_TYPE_DESCRIPTOR_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_TYPE_DESCRIPTOR_TYPE_POD = 5,
+};
+
+// 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 descriptor describing
+// the field, if the type has one (handles don't have type descriptors).
+// |offset| indicates the starting byte offset of the element within the struct.
+struct MojomTypeDescriptorStructEntry {
+  // The type that |elem_table| points to.

[viettrungluu, 2016/06/21 23:06:52]

(And then here you could just refer to the comment above.)

[vardhan, 2016/06/22 15:18:48]

Done.

+  // - If MOJOM_TYPE_DESCRIPTOR_TYPE_STRUCT, then |elem_table| points to a
+  //   |MojomTypeDescriptorStruct|.
+  // - If MOJOM_TYPE_DESCRIPTOR_TYPE_UNION, then |elem_table| points to a
+  //   |MojomTypeDescriptorUnion|.
+  // - If MOJOM_TYPE_DESCRIPTOR_TYPE_ARRAY, then |elem_table| points to a
+  //   |MojomTypeDescriptorArray|.
+  // - For any other value, |elem_table| is NULL.
+  enum MojomTypeDescriptorType elem_type;
+  // Use |elem_type| to decide which type |elem_table| should be casted to.
+  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;
+};
+
+// Mojom structs are described using this struct.
+struct MojomTypeDescriptorStruct {

[viettrungluu, 2016/06/21 23:06:53]

Note that since this is C, you can actually put this declaration before that of
|struct MojomTypeDescriptorStructEntry|, which is kind of nice.

[vardhan, 2016/06/22 15:18:48]

cool, done.

+  size_t num_entries;
+  // |entries| is an array of |num_entries|, each describing a field of
+  // reference or handle type.
+  const struct MojomTypeDescriptorStructEntry* entries;
+};
+
+// Like |MojomTypeDescriptorStructEntry|, this variant is used to construct a
+// type table for a union. Instead of an offset, it describes a union field by
+// its |tag|.
+struct MojomTypeDescriptorUnionEntry {
+  // The behaviour of |elem_type| and |elem_table| is the same as
+  // |MojomTypeDescriptorStructEntry|.
+  enum MojomTypeDescriptorType elem_type;
+  const void* elem_table;
+  // The tag of the union field.
+  uint32_t tag;
+  bool nullable;
+};
+
+// Mojom unions are described using this struct.
+struct MojomTypeDescriptorUnion {
+  size_t num_entries;
+  const struct MojomTypeDescriptorUnionEntry* entries;
+};
+
+// 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 MojomTypeDescriptorArray {
+  enum MojomTypeDescriptorType 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 MojomTypeDescriptorArray MojomStringTypeDescription;

[viettrungluu, 2016/06/21 23:06:53]

I was wonder, w.r.t. the name, whether it shouldn't be
g_mojom_string_type_description, or something like that.

Or maybe make it obvious that it's the MojomTypeDescriptorArray for strings in
some other way? (I can't tell offhand how you're naming generated structs, but
maybe you should follow a similar pattern?)

[vardhan, 2016/06/22 15:18:48]

Done.
 
array type descriptor names are generated from a counter
(mymodule_mystruct_myarray_0, mymodule_mystruct_myarray_1, etc.), which we don't
need for MojomStrings

(i realized shortly after i'd written the naming part that we could generate
array type descriptor names by name-mangling them without a counter, which would
let us reuse common types ("array_int" for array<int>, "map_int_array_int"
"map<int,array<int>>" that we only generate once within a mojom file.  i left
that as a TODO).

+
+MOJO_END_EXTERN_C
+
+#endif  // MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_TABLE_H_