- Add functionality to morph a string into an external string

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 1465 matching lines @@
  * \param length Used to pass in the length of the provided array.
  *   Used to return the length of the array which was actually used.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringToUTF16(Dart_Handle str,
                                            uint16_t* utf16_array,
                                            intptr_t* length);
 
 
+/**
+ * Converts a String into an ExternalString.

[Anton Muhin, 2012/11/07 10:05:46]

From the documentation and a signature it's not obvious that this function
morphs existing string into externalize one.

And another possibly handy thing: V8 API can refuse to externalize the string. 
Originally it was necessary on x64 as very short strings cannot be externalized.
 Later it was abused to tweak externalization policy: oftentimes it's useless to
externalize very young strings as we do not know if they go away soon or not.

[siva, 2012/11/07 21:43:27]

I am assuming converts means it morphs the existing object. I can add a line in
the description making that explicit.
I am not sure I understand the need to refuse externalization. We don't have the
issue that V8 had with regards to short strings as we always align all objects
and
the external data is just one word long in the object.

The embedder should decide whether to externalize or
not externalize a string. Once called I would think the
string should be externalized.

[Anton Muhin, 2012/11/08 08:05:29]

Up to you, Siva.
That was an optimisation and it was implemented in VM as it's only VM which can
understand if the string is young enough.

The simplified version of the code which lead to this optimisation is roughly:

for (int i = 0; i < BIG_NUMBER; i++) {
  String s = '............ $i';
  dom_call_with_string_conversion(s);
}

Originally v8 externalized all those short-lived strings which has its price as
externalization is not very cheap. The problem is bindings cannnot understand if
JS string is a very young or not.  So Vitaly implemented an heuristics which
checked how young string is (by looking where in new space it has been
allocated---if it's too close to top, it's considered to be too young) and
refused to externalize such strings.

That's heuristics, not mandatory, but we may want to leave a room for it.

Again, up to you to decide.

[Ivan Posva, 2012/11/08 08:50:47]

Anton, the reason I think this "optimization" paid off in V8 is due to the fact
that weak handles were only handled during an old collection. The weak handles
for StringImpls should not be participating in grouping, so we can collect them
during new collections as well. Although I understand that there is an
additional benefit in your example of skipping the weak handle creation in the
first place.

[Anton Muhin, 2012/11/08 08:56:08]

I am not quite sure---if memory serves V8 was always able to collect external
strings in minor GC.  My, but not 100% sure, recollections are this was due to
all this additinal overhead of allocating external resource wrapper + another V8
API call, etc.

Again, I don't suggest to implement this immediately, I only want to point out
it might be useful to have a room for this optimisation later on.

And, no, I am not insisting.

On 2012/11/08 08:50:47, Ivan Posva wrote:

+ *
+ * \param array External space into which the string data will be
+ *   copied into. This must not move.
+ * \param length The length of the provided space.
+ * \param peer An external pointer to associate with this string.
+ * \param cback A callback to be called when this string is finalized.
+ *
+ * \return the converted ExternalString object if no error occurs.
+ *   Otherwise returns an error handle.
+ */
+DART_EXPORT Dart_Handle Dart_MakeExternalString(Dart_Handle str,
+                                                void* array,
+                                                intptr_t length,

[Anton Muhin, 2012/11/07 10:05:46]

how embedder can find out this length?

[siva, 2012/11/07 21:43:27]

This is the length of array passed in by the embedder.
Since it creates the external space it would know the length.

It can try and figure an appropriate length to be used by
looking at Dart_StringLength and the type of the string
(ascii or not).


On 2012/11/07 10:05:46, Anton Muhin wrote:

[Anton Muhin, 2012/11/08 08:05:29]

I might be missing something, sorry if it's the case.

I meant that I found no embedder's API call to find out exact size of the
storage into which internal representation of VM string will fit.

Yes, there is _IsAscii, but it's to some extent leaking internal implementation
to assume optimal_length = Dart_IsAscii ? Dart_StringLength : 2 *
Dart_StringLength.

As an example, when 32 bits per code point were dropped, it might have affected
calculations.

May we add a helper function to find out required length?

Or do it in v8 way and allow the embedder to control internal representation of
the string?

On 2012/11/07 21:43:27, siva wrote:

[siva, 2012/11/09 02:55:06]

Added an API function to determine the storage size of
a string.

On 2012/11/08 08:05:29, Anton Muhin wrote:

+                                                void* peer,
+                                                Dart_PeerFinalizer cback);
+
+
 // --- Lists ---
 
 /**
  * Is this object a List?
  */
 DART_EXPORT bool Dart_IsList(Dart_Handle object);
 
 /**
  * Returns a List of the desired length.
  *
@@ skipping 1234 matching lines @@
  *
  * \param object An object.
  * \param peer A value to store in the peer field.
  *
  * \return Returns an error if 'object' is a subtype of Null, num, or
  *   bool.
  */
 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
 
 #endif  // INCLUDE_DART_API_H_