Introduce RawVarData and associated classes for serializing PP_Vars

ppapi/proxy/raw_var_data.h

+// Copyright (c) 2013 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.
+
+#ifndef PPAPI_PROXY_RAW_VAR_DATA_H_
+#define PPAPI_PROXY_RAW_VAR_DATA_H_
+
+#include <vector>
+
+#include "base/callback.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/memory/scoped_vector.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_var.h"
+#include "ppapi/proxy/ppapi_param_traits.h"
+#include "ppapi/proxy/serialized_handle.h"
+#include "ppapi/shared_impl/var_graph.h"
+
+class PickleIterator;
+
+namespace IPC {
+class Message;
+}
+
+namespace ppapi {
+namespace proxy {
+
+class RawVarData;
+
+typedef base::Callback<void(IPC::Message*, const SerializedHandle&)>
+    HandleWriter;
+
+// Contains the data associated with a graph of connected PP_Vars. Useful for
+// serializing/deserializing a graph of PP_Vars. First we compute the transitive
+// closure of the given PP_Var to find all PP_Vars which are referenced by that
+// var. Only PP_Vars which are valid vars in the VarTracker are included (other
+// vars are leaves in the graph, see below for how they are handled). A
+// RawVarData object is created for each of these vars. We then write data
+// contained in each RawVarData to the message. The format looks like this:
+//    idx | size     | (number of vars in the graph)
+//     0  | var type |
+//        | var data |
+//     1  | var type |
+//        | var data |
+//     2  | var type |
+//        | var data |
+//        |   ....   |
+//
+// Vars that reference other vars (such as arrays and dictionaries) are written
+// specially. We know that a PP_Var contained in another PP_Var must either
+// be a reference to a var in the transitive closure (or a null reference) or be
+// a primitive value. If it is a primitive value, we write it out in the same
+// format as above (type followed by data). If it is a reference, we write the
+// index in the array written above to denote the reference:
+//        | var type  |  (the type of the var pointed to)
+//        | valid ref |  (boolean: whether it is a null reference)
+//        | index     |  (index into the array of vars written to the msg)
+class RawVarDataGraph {
+ public:
+  // Constructs an empty RawVarDataGraph.
+  RawVarDataGraph();
+  // Construct a RawVarDataGraph from a given root PP_Var.
+  RawVarDataGraph(const PP_Var& var, PP_Instance instance);
+  virtual ~RawVarDataGraph();

[dmichael (off chromium), 2013/04/12 22:40:38]

I don't see you using this as a base class, so it seems like this shouldn't be
virtual. Am I missing something?

[raymes, 2013/04/14 16:32:57]

Done.

+
+  // Construct a new PP_Var from the graph. All of the PP_Vars referenced by
+  // the returned PP_Var are also constructed. Each PP_Var created has a
+  // ref-count of at least one, plus the number of references to it in the
+  // graph.
+  PP_Var CreatePPVar(PP_Instance instance);
+
+  // Write the graph to a message using the given HandleWriter.
+  void Write(IPC::Message* m, const HandleWriter& handle_writer);
+  // Write the graph to a message using the default handle writer.
+  void Write(IPC::Message* m);
+
+  // Create a RawVarDataGraph from the given message.
+  static scoped_ptr<RawVarDataGraph> Read(const IPC::Message* m,
+                                          PickleIterator* iter);
+
+  // A list of the nodes in the graph.
+  ScopedVector<RawVarData> data_;
+};
+
+// Abstract base class for the data contained in a PP_Var.
+class RawVarData {
+ public:
+  virtual ~RawVarData();
+
+  // Create a PP_Var from the raw data contained in this object.
+  virtual PP_Var CreatePPVar(PP_Instance instance) = 0;
+  // Some PP_Vars may require 2-step initialization. For example, they may
+  // reference other PP_Vars which had not yet been created when |CreatePPVar|
+  // was called. The original var created with |CreatePPVar| is passed back in,
+  // along with the graph it is apart of to be initialized.

[dmichael (off chromium), 2013/04/12 22:40:38]

apart->a part

[raymes, 2013/04/14 16:32:57]

Done.

+  virtual void InitPPVar(const PP_Var& var,

[dmichael (off chromium), 2013/04/12 22:40:38]

If CreatePPVar returns |var|, it seems a little odd to pass it back in? Should
we store the scoped_refptr<Var> so we don't need that? Or have a Var out-param
(Var*)?

[raymes, 2013/04/14 16:32:57]

I debated about doing something like this be decided I would rather not store
temporary data in the object because i think it can cause confusion. I do think
the name is bad though and renamed the function to PopulatePPVar as you
suggested :)

+                         const std::vector<PP_Var>& graph) = 0;
+
+  // Writes the RawVarData to a message.
+  virtual void Write(IPC::Message* m,
+                     const HandleWriter& handle_writer) = 0;
+
+  // Represents a reference to another PP_Var. For example references can be
+  // held by array and dictionary PP_Vars.
+  struct VarReference {
+    PP_Var var;
+    // Whether or not the reference is valid (i.e. whether or not the |as_id|
+    // property points to a live var).
+    bool valid_var_ref;

[dmichael (off chromium), 2013/04/12 22:40:38]

Not sure we need this...  if any are invalid, maybe we should just bail? Also
doesn't make sense for value types.

[raymes, 2013/04/14 16:32:57]

Done - if there are any invalid vars in the graph, I now just bail.

+    // An index into the |data_| field of |RawVarData| denoting which node this
+    // var references.
+    uint32_t ref_id;
+  };
+};
+
+// A RawVarData class for PP_Vars which are value types.
+class BasicRawVarData : public RawVarData {
+ public:
+  BasicRawVarData(const PP_Var& var);
+  virtual ~BasicRawVarData();
+
+  // RawVarData implementation.
+  virtual PP_Var CreatePPVar(PP_Instance instance) OVERRIDE;
+  virtual void InitPPVar(const PP_Var& var,
+                         const std::vector<PP_Var>& graph) OVERRIDE;
+  virtual void Write(IPC::Message* m,
+                     const HandleWriter& handle_writer) OVERRIDE;
+
+  static BasicRawVarData* Read(PP_VarType type,
+                               const IPC::Message* m,
+                               PickleIterator* iter);
+
+ private:
+  PP_Var var_;
+};
+
+// A RawVarData class for string PP_Vars.
+class StringRawVarData : public RawVarData {
+ public:
+  StringRawVarData(const PP_Var& var);
+  StringRawVarData(bool valid_var_ref, const std::string& data);
+  virtual ~StringRawVarData();
+
+  // RawVarData implementation.
+  virtual PP_Var CreatePPVar(PP_Instance instance) OVERRIDE;
+  virtual void InitPPVar(const PP_Var& var,
+                         const std::vector<PP_Var>& graph) OVERRIDE;
+  virtual void Write(IPC::Message* m,
+                     const HandleWriter& handle_writer) OVERRIDE;
+
+  static StringRawVarData* Read(PP_VarType type,
+                                const IPC::Message* m,
+                                PickleIterator* iter);
+
+ private:
+  // Denotes whether the underlying PP_Var was a valid reference.
+  bool valid_var_ref_;
+  // The data in the string.
+  std::string data_;
+};
+
+// A RawVarData class for array buffer PP_Vars.
+class ArrayBufferRawVarData : public RawVarData {
+ public:
+  // Enum for array buffer message types.
+  enum ShmemType {
+    ARRAY_BUFFER_NO_SHMEM,
+    ARRAY_BUFFER_SHMEM_HOST,
+    ARRAY_BUFFER_SHMEM_PLUGIN,
+  };
+
+  ArrayBufferRawVarData(const PP_Var& var, PP_Instance instance);
+  ArrayBufferRawVarData(bool valid_var_ref, ShmemType type);
+  virtual ~ArrayBufferRawVarData();
+
+  // RawVarData implementation.
+  virtual PP_Var CreatePPVar(PP_Instance instance) OVERRIDE;
+  virtual void InitPPVar(const PP_Var& var,
+                         const std::vector<PP_Var>& graph) OVERRIDE;
+  virtual void Write(IPC::Message* m,
+                     const HandleWriter& handle_writer) OVERRIDE;
+
+  static ArrayBufferRawVarData* Read(PP_VarType type,
+                                     const IPC::Message* m,
+                                     PickleIterator* iter);
+
+ private:
+  bool valid_var_ref_;
+  // The type of the storage underlying the array buffer.
+  ShmemType type_;
+  // The data in the buffer. Valid for |type_| == ARRAY_BUFFER_NO_SHMEM.
+  std::string data_;

[dmichael (off chromium), 2013/04/12 22:40:38]

vector<uint8_t> seems more natural to me.

+  // Host shmem handle. Valid for |type_| == ARRAY_BUFFER_SHMEM_HOST.
+  int host_shm_handle_id_;
+  // Plugin shmem handle. Valid for |type_| == ARRAY_BUFFER_SHMEM_PLUGIN.
+  SerializedHandle plugin_shm_handle_;
+};
+
+// A RawVarData class for array PP_Vars.
+class ArrayRawVarData : public RawVarData {
+ public:
+  ArrayRawVarData(const PP_Var& var, const VarGraph& var_graph);
+  ArrayRawVarData(bool valid_var_ref,
+                  const std::vector<VarReference>& data);
+  virtual ~ArrayRawVarData();
+
+  // RawVarData implementation.
+  virtual PP_Var CreatePPVar(PP_Instance instance) OVERRIDE;
+  virtual void InitPPVar(const PP_Var& var,
+                         const std::vector<PP_Var>& graph) OVERRIDE;
+  virtual void Write(IPC::Message* m,
+                     const HandleWriter& handle_writer) OVERRIDE;
+
+  static ArrayRawVarData* Read(PP_VarType type,
+                               const IPC::Message* m,
+                               PickleIterator* iter);
+
+ private:
+  bool valid_var_ref_;
+  // A vector of the references representing the elements of the array.
+  std::vector<VarReference> data_;
+};
+
+// A RawVarData class for dictionary PP_Vars.
+class DictionaryRawVarData : public RawVarData {
+ public:
+  DictionaryRawVarData(const PP_Var& var, const VarGraph& graph);
+  DictionaryRawVarData(
+      bool valid_var_ref,
+      const std::vector<std::pair<std::string, VarReference> >& data);
+  virtual ~DictionaryRawVarData();
+
+  // RawVarData implementation.
+  virtual PP_Var CreatePPVar(PP_Instance instance) OVERRIDE;
+  virtual void InitPPVar(const PP_Var& var,
+                         const std::vector<PP_Var>& graph) OVERRIDE;
+  virtual void Write(IPC::Message* m,
+                     const HandleWriter& handle_writer) OVERRIDE;
+
+  static DictionaryRawVarData* Read(PP_VarType type,
+                                    const IPC::Message* m,
+                                    PickleIterator* iter);
+
+ private:
+  bool valid_var_ref_;
+  // A vector of the key/value reference pairs representing elements of the
+  // dictionary.
+  std::vector<std::pair<std::string, VarReference> > data_;
+};
+
+}  // namespace proxy
+}  // namespace ppapi
+
+#endif  // PPAPI_PROXY_RAW_VAR_DATA_H_