Expose external constructor for byte arrays. (#2579)

lib/bytes.toit

@@ -334,14 +334,14 @@ class Buffer extends BufferConsumer:
     // We copy the code of the 'with-initial-size' constructor, so we don't get
     // a deprecation warning.
     init-size_ = INITIAL-BUFFER-LENGTH_
-    buffer_ = init-size_ > MAX-INTERNAL-SIZE_ ? (ByteArray_.external_ init-size_) : (ByteArray init-size_)
+    buffer_ = init-size_ > MAX-INTERNAL-SIZE_ ? (ByteArray.external init-size_) : (ByteArray init-size_)
 
   /**
   Constructs a new buffer with the given $init-size_.
   If the $init-size_ isn't big enough, the buffer grows when necessary.
   */
   constructor.with-initial-size .init-size_/int:
-    buffer_ = init-size_ > MAX-INTERNAL-SIZE_ ? (ByteArray_.external_ init-size_) : (ByteArray init-size_)
+    buffer_ = init-size_ > MAX-INTERNAL-SIZE_ ? (ByteArray.external init-size_) : (ByteArray init-size_)
 
   /** See $BufferConsumer.size. */
   size -> int:

lib/core/collections.toit

@@ -1200,6 +1200,27 @@ interface ByteArray extends io.Data:
     bytes.write-to-byte-array result --at=0 from to
     return result
 
+  /**
+  Constructs a byte array where the data is not on the Toit heap.
+
+  The byte array's backing store is allocated using 'malloc' and is thus
+    not located on the Toit heap. This has the following consequences:
+  - The garbage collector can't move the data, which can lead to fragmentation.
+  - External byte arrays can be handed over to the system. The system would
+    then "neuter" the byte array, rendering it unusable in Toit. This can
+    be useful for performance reasons, as can sometimes avoid copying the data.
+    Only few functions neuter byte arrays and typically only on request.
+
+  External byte arrays are not automatically faster than normal byte arrays.
+    Unless you know what you are doing or have a specific use-case in mind,
+    you should use normal byte arrays.
+
+  Note: bigger byte arrays are always external, even if allocated using
+    the normal $(constructor size).
+  */
+  constructor.external size/int:
+    #primitive.core.byte-array-new-external
+
   /**
   The number of bytes in this instance.
   */
@@ -1643,6 +1664,7 @@ class ByteArray_ extends ByteArrayBase_:
   constructor size/int --filler/int=0:
     #primitive.core.byte-array-new
 
+  /** Deprecated. Use $(ByteArray.external size) instead. */
   constructor.external_ size/int:
     #primitive.core.byte-array-new-external
 

tests/esp32/ble3-shared.toit

@@ -115,7 +115,7 @@ main-central:
   task::
     i := 0
     while not done:
-      ba := ByteArray_.external_ 100
+      ba := ByteArray.external 100
       keep-alive[i % keep-alive.size] = ba
       ByteArray 10
       yield

tests/serialization-test.toit

@@ -60,7 +60,7 @@ main:
 class Unserializable:
 
 test-throwing-process-send:
-  l := List 10: ByteArray_.external_ 100
+  l := List 10: ByteArray.external 100
   expect-throw "TOO_MANY_EXTERNALS": process-send_ 0 0 l
   expect-not (process-send_ 100000000 -10 #[])
   l = []