firefly-compiler 0.5.39 → 0.5.40

package/fireflysite/assets/markdown/reference/StructuredConcurrency.md

@@ -1,99 +1,99 @@
-# Structured concurrency
-
-Firefly has a lightweight task system that supports structured concurrency and cancellation. 
-
-Tasks are structured in a parent-child relationship, where the parent scope waits for all its child tasks to complete before proceeding.
-
-If the parent task or a sibling subtask fails with an uncaught exception, the other subtasks are cancelled.
-
-
-# Waiting for results
-
-A simple use case is to concurrently run some tasks and waiting for their results.
-This can be done without explicitly spawning tasks, as there's a utility method `task.mapList()` for this:
-
-```firefly
-let results = system.mainTask().mapList(urls) {url =>
-    system.httpClient().get(url) {_.readText()}
-}
-```
-
-This fetches all of the URLs concurrently. 
-If any fetch throws an exception, the other fetches are cancelled and `task.mapList()` rethrows an exception. 
-Otherwise, the list of results is returned.
-
-Similarly, `task.raceList()` can be used to run some tasks concurrently, wait for the first one to complete, and cancel the others.
-
-
-# Spawning tasks
-
-A slightly more advanced use case is handling requests concurrently. It might look like this:
-
-```firefly
-while {True} {
-    let request = waitForRequest()
-    system.mainTask().spawn {subtask =>
-        handleRequest(subtask, request)
-    }
-}
-```
-
-The infinite loop here calls some function to wait for the next request.
-Then it spawns a subtask to handle the request, and loops back to waiting for the next request.
-The subtask executes concurrently, and thus doesn't block the loop while the request is being handled.
-
-
-# Channels
-
-Concurrently running tasks may need to communicate while executing.
-One mechanism for inter-task communication is the `Channel[T]` type, which represents an unbuffered multi-producer multi-consumer channel for messages of type `T`.
-
-A function to read URLs from a channel, fetch JSON from those URLs, and write the results to another channel could look like this:
-
-```firefly
-fetchTask(in: Channel[String], out: Channel[Json]) {
-    while {True} {
-        let url = in.read()
-        let result = system.httpClient().get(url) {_.readJson()}
-        out.write(result)
-    }
-}
-```
-
-The `in.read()` call waits until there's a task ready to write to the `in` channel.
-Similarly, the `out.write()` call waits until there's a task ready to read from the `out` channel.
-
-To do multiple requests concurrently, spawn multiple instances of the task:
-
-```firefly
-let in = system.mainTask().channel()
-let out = system.mainTask().channel()
-1.to(3).each {_ => 
-    system.mainTask().spawn {_ =>
-        fetchTask(in, out)
-    }
-}
-```
-
-Consider calling an API that either returns `{value: ...}` where `...` is some number, or `{add: ...}` where `...` is a list of API URLs to add up to a total.
-A first attempt could be adding the following code:
-
-```firefly
-mutable total = 0
-in.write("https://example.com/my-api")
-while {True} {
-    let json = out.read()
-    json.field("value").map {total += _.grabInt()}.else {
-        let urls = json.field("add").map {_.grabArray().map {_.grabString()}}
-        urls.each {url =>
-            in.write(url)
-        }
-    }
-}
-```
-
-However, there are two problems here:
-
- * If all the fetch tasks are waiting to write to the `out` channel, `in.write(url)` will block forever.
- * There's no logic to discover that there are no API calls left to do, so the `total` will never be reported.
- 
+# Structured concurrency
+
+Firefly has a lightweight task system that supports structured concurrency and cancellation. 
+
+Tasks are structured in a parent-child relationship, where the parent scope waits for all its child tasks to complete before proceeding.
+
+If the parent task or a sibling subtask fails with an uncaught exception, the other subtasks are cancelled.
+
+
+# Waiting for results
+
+A simple use case is to concurrently run some tasks and waiting for their results.
+This can be done without explicitly spawning tasks, as there's a utility method `task.mapList()` for this:
+
+```firefly
+let results = system.mainTask().mapList(urls) {url =>
+    system.httpClient().get(url) {_.readText()}
+}
+```
+
+This fetches all of the URLs concurrently. 
+If any fetch throws an exception, the other fetches are cancelled and `task.mapList()` rethrows an exception. 
+Otherwise, the list of results is returned.
+
+Similarly, `task.raceList()` can be used to run some tasks concurrently, wait for the first one to complete, and cancel the others.
+
+
+# Spawning tasks
+
+A slightly more advanced use case is handling requests concurrently. It might look like this:
+
+```firefly
+while {True} {
+    let request = waitForRequest()
+    system.mainTask().spawn {subtask =>
+        handleRequest(subtask, request)
+    }
+}
+```
+
+The infinite loop here calls some function to wait for the next request.
+Then it spawns a subtask to handle the request, and loops back to waiting for the next request.
+The subtask executes concurrently, and thus doesn't block the loop while the request is being handled.
+
+
+# Channels
+
+Concurrently running tasks may need to communicate while executing.
+One mechanism for inter-task communication is the `Channel[T]` type, which represents an unbuffered multi-producer multi-consumer channel for messages of type `T`.
+
+A function to read URLs from a channel, fetch JSON from those URLs, and write the results to another channel could look like this:
+
+```firefly
+fetchTask(in: Channel[String], out: Channel[Json]) {
+    while {True} {
+        let url = in.read()
+        let result = system.httpClient().get(url) {_.readJson()}
+        out.write(result)
+    }
+}
+```
+
+The `in.read()` call waits until there's a task ready to write to the `in` channel.
+Similarly, the `out.write()` call waits until there's a task ready to read from the `out` channel.
+
+To do multiple requests concurrently, spawn multiple instances of the task:
+
+```firefly
+let in = system.mainTask().channel()
+let out = system.mainTask().channel()
+1.to(3).each {_ => 
+    system.mainTask().spawn {_ =>
+        fetchTask(in, out)
+    }
+}
+```
+
+Consider calling an API that either returns `{value: ...}` where `...` is some number, or `{add: ...}` where `...` is a list of API URLs to add up to a total.
+A first attempt could be adding the following code:
+
+```firefly
+mutable total = 0
+in.write("https://example.com/my-api")
+while {True} {
+    let json = out.read()
+    json.field("value").map {total += _.grabInt()}.else {
+        let urls = json.field("add").map {_.grabArray().map {_.grabString()}}
+        urls.each {url =>
+            in.write(url)
+        }
+    }
+}
+```
+
+However, there are two problems here:
+
+ * If all the fetch tasks are waiting to write to the `out` channel, `in.write(url)` will block forever.
+ * There's no logic to discover that there are no API calls left to do, so the `total` will never be reported.
+ 

