Allocate a Dart_CMessage structure when decoding a message into C structures

runtime/include/dart_api.h

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #ifndef INCLUDE_DART_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 1345 matching lines @@
 
 // External pprof support for gathering and dumping symbolic
 // information that can be used for better profile reports for
 // dynamically generated code.
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 // --- Message encoding/decoding ----
 
 /**
+ * A memory allocation function.
+ *
+ * Allocate a new piece of memory or change the size (ra-allocates) of
+ * a previously allocated piece of memory.
+ *
+ * \param ptr NULL for new allocation and pointer to a previously
+ *   allocated piece of memory for re-allocation.
+ * \param old_size 0 for new allocation and size of previously allocated
+ *   piece of memory for re-allocation.
+ * \param new_size
+ *
+ * \return Address of newly allocated or re-allocated piece of
+ *   memory of size new_size. NULL if allocation fails.
+ */
+typedef uint8_t* (*Allocator)(uint8_t* ptr,
+                              intptr_t old_size,
+                              intptr_t new_size);
+
+/**
  * A Dart_CObject is used for representing Dart objects as native C
  * data outside the Dart heap. These objects are totally detached from
  * the Dart heap. Only a subset of the Dart objects have a
  * representation as a Dart_CObject.
  */
 struct Dart_CObject {
   enum Type {
     kNull = 0,
     kBool,
     kInt32,
@@ skipping 12 matching lines @@
       int length;
       Dart_CObject** values;
     } as_array;
   } value;
 };
 
 /**
  * A Dart_CMessage is used for encoding and decoding messages from native code.
  */
 struct Dart_CMessage {
-  Dart_CObject** message;
+  Dart_CObject* object;
+  intptr_t allocated_length;
+  Dart_CObject** allocated;

[siva, 2012/02/01 01:48:36]

Do we need the allocated and allocated_length fields in this strucuture.
If we use the native handler callback API provided by Todd and allow the message
handler loop to free up the allocated CMessage objects (using some kind of zone
allocator) this part would be a lot simpler.

[Søren Gjesse, 2012/02/01 12:12:23]

We don't need it if we decide to handle the decoding and allocation/freeing
inside the VM.

+  uint8_t* original_message;
+  intptr_t original_message_length;

[siva, 2012/02/01 01:48:36]

Do we need the original message and length etc. over here?

[Søren Gjesse, 2012/02/01 12:12:23]

The reason they are here is that if we allow for the Dart_CObject structures to
point back into the original message (e.g. for large byte arrays) and the
embedder is responsible for freeing this structure then there need to be a
pointer to the original message which needs to be freed as well.

Maybe that makes it all too complicated for now.

 };
 
+/**
+ * Decodes a Dart message into a Dart_CMessage structure.
+ *
+ * \param message Pointer to the raw encoded message.
+ * \param length Length of the raw encoded message.
+ * \param allocator The memory allocation function to use to allocate
+ *   the Dart_CMessage structure and the Dart_CObject structures making
+ *   up the decoded message. If NULL is passed standard stdlib
+ *   malloc/realloc/free is used.
+ */
+
+DART_EXPORT Dart_CMessage* Dart_DecodeMessage(uint8_t* message,
+                                              intptr_t length,
+                                              Allocator allocator);

[turnidge, 2012/01/31 22:20:42]

Do we need this to be a public api?  If the Dart_NativePortHandler function
takes a Dart_CMessage as an argument, then the decoding, allocation, and
deallocation would happen internally in the vm.

[siva, 2012/02/01 01:48:36]

I agree with Todd, the native message handler could be made to take the decoded
CMessage object and the message loop would do the deserialization of the
message.

[Søren Gjesse, 2012/02/01 12:12:23]

Maybe we don't. We could start out with delivering decoded messages with their
lifetime controlled by the VM. However that require that the receiver of a
decoded message does not keep around pointers but copies any data needed across
calls.

[Søren Gjesse, 2012/02/01 12:12:23]

I am fine with this - we can always add embedder controlled decoding later if
required.

+// TODO(sgjesse): Remove length parameter if that is part of the
+// message header.
+// TODO(sgjesse): Should this function have flags for:
+//   Don't fill in allocated (caller uses zone like allocation)
+//   Don't Never point into original_message for e.g. byte arrays.
+
 #endif  // INCLUDE_DART_API_H_