package/fireflysite/assets/markdown/reference/TraitsAndInstances.md

@@ -1,100 +1,100 @@
-# Traits and instances
-
-A trait defines an open set of types that support a common set of functions. 
-For example, here's a trait for shapes with a common function to compute the area:
-
-```firefly
-trait T: Shape {
-    area(shape: T): Float
-}
-```
-
-The function becomes a top level function `area[T: Shape](shape: T): Float`.
-Here `T` is a bounded type parameter: It can only be instantiated to a type that has an instance of the `Shape` trait.
-
-Consider these two types that would be good candidates for having an instance of the `Shape` trait:
-
-```firefly
-data Circle(radius: Float)
-data Rectangle(width: Float, height: Float)
-```
-
-Only types defined with the `data` or `newtype` keyword can have trait instances.
-
-Instances for these types can be created with the `instance` keyword as follows:
-
-```firefly
-instance Circle: Shape {
-    area(shape: Circle): Float {
-        Float.pi() * (shape.radius ^ 2.0)
-    }
-}
-
-instance Rectangle: Shape {
-    area(shape: Rectangle): Float {
-        shape.width * shape.height
-    }
-}
-```
-
-Each instance provides an implementation of `area` specific to the type.
-
-Here's an example of how to define a normal top level function with a bounded type parameter:
-
-```firefly
-printArea[T: Shape](shape: T) {
-    Log.trace("Area: " + area(shape))
-}
-
-printArea(Circle(0.0))          // Prints "Area: 0"
-printArea(Rectangle(5.0, 6.0))  // Prints "Area: 30"
-```
-
-Multiple bounds are separated by colons, e.g. `foo[T: Bar: Baz]` means that `T` must have instances for both `Bar` and `Baz`.
-
-
-# Traits with type parameters
-
-Traits can have type parameters:
-
-```firefly
-trait I: Rpc[O] {}
-
-instance MyMessage: Rpc[Int] {}
-```
-
-The choice of `I` fully determines `O` - in this case, if `I` is `MyMessage`, then `O` is `Int`.
-
-
-# Automatic traits
-
-If instances for the following traits are not explicitly defined, they will be generated automatically.
-This only applies to types defined with the `data` or `newtype` keyword.
-
-```firefly
-// Used for == !=
-trait T: Equal {
-    equals(x: T, y: T): Bool
-}
-
-// Used for < > <= >= and sorting
-trait T: Order {
-    compare(x: T, y: T): Ordering
-}
-
-// Used to display values for debugging
-trait T: Show {
-    show(value: T): String
-}
-
-// Used for binary serialization
-trait T: Serializable {
-    serializeUsing(serialization: Serialization, value: T): Unit
-    deserializeUsing(serialization: Serialization): T
-}
-
-// Used for throwing and catching exceptions
-trait T: HasAnyTag {
-    anyTag(): AnyTag[T]
-}
-```
+# Traits and instances
+
+A trait defines an open set of types that support a common set of functions. 
+For example, here's a trait for shapes with a common function to compute the area:
+
+```firefly
+trait T: Shape {
+    area(shape: T): Float
+}
+```
+
+The function becomes a top level function `area[T: Shape](shape: T): Float`.
+Here `T` is a bounded type parameter: It can only be instantiated to a type that has an instance of the `Shape` trait.
+
+Consider these two types that would be good candidates for having an instance of the `Shape` trait:
+
+```firefly
+data Circle(radius: Float)
+data Rectangle(width: Float, height: Float)
+```
+
+Only types defined with the `data` or `newtype` keyword can have trait instances.
+
+Instances for these types can be created with the `instance` keyword as follows:
+
+```firefly
+instance Circle: Shape {
+    area(shape: Circle): Float {
+        Float.pi() * (shape.radius ^ 2.0)
+    }
+}
+
+instance Rectangle: Shape {
+    area(shape: Rectangle): Float {
+        shape.width * shape.height
+    }
+}
+```
+
+Each instance provides an implementation of `area` specific to the type.
+
+Here's an example of how to define a normal top level function with a bounded type parameter:
+
+```firefly
+printArea[T: Shape](shape: T) {
+    Log.trace("Area: " + area(shape))
+}
+
+printArea(Circle(0.0))          // Prints "Area: 0"
+printArea(Rectangle(5.0, 6.0))  // Prints "Area: 30"
+```
+
+Multiple bounds are separated by colons, e.g. `foo[T: Bar: Baz]` means that `T` must have instances for both `Bar` and `Baz`.
+
+
+# Traits with type parameters
+
+Traits can have type parameters:
+
+```firefly
+trait I: Rpc[O] {}
+
+instance MyMessage: Rpc[Int] {}
+```
+
+The choice of `I` fully determines `O` - in this case, if `I` is `MyMessage`, then `O` is `Int`.
+
+
+# Automatic traits
+
+If instances for the following traits are not explicitly defined, they will be generated automatically.
+This only applies to types defined with the `data` or `newtype` keyword.
+
+```firefly
+// Used for == !=
+trait T: Equal {
+    equals(x: T, y: T): Bool
+}
+
+// Used for < > <= >= and sorting
+trait T: Order {
+    compare(x: T, y: T): Ordering
+}
+
+// Used to display values for debugging
+trait T: Show {
+    show(value: T): String
+}
+
+// Used for binary serialization
+trait T: Serializable {
+    serializeUsing(serialization: Serialization, value: T): Unit
+    deserializeUsing(serialization: Serialization): T
+}
+
+// Used for throwing and catching exceptions
+trait T: HasAnyTag {
+    anyTag(): AnyTag[T]
+}
+